AutoGen چیست و چت گروهی چه مشکلی را حل میکند؟
AutoGen فریمورک متنباز مایکروسافت برای ساخت اپلیکیشنهای چندعاملی با LLM است: بهجای یک چتبات تنها، چند عامل با نقشهای مشخص میسازید که با هم گفتوگو میکنند تا وظیفه حل شود. مخزن رسمی آن خودش را چنین معرفی میکند: «فریمی برای ساخت اپلیکیشنهای هوش مصنوعی چندعاملی». توضیح رسمی همینقدر کوتاه است، چون ارزش اصلی در الگوهای گفتوگویی است که AutoGen آماده میکند — و چت گروهی قویترین آنهاست.
- نسل ۰.۲ (بستهٔ pyautogen): کلاسهای GroupChat و GroupChatManager — پایدار، پرمستندات و مبنای کدهای این مقاله.
- نسل ۰.۴ به بعد (بستهٔ autogen-agentchat): تیمهای RoundRobinGroupChat و SelectorGroupChat با معماری رویدادمحور و شرطهای پایان کلاسمحور.
- هر دو نسل با هر API سازگار با OpenAI — از جمله آپکس۲۴ — کار میکنند؛ تنها تفاوت امضای توابع و شرطهای پایان است.
چرا این تقسیمبندی مهم است؟ چون بیشتر آموزشهای قدیمی اینترنت روی نسل ۰.۲ نوشته شدهاند و مستندات جدید رو به نسل ۰.۴+ میروند. اگر بدانید کدام بسته را نصب کردهاید، نیمی از خطاهای «این کلاس وجود ندارد» و «این پارامتر ناشناخته است» از همینجا حل میشود. در ادامه، جدول مقایسهٔ دو نسل را هم میبینید.
AutoGen is a framework for creating multi-agent AI applications.
— توضیح رسمی مخزن AutoGen در GitHub
معماری چت گروهی چگونه کار میکند؟
قلب چت گروهی یک حلقهٔ ساده است: مدیر گفتوگو در هر نوبت گویندهٔ بعدی را انتخاب میکند، آن عامل پاسخ تولید میکند، پاسخ به تاریخچه اضافه میشود و حلقه تکرار میشود تا شرط پایان برقرار شود یا سقف نوبتها پر شود. نکتهٔ فنی مهم این است که هر دو کار «انتخاب گوینده» و «تولید پاسخ» در نهایت به یک درخواست HTTP به endpoint چت — یعنی POST /v1/chat/completions روی آپکس۲۴ — تبدیل میشوند.
- 1
۱. انتخاب گوینده
مدیر گفتوگو بر اساس speaker_selection_method تصمیم میگیرد کدام عامل صحبت کند. در حالت auto این تصمیم خودش یک فراخوانی LLM است: مدل نام گویندهٔ بعدی را از فهرست انتخاب میکند.
- 2
۲. تولید پاسخ
عامل انتخابشده، کل تاریخچهٔ گفتوگو بهعلاوهٔ system_message خودش را در یک درخواست به آپکس۲۴ میفرستد و پاسخ میگیرد. به همین دلیل هرچه گفتوگو طولانیتر شود، توکن ورودی هر نوبت بیشتر میشود.
- 3
۳. ثبت در تاریخچه
پاسخ به پیامهای GroupChat اضافه میشود و همهٔ عاملها در نوبت بعدی آن را میبینند. این «حافظهٔ مشترک» هم نقطهٔ قوت هم نقطهٔ هزینهٔ چت گروهی است.
- 4
۴. بررسی شرط پایان
اگر پیام حاوی TERMINATE باشد (و is_termination_msg آن را بگیرد) یا به max_round رسیده باشیم، حلقه تمام میشود و ChatResult به فراخواننده برگردانده میشود.
چطور محیط را آماده کنم؟ نصب و پیشنیازها
سه چیز لازم دارید: پایتون ۳.۱۰ یا جدیدتر، بستهٔ pyautogen، و یک کلید API آپکس۲۴ با اعتبار کافی. چت گروهی چند عامل را در چندین درخواست پشتسرهم میفرستد، پس مطمئن شوید حسابتان اعتبار دارد؛ آپکس۲۴ حداقل مصرف و اشتراک ندارد و فقط بهاندازهٔ مصرف واقعی هزینه کم میکند، پس شروع با اعتبار کوچک کاملاً منطقی است.
- 1
۱. ساخت محیط مجازی و نصب pyautogen
برای الگوی کدهای این مقاله (نسل ۰.۲) بستهٔ pyautogen کافی است؛ openai هم نصب میشود تا SDK سازگار در دسترس باشد. اگر مسیر نسل جدید را میخواهید، autogen-agentchat و autogen-ext را جداگانه نصب کنید — API آن متفاوت است.
- 2
۲. گرفتن کلید API از آپکس۲۴
در پنل آپکس۲۴ وارد صفحهٔ کلیدهای API شوید، کلید جدید بسازید و آن را کپی کنید. کلید با پیشوند sk-apx- شروع میشود و فقط یکبار نمایش داده میشود؛ آن را هرگز در کد کامیتشده قرار ندهید.
- 3
۳. نگهداری امن کلید در متغیر محیطی
کلید را در متغیر محیطی APX24_API_KEY ذخیره کنید تا هرگز داخل سورسکد ظاهر نشود. همهٔ کدهای این مقاله همین الگو را دنبال میکنند.
چطور AutoGen را به API آپکس۲۴ وصل کنم؟
اتصال آپکس۲۴ به AutoGen از آن دست سادههایی است که باورش نمیکنید: چون AutoGen برای همهٔ مدلها از الگوی سازگار با OpenAI استفاده میکند و آپکس۲۴ همین الگو را روی https://api.apx24.ir/v1 پیادهسازی کرده، فقط باید دو مقدار base_url و api_key را در config_list بگذارید. هیچ subclass، هیچ پلاگین و هیچ wrapper لازم نیست — کلاسهای AssistantAgent و GroupChat دستنخورده میمانند.
| ویژگی | pyautogen (نسل ۰.۲) | autogen-agentchat (نسل ۰.۴+) |
|---|---|---|
| نصب | pip install pyautogen | pip install autogen-agentchat autogen-ext |
| چت گروهی | autogen.GroupChat + autogen.GroupChatManager | RoundRobinGroupChat / SelectorGroupChat / MagenticOneGroupChat |
| انتخاب گوینده | speaker_selection_method روی GroupChat | مدیر داخلی تیم — چرخشی یا انتخاب با LLM |
| شرط پایان | max_round و is_termination_msg | TerminationCondition: MaxMessageTermination، TextMentionTermination و ترکیب با | |
| مدل روی آپکس۲۴ | config_list با base_url | OpenAIChatCompletionClient با base_url و model_info |
| مناسب برای | شروع سریع، آموزش، نمونههای فراوان | پروژههای جدید async و رویدادمحور |
چطور اولین چت گروهی سهنفره را بسازم؟ (برنامهریز، کدنویس، بازبین)
حالا همهٔ قطعهها را کنار هم میگذاریم: یک UserProxyAgent که وظیفه را میآورد، سه AssistantAgent با نقشهای مکمل، یک GroupChat با سقف نوبت معقول و یک GroupChatManager که با مدل آپکس۲۴ نوبتدهی میکند. کل فایل حدود ۶۰ خط است و مستقیم قابل اجرا.
روشهای انتخاب گوینده: auto، round_robin، random، manual — کدام را انتخاب کنم؟
speaker_selection_method تعیین میکند شخصیت گفتوگوی شما چیست: خلاق و انعطافپذیر (auto)، منظم و ارزان (round_robin)، یا کاملاً در کنترل شما (manual). انتخاب اشتباه این پارامتر رایجترین علت دو شکایت توسعهدهندگان است: «چرا همه کار را یکی انجام میدهد؟» و «چرا فاکتورم آنقدر بالا رفت؟».
| مقدار | منطق انتخاب گوینده | هزینهٔ توکن اضافه | مناسب برای |
|---|---|---|---|
| auto | مدل با خواندن تاریخچه، نام گویندهٔ بعدی را انتخاب میکند | یک درخواست اضافه در هر نوبت | وظایف پیچیدهٔ چندمرحلهای که ترتیب صحبت از متن پیام معلوم میشود |
| round_robin | چرخش ثابت به ترتیب فهرست agents | هیچ | خط تولید مشخص: طراحی ← پیادهسازی ← بازبینی |
| random | انتخاب تصادفی بین عاملها | هیچ | طوفان فکری و ایدهپردازی متنوع |
| manual | ادمین (admin_name) در هر نوبت گوینده را تعیین میکند | هیچ | کنترل کامل انسانی و سناریوهای نمایشی |
| تابع سفارشی | تابع پایتون شما بر اساس آخرین گوینده و تاریخچه انتخاب میکند | هیچ | قواعد کسبوکار خاص، مثلاً مسیریابی پیام بر اساس نوع محتوا |
- اگر ترتیب کار مشخص است ← round_robin: ارزان، قطعی و قابلدیباگ.
- اگر «چه کسی صحبت کند» به محتوای پیام بستگی دارد ← auto با مدل قوی؛ و مدیر را روی مدل اقتصادی جدا بگذارید تا هزینهٔ انتخاب گوینده کم بماند.
- اگر میخواهید ایدههای متنوع ببینید ← random در مرحلهٔ ایدهپردازی، بعد سوییچ به round_robin برای اجرا.
- اگر در حال آموزش یا دمو هستید ← manual: خودتان میکروفون را بدهید.
- قاعدهٔ پیشفرض تحریریه: برای اولین اجرای هر پروژه، round_robin — و بعد از پایدار شدن نقشها، فقط اگر لازم شد auto.
یک جزئیات عملی از مستندات رسمی: GroupChat پارامتر send_introductions هم دارد که در شروع گفتوگو، خودمعرفی کوتاه عاملها را به تاریخچه اضافه میکند و انتخاب گویندهٔ auto را دقیقتر میکند. هزینهٔ یکبارهٔ کوچکی دارد اما در تیمهای چندنفره معمولاً جلوی انتخابهای اشتباه را میگیرد.
چطور گفتوگو را تمیز تمام کنم و حلقهٔ بیپایان را ببندم؟
برای توقف گفتوگو سه لایهٔ دفاعی دارید و بهتر است هر سه را با هم ببندید: لایهٔ نخست قراردادی است — به عامل متمرکز بگویید وقتی کار تمام شد فقط کلمهٔ TERMINATE بنویسد. لایهٔ دوم تشخیصی است — is_termination_msg روی GroupChatManager همان عبارت را از پیامهای ورودی میگیرد و حلقه را میشکند. لایهٔ سوم ایمنی است — max_round سقف قطعی نوبتهاست؛ حتی اگر دو لایهٔ قبلی هر دو شکست بخورند، حسابتان آتش نمیگیرد چون پیشفرض GroupChat همان ۱۰ نوبت است.
خطاهای رایج اتصال AutoGen به آپکس۲۴ و راهحلها
خطاهای چت گروهی تقریباً همیشه در اولین نوبت ظاهر میشوند و متأسفانه traceback پایتون پیام واقعی HTTP را عمیق دفن میکند. سه خطای زیر حدود ۹۰٪ مشکلات اتصال را پوشش میدهند؛ قبل از دیباگ پیچیده، همین سه چکلیست را رد کنید.
- چکلیست ۶۰ ثانیهای پیش از هر دیباگ: curl تکدرخواستی به endpoint پاسخ ۲۰۰ میدهد؟
- متغیر محیطی APX24_API_KEY ست است و کلید کامل است؟
- base_url فقط تا /v1 است و model عین نام کاتالوگ است؟
- speaker_selection_method و max_round آگاهانه انتخاب شدهاند؟
- خطای واقعی HTTP را از traceback پیدا کردهاید یا از پیام عمومی پایتون؟
هزینهٔ چت گروهی چقدر است؟ فرمول، جدول قیمت و بهینهسازی
هزینهٔ چت گروهی از یک جمع ساده میآید که فقط یک پیچوتاب دارد: تاریخچهٔ مشترک. هر نوبت، کل گفتوگوی قبلی دوباره به مدل ارسال میشود؛ پس توکن ورودی هر نوبت بزرگتر از نوبت قبل است و هزینه بهصورت شتابدار رشد میکند. بگذارید با فرمول و اعداد واقعی آپکس۲۴ دقیق حساب کنیم.
کاربردهای واقعی چت گروهی در کسبوکار و گام بعدی
الگوی مشترک هر دو مثال یک است: نقشهای کوچک با مرز روشن، ترتیب یا انتخاب گویندهٔ آگاهانه، شرط پایان قطعی و مدلبندی هزینهآگاه. وقتی این چهار مورد را دارید، تغییر از یک تیم سهنفره به دهها سناریوی دیگر فقط عوضکردن system_messageهاست — زیرساخت (AutoGen + آپکس۲۴) هیچ تغییری نمیخواهد.
- گام بعدی ۱: تمرینهای چهارگانهٔ پایان مقاله را حل کنید — P3 حسابداری هزینه را برای همیشه یادتان میاندازد.
- گام بعدی ۲: function calling به عاملها اضافه کنید تا بهجای حرف، ابزار صدا بزنند.
- گام بعدی ۳: سراغ SelectorGroupChat نسل ۰.۴+ بروید وقتی گفتوگوی async و رویدادمحور خواستید.
- گام بعدی ۴: تیم پایدارشده را در CI اجرا کنید و گزارش ChatResult را به داشبورد مصرفتان وصل کنید.





