AutoGen چیست و «اجرای کد» چرا قلب معماری agentic است؟
AutoGen فریمورک متنباز مایکروسافت برای ساخت برنامههای چند-عاملی (Multi-Agent) است؛ جایی که چند «عامل گفتوگو-پذیر» (Conversable Agent) وظیفه را با مکالمه حل میکنند. هر عامل میتواند به LLM وصل باشد، ابزار اجرا کند یا نقش یک کاربر انسانی را بازی کند. اما چیزی که AutoGen را از یک چتبات ساده جدا میکند، همین بخش سوم است: عاملهایی که کد را «اجرا» میکنند، نه فقط «پیشنهاد».
معماری اجرای کد در AutoGen چطور کار میکند؟
در معماری اجرای کد، دو نقش کاملاً تفکیک شدهاند: عامل مبتنی بر LLM که «تصمیم میگیرد چه کدی لازم است» و عامل مجری که «فقط اجرا میکند». عامل مجری هنگام دریافت پیام، بلاکهای کد مشخصشده با زبان (مثل ```python یا ```sh) را پیدا میکند، هر بلاک را در یک فایل در work_dir مینویسد، آن را در زیر-پروسه یا کانتینر اجرا میکند و خروجی کنسول را بهعنوان پاسخ برمیگرداند. این جداسازی یعنی میتوانید مجری را بدون یک ریال هزینهٔ توکن راه بیندازید.
- 1
استخراج بلاک کد
مجری متن پیام را برای بلاکهای کد با مشخصکنندهٔ زبان (python، bash، sh و...) جستوجو میکند و هر بلاک را جدا میکند.
- 2
نوشتن در work_dir
هر بلاک در فایلی موقت (مثل tmp_code_*.py) داخل پوشهٔ کاری تعیینشده ذخیره میشود تا قابل ردیابی باشد.
- 3
اجرا در محیط ایزوله یا لوکال
فایل کد در زیر-پروسهٔ شِل (لوکال) یا داخل کانتینر Docker اجرا میشود؛ timeout برای جلوگیری از حلقههای بیپایان اعمال میشود.
- 4
جمعآوری خروجی
stdout و stderr اجرا (خروجی کنسول، خطاها و exit_code) جمعآوری میشود؛ exit_code صفر یعنی موفقیت.
- 5
بازگشت نتیجه به مکالمه
خروجی بهعنوان پیام جدید به عامل کدنویس برمیگردد و چرخه تکرار میشود تا وظیفه حل شود یا شرط خاتمه فعال شود.
| Executor | محیط اجرا | بسته / مسیر import | کاربرد پیشنهادی |
|---|---|---|---|
| LocalCommandLineCodeExecutor | شِل سیستم میزبان | autogen-ext.code_executors.local (۰.۴+) / autogen.coding (۰.۲) | تست و توسعهٔ سریع؛ فقط کد قابلاعتماد |
| DockerCommandLineCodeExecutor | کانتینر Docker | autogen-ext.code_executors.docker | production و کد غیرقابلاعتماد؛ ایزوله کامل |
| JupyterCodeExecutor | کرنل Jupyter (مثل python3) | autogen-ext.code_executors.jupyter | نوتبوک، نمودار و دادههای interactive |
| ACADynamicSessionsCodeExecutor | Azure Container Apps | autogen-ext.code_executors.azure | اجرا در ابر بدون مدیریت کانتینر |
چطور AutoGen را نصب و محیط را آماده کنم؟
قبل از هر کاری سه چیز لازم دارید: پایتون ۳.۱۰ یا بالاتر، یک محیط مجازی تمیز، و کلید API از پنل APX24. نسخهٔ ۰.۴+ معماری ماژولار دارد؛ بستهٔ اصلی رفتار عاملها را میدهد (autogen-agentchat) و اکستنشنها — از جمله کلاینت مدل OpenAI و executors — در بستهٔ جداگانهٔ autogen-ext منتشر میشوند. اگر اجرای ایزوله میخواهید، Docker Desktop را هم از قبل بالا بیاورید تا بعداً خطای اتصال daemon نگیرید.
- Python 3.10+ نصب و در PATH است.
- محیط مجازی فعال است (python -m venv .venv && source .venv/bin/activate).
- کلید API از مسیر کلیدهای API در پنل APX24 ساخته شده و حساب اعتبار دارد.
- Docker Desktop در حال اجراست (فقط برای بخش Docker الزامی است).
- curl یا یک REST client برای تست اولیهٔ اتصال در دسترس است.
چطور AutoGen را به API هوش مصنوعی APX24 وصل کنم؟
لایهٔ مدل در AutoGen نسخهٔ ۰.۴+ از طریق کلاس OpenAIChatCompletionClient کار میکند که با هر API سازگار با OpenAI (OpenAI-compatible) حرف میزند — و APX24 دقیقاً همین استاندارد را در مسیر /v1 ارائه میدهد. دو نکته حیاتی است: اول، base_url باید به https://api.apx24.ir/v1 اشاره کند؛ دوم، چون نام مدل (مثل claude-sonnet-5) جزو مدلهای شناختهشدهٔ داخلی AutoGen نیست، باید قابلیتهایش را صریح در model_info اعلام کنید وگرنه فریمورک نمیداند مدل شما function calling دارد یا نه.
در AutoGen نسخهٔ ۰.۲ چطور کد تولیدشده را اجرا کنم؟
نسخهٔ ۰.۲ هنوز در بسیاری از پروژهها و آموزشها زنده است، پس ارزش میفهمیدن دارد. در این نسل، قابلیت اجرای کد یک پیکربندی داخل خود عامل است: هر عامل گفتوگو-پذیر (ConversableAgent و زیرکلاسهایش مثل UserProxyAgent) با code_execution_config به یک executor وصل میشود. عاملِ مجری را با llm_config=False بسازید تا هیچ توکنی مصرف نکند و در جواب هر پیام حاوی کد، خروجی اجرا را برگرداند.
در نسخهٔ ۰.۴+ چطور CodeExecutorAgent را مستقل اجرا کنم؟
در نسخهٔ ۰.۴+ اجرای کد از «پیکربندی داخل عامل» به یک عامل مستقل با نام CodeExecutorAgent ارتقا یافته است: عکسی که model_client ندارد و تنها کارش اجرای بلاکهای کد داخل پیامهای دریافتی است. این جداسازی دو مزیت دارد: اول، میتوانید بدون هیچ LLM و توکنی، رفتار executor را دقیق تست کنید؛ دوم، در تیمهای چند-عاملی فقط کافی است این عامل را کنار عامل کدنویس بگذارید.
چطور یک تیم دو-عاملی بسازم که کد بنویسد و خودش اجرا و اصلاح کند؟
حالا دو قطعهای که ساختیم را کنار هم میگذاریم: عامل کدنویس (با مغز APX24) و عامل مجری (با کانتینر Docker). تیم RoundRobin نوبتی حرف میزند؛ کدنویس بلاک کد میفرستد، مجری اجرا میکند و نتیجه را برمیگرداند، و کدنویس اگر خطا ببیند کد اصلاحشده میفرستد. شرط خاتمهٔ TextMentionTermination("TERMINATE") چرخه را وقتی تمام میکند که مدل خودش اعلام کند کار تمام است.
خطاهای رایج اجرای کد در AutoGen و راهحل هر کدام چیست؟
۹۰٪ مشکلات اجرای کد در AutoGen به چهار ریشه برمیگردد: Docker در حال اجرا نیست، پوشهٔ work_dir وجود ندارد، کلید API یا اعتبار مشکل دارد، یا نرخ فراخوانی محدود شده. هر کدام را با پیام خطای واقعی، کد رفع و راهکار پیشگیری میبینید — این بخش را bookmark کنید؛ در روزهای اول با آن زیاد برخورد میکنید.
کدام مدل APX24 برای عامل کدنویس مناسبتر است و هزینه چقدر میشود؟
برای تیم کدنویس-مجری، انتخاب مدل مستقیماً روی دو چیز اثر میگذارد: کیفیت چرخهٔ اصلاح خطا و فاکتور نهایی. هر دور مکالمه کل تاریخچه را دوباره به مدل میفرستد؛ پس در جریان agentic هزینهٔ توکن ورودی چند برابر یک چت ساده است. قانون انگشتی تحریریه: برای وظایف حساس تولید کد، مدل قویِ فراخوانی-تابعمحور؛ برای حجم زیادِ وظایف ساده، مدل اقتصادی — و در صورت امکان، ترکیب هر دو در یک معماری مسیریابی.
| مدل | توکن ورودی روزانه | توکن خروجی روزانه | هزینهٔ هر وظیفه | هزینهٔ روزانه | هزینهٔ ماهانه (۳۰ روز) |
|---|---|---|---|---|---|
| claude-sonnet-5 | ۶M | ۰.۸M | ≈ ۱۶٬۲۰۰ تومان | ۱٬۶۲۰٬۰۰۰ تومان | ۴۸٬۶۰۰٬۰۰۰ تومان |
| deepseek-v4-pro | ۶M | ۰.۸M | ≈ ۵٬۹۸۸ تومان | ۵۹۸٬۷۵۲ تومان | ۱۷٬۹۶۲٬۵۶۰ تومان |
نکات production برای اجرای امن و مقیاسپذیر کد چیست؟
تفاوت دمو و محصول در همین بخش است. یک تیم agentic در production باید سه چیز را تضمین کند: امنیت اجرا (کد مدل هرگز با مجوز کامل میزبان ناجست)، ثبات منابع (کانتینرها بسته شوند، timeoutها فعال بمانند) و قابلیت پیشبینی هزینه (سقف پیام، کش و مانیتورینگ usage). چکلیست زیر را بهعنوان ستون فقرات code review خودتان بگذارید.
- اجرا فقط در DockerCommandLineCodeExecutor (یا ACA) انجام شود؛ LocalCommandLineCodeExecutor فقط روی لپتاپ توسعهدهنده.
- همیشه timeout فعال باشد؛ کد تولیدشدهٔ مدل میتواند حلقهٔ بینهایت داشته باشد.
- سقف مکالمه: ترکیب TextMentionTermination با MaxMessageTermination تا هزینه و نرخ کنترل شود.
- کلید API فقط از متغیر محیطی/سرویس secret خوانده شود؛ هرگز در لاگ یا کد چاپ نشود.
- usage هر فراخوانی (prompt_tokens/completion_tokens) لاگ و به داشبورد هزینه فرستاده شود.
- work_dir مشخص و gitignore شده؛ فایلهای کد تولیدی قدیمی بهصورت دورهای پاک شوند.
- پیام سیستم هر عامل minimal و دقیق نگه داشته شود — هر توکن پیام سیستم در «هر دور» دوباره پرداخت میشود.
- نسخهٔ بستهها (autogen-agentchat / autogen-ext) در requirements قفل شود؛ آپدیتهای major را در staging تست کنید.





