زمینه
میخواستم قدرت کامل یک ایجنت هوش مصنوعی — نه فقط یک پنجرهٔ چت — از روی گوشی در دسترسم باشد. نتیجه، یک ربات تلگرامی self-hosted است بر پایهٔ Claude Agent SDK؛ همان runtime ایجنتی که پشت Claude Code قرار دارد. این ربات متن، پیام صوتی، عکس و ویدیو را میپذیرد، به ایجنت اجازه میدهد رسانه را واقعاً با ابزارهای محلی پردازش کند و هر فایلی را که ایجنت تولید میکند مستقیم به چت برمیگرداند.
مسئله
بیشتر رباتهای چت در حد متن میمانند. بخش جذاب مهندسی از جایی شروع میشود که مکالمه شامل رسانه باشد و مدل به راهی برای برگرداندن نتیجه نیاز داشته باشد: متنِ یک پیام صوتی، تصویر ویرایششده یا فریمی که از ویدیو استخراج شده. این یعنی یک پایپلاین واقعی در هر دو سوی مدل — نه فقط یک فراخوانی API.
معماری
- یک شنوندهٔ long-polling تلگرام، پیامها را دریافت و به ورودی ایجنت تبدیل میکند.
- رسانهٔ ورودی در پوشهٔ محلی
media/ذخیره میشود و مسیر فایل به ایجنت داده میشود — Claude تصاویر را مستقیم میبیند و برای پردازش از ابزارهای خط فرمان (ffmpeg، ImageMagick) استفاده میکند. - پیامهای صوتی پیش از ورود به مکالمه با ElevenLabs Scribe به متن تبدیل میشوند.
- یک ابزار MCP درونپردازشی به نام
send_mediaراهی صریح و قطعی به ایجنت میدهد تا هر فایل تولیدشده را به چت بفرستد — بدون تجزیهٔ شکنندهٔ خروجی مدل برای پیدا کردن مسیر فایلها. - یک نشست (session) پایدار، زمینهٔ گفتوگو را بین پیامها حفظ میکند و دستور
/newآن را از نو میسازد.
تصمیمهای فنی قابلتوجه
- مسیر بازگشت با «ابزار»، نه با «قرارداد». تعریف
send_mediaبهعنوان ابزار MCP یعنی رفتار سیستم قطعی میماند: ایجنت وقتی میخواهد فایلی تحویل دهد آن را فراخوانی میکند، بهجای آنکه میزبان از دل متن حدس بزند. - بازخورد فوری. ربات بلافاصله پیام «Thinking…» میفرستد و بعد همان پیام را در جا ویرایش میکند — جزئیات کوچکی که پاسخهای طولانی ایجنت را سریع و روان جلوه میدهد.
- قفل تککاربره. رباتی که به shell دسترسی دارد نباید به غریبهها سرویس بدهد: فقط شناسهٔ چت مالک پاسخ میگیرد و باقی نادیده گرفته میشوند.
- کنترل در زمان اجرا. دستور
/modelبا دکمههای inline بین مدلهای Claude جابهجا میشود و/modeحالت مجوزهای ایجنت را تغییر میدهد. - قابل حمل. روی macOS، لینوکس و ویندوز اجرا میشود و پیکربندی Docker هم دارد.
چه چیزی را نشان میدهد
همان الگویی که بهصورت حرفهای ساختهام — ربات تلگرامی در جلوی یک پایپلاین داده — این بار با یک ایجنت هوش مصنوعی در مرکز: هماهنگسازی ایجنت، طراحی ابزار MCP، پردازش رسانه و جزئیات عملیاتی (نشستها، مجوزها، قفلهای ایمنی) که استفادهٔ روزمره از ایجنت را ممکن میکنند.