در توسعه‌ی سیستم‌های هوش مصنوعی چندایجنتی، بیشتر فریم‌ورک‌ها مانند LangGraph یا CrewAI ساختارهای پیچیده‌ای از گراف‌ها، نودها و زبان‌های اختصاصی را تحمیل می‌کنند. این انتزاع‌ها اگرچه قدرتمندند، اما کد را سنگین و نگهداری آن را دشوار می‌سازند. الگوی معرفی‌شده در OpenAI Swarm این پیچیدگی را کنار میزند و ارکستراسیون را تنها با تکیه بر قابلیت درونی فراخوانی ابزار (Tool Calling) مدل‌ها پیاده میکند.
در این درس یاد می‌گیرید که چگونه با دو المان پایه‌ای یعنی روتین‌ها (دستورالعمل و ابزارها) و دستبهدستکردن (Handoff)، جریان گفت‌وگو را بین چندین ایجنت متخصص جابه‌جا کنید. شناخت این الگو نه‌تنها کد شما را فوق‌العاده خوانا و سبک نگه می‌دارد، بلکه پایه‌ی مفهومی نسل جدید فریم‌ورک‌ها از جمله OpenAI Agents SDK را تشکیل میدهد.
اگر برای تست و اجرای کدهای این آموزش به APIهای خارجی متصل می‌شوید، توجه داشته باشید که پرداخت ارزی برای تهیه‌ی اعتبار در ارائه‌دهندگانی مثل OpenAI از ایران با کارت‌های بانکی مستقیم ممکن نیست؛ با این حال، چون این الگو بر مبنای فراخوانی استاندارد مدل طراحی شده، با تغییر آدرس پایه (Base URL) می‌توانید آن را روی گیت‌وی‌های واسط داخلی یا مدل‌های محلی سازگار با ساختار OpenAI نیز پیاده کنید.
فریمورک Swarm از شرکت OpenAI (اکتبر 2024) ارکستراسیون چندایجنتی (Multi-agent orchestration) را در دو مفهوم بنیادین خلاصه کرد: روتین‌ها (دستورالعمل‌ها + ابزارها در قالب پرامپت سیستم) و دستبهدستکردن (Handoff یا تحویل وظیفه؛ ابزاری که یک ایجنت جدید برمی‌گرداند). نه خبری از ماشین وضعیت (State Machine) است و نه زبان‌های اختصاصی دامنه (DSL) برای شاخه‌بندی؛ خود مدل زبانی بزرگ (LLM) با فراخوانی ابزار دست‌به‌دست‌کردنِ مناسب، کار مسیریابی را انجام میدهد. فریمورک OpenAI Agents SDK (مارس 2025) جانشین رسمی آن برای محیط عملیاتی (پروداکشن) است. با این حال، خود Swarm شفاف‌ترین مرجع مفهومی باقی مانده است؛ کل کد منبع آن در چند صد خط جا می‌شود. دلیل استقبال گسترده از این الگو، سادگی سطح API آن است: «ایجنت = پرامپت + ابزارها؛ دستبهدستکردن = تابعی که ایجنت برمی‌گرداند». محدودیت اصلی: سیستم بیوضعیت (Stateless) است و مدیریت حافظه به دوش فراخواننده می‌افتد.
مسئله
تقریباً همه‌ی فریم‌ورک‌های چندایجنتی شما را وادار می‌کنند DSL اختصاصی‌شان را یاد بگیرید: نودها و یال‌ها در LangGraph، تیم‌ها (Crews) و وظیفه‌ها (Tasks) در CrewAI، و GroupChat و مدیرها در AutoGen. این زبان‌ها تجریدهای واقعی و معتبری هستند، اما ماجرا را سنگین‌تر از چیزی که باید باشد نشان می‌دهند.
فریمورک Swarm دقیقاً در جهت عکس حرکت میکند: استفاده از همان قابلیت فراخوانی ابزار (Tool call) که مدل از قبل دارد. دست‌به‌دست‌کردن‌ها تبدیل به فراخوانی ابزار می‌شوند. هماهنگ‌کننده (Orchestrator) همان ایجنتی است که در حال حاضر گفت‌وگو را دست دارد. ماشین وضعیت هم به‌طور ضمنی درون پرامپت‌های سیستمِ خود ایجنت‌ها قرار گرفته است.
مفاهیم پایه
دو مفهوم بنیادین
روتین (Routine). پرامپت سیستمی که نقش ایجنت و ابزارهای در دسترس آن را تعیین میکند. آن را مثل مجموعه‌ای از دستورالعمل‌ها با دامنه‌ی (Scope) مشخص در نظر بگیرید: «شما ایجنت تریاژ هستید؛ اگر کاربر درباره‌ی بازگشت وجه پرسید، کار را به ایجنت بازگشت وجه تحویل دهید».
دستبهدستکردن (Handoff). ابزاری که ایجنت می‌تواند فراخوانی کند و خروجی آن یک شیء ایجنت جدید است. محیط اجرای Swarm این مقدار بازگشتی از نوع ایجنت را تشخیص میدهد و ایجنت فعال را برای نوبت گفت‌وگوی (Turn) بعدی عوض میکند.
کل ساختار تجرید همین است؛ نه بیشتر و نه کمتر.
def transfer_to_refunds():
return refund_agent # Swarm sees Agent return → switch active agent
triage_agent = Agent(
name="triage",
instructions="Route the user to the right specialist.",
functions=[transfer_to_refunds, transfer_to_sales, transfer_to_support],
)پرامپت سیستمِ ایجنت تریاژ باعث می‌شود بر اساس پیام کاربر، دستبهدستکردن درست را انتخاب کند. در واقع قابلیت فراخوانی ابزار مدل، کار مسیریابی را انجام میدهد.
چرا این الگو فراگیر شد؟
- رابط برنامه‌نویسی بسیار کوچک. کلاً دو مفهوم برای یادگیری دارد.
- استفاده از توانمندی‌های فعلی مدل. فراخوانی ابزار هم‌اکنون در تمامی ارائه‌دهندگان مدل در سطح محیط عملیاتی کار میکند.
- حذف بار سنگین ماشین وضعیت. نیازی به تعریف گراف ندارید؛ پرامپت‌های ایجنت‌ها مشخص می‌کنند وظیفه باید به چه کسی تحویل داده شود.
هزینه‌ی بیوضعیت بودن
فریمورک Swarm صراحتاً بین دفعات اجرا بیوضعیت است. در طول یک اجرا تاریخچه‌ی پیام‌ها را نگه می‌دارد، اما هیچ داده‌ای را ذخیره یا پایدار نمی‌کند. حافظه، تداوم گفت‌وگو و وظایف طولانی‌مدت؛ همگی مسئولیت کد فراخواننده هستند.
در محیط عملیاتی (OpenAI Agents SDK، مارس 2025) این موضوع یکی از تغییرات اصلی بود: این SDK مدیریت نشست (Session)، گاردریلها (سازوکارهای ایمنی یا Guardrails) و ردگیری محاسبات (Tracing) را به صورت توکار اضافه کرد، در حالی که مفهوم بنیادین دستبهدستکردن را دست‌نخورده نگه داشت.
چه زمان Swarm و الگوی دستبهدستکردن مناسب است؟
- الگوهای تریاژ. ایجنت خط اول، کاربر را به متخصص مربوطه هدایت میکند.
- تحویل وظیفه بر اساس مهارت. «اگر کار نیاز به کدنویسی دارد، ایجنت برنامه‌نویس را صدا بزن؛ اگر به تحقیق نیاز دارد، ایجنت محقق را فراخوانی کن».
- گفت‌وگوهای کوتاه و محدود. پشتیبانی مشتریان، تبدیل پرسش‌های متداول به تیکت و جریان‌های کاری (Workflows) ساده.
نقاط ضعف Swarm کجاست؟
- نشست‌های طولانی با حافظه‌ی مشترک. با هر بار دستبهدستکردن، وضعیت گفت‌وگو به پرامپت ایجنت جدید به‌علاوه‌ی تاریخچه بازنشانی می‌شود. هیچ وضعیت پایداری بین ایجنت‌ها وجود ندارد، مگر این‌که حافظه را در سمت فراخواننده مدیریت کنید.
- اجرای موازی. تحویل وظیفه تک‌به‌تک انجام می‌شود؛ یعنی ایجنت فعال جابه‌جا می‌شود. اجرای موازی مستلزم آن است که فراخواننده چندین اجرای مجزای Swarm را ارکستریت کند.
- حسابرسی و بازپخش (Replay). اجرای بدون وضعیت را به‌سختی می‌توان دقیقاً بازپخش کرد؛ انتخاب دستبهدستکردن توسط مدل، قطعی (Deterministic) نیست.
فریمورک OpenAI Agents SDK (مارس 2025)
این نسخهی عملیاتی قابلیت‌های زیر را اضافه میکند:
- وضعیت نشست (Session state). رشته‌گفت‌وگوی پایدار در میان چندین اجرا.
- گاردریلها (Guardrails). قلاب‌هایی (Hooks) برای اعتبارسنجی ورودی و خروجی.
- ردگیری محاسبات (Tracing). تمام فراخوانی‌های ابزار و دست‌به‌دست‌کردن‌ها ثبت می‌شوند.
- فیلترهای دستبهدستکردن. کنترل این‌که چه بخشی از بافتار (Context) در زمان تحویل منتقل شود.
مفهوم پایه‌ایِ دستبهدستکردن پابرجا مانده و امکانات و ارگونومی محیط عملیاتی به دور آن اضافه شده است.
مقایسه‌ی Swarm با GroupChat
هر دو از مسیریابی مبتنی بر مدل زبانی استفاده می‌کنند، اما تفاوت‌شان در این است که چه کسی نفر بعدی را انتخاب میکند:
- در GroupChat: یک انتخاب‌کننده (تابع یا مدل زبانی) از بیرون مشخص میکند چه کسی باید صحبت کند.
- در Swarm: ایجنت فعلی با فراخوانی ابزار دستبهدستکردن، جانشین خودش را برمی‌گزیند.
در واقع Swarm یعنی «ایجنت تصمیم میگیرد گام بعدی چیست»؛ اما GroupChat یعنی «مدیر تصمیم میگیرد نفر بعدی کیست». تصمیم در Swarm درون فراخوانی ابزارِ ایجنت فعال شکل میگیرد؛ در GroupChat این تصمیم در دل GroupChatManager رخ میدهد.
ساخت و پیاده‌سازی
فایل code/main.py فریمورک Swarm را از صفر پیاده میکند: یک کلاس داده‌ی (Dataclass) ایجنت، سازوکار دستبهدستکردن (ابزاری که ایجنت برمی‌گرداند)، و حلقه‌ی اجرایی که تغییر ایجنت را تشخیص میدهد.
دمو: یک ایجنت تریاژ گفت‌وگو را به متخصصان بازگشت وجه، فروش یا پشتیبانی هدایت میکند. هر متخصص ابزارهای خاص خود را دارد. حلقه‌ی اجرا هر بار تحویل وظیفه را چاپ میکند.
اجرا:
python3 code/main.pyاستفاده در عمل
فایل outputs/skill-handoff-designer.md توپولوژی دستبهدستکردن را برای یک وظیفه‌ی معین طراحی میکند: چه ایجنت‌هایی وجود دارند، کدام ابزارهای تحویل را می‌توانند فراخوانی کنند و چه بافتاری باید منتقل شود.
ورود به محیط عملیاتی
چک‌لیست:
- ثبت لاگ دستبهدستکردن. هر جابه‌جایی باید یک رویداد ردگیری محاسبات شامل ایجنت مبدأ، ایجنت مقصد و اسنپ‌شاتی (Snapshot) از بافتار ثبت کند.
- قواعد انتقال بافتار. مشخص کنید در زمان تحویل چه چیزی منتقل می‌شود: کل تاریخچه (پرهزینه)، N پیام آخر، یا خلاصه‌ای از گفت‌وگو.
- گاردریل روی دستبهدستکردن. تحویل وظیفه به متخصصی با سطح دسترسی متفاوت به ابزارها باید اعتبارسنجی و احراز هویت شود؛ در غیر این صورت تزریق پرامپت (Prompt injection) می‌تواند تحویل ناخواسته را تحمیل کند.
- تشخیص حلقه (Loop detection). دست‌به‌دست شدن مداوم بین دو ایجنت یک خطای رایج است؛ با یک بررسی ساده روی K وضعیت آخر جلوی آن را بگیرید.
- ایجنت پشتیبان (Fallback). اگر مقصد تحویل وجود نداشت، روی یک پیش‌فرض امن (Safe default) برگردید.
تمرین‌ها
- فایل
code/main.pyرا اجرا کنید و پیام را به ایجنت بازگشت وجه هدایت نمایید. بررسی کنید که ایجنت فعال در نوبت دوم، همان ایجنت بازگشت وجه باشد. - قاعده‌ای برای تشخیص حلقه اضافه کنید: اگر دو ایجنت یکسان 3 بار متوالی کار را به یکدیگر سپردند، خروج اجباری بزنید. طرح پشتیبان (Fallback) را هم طراحی کنید.
- مستندات OpenAI Agents SDK درباره‌ی فیلترهای دستبهدستکردن را مطالعه کنید. نسخه‌ای با قابلیت «خلاصه‌سازی هنگام تحویل» پیاده کنید: ایجنت خروجی پیش از تحویل کار به ایجنت ورودی، بافتار را در قالب چند نکته‌ی کلیدی خلاصه کند.
- نحوه‌ی تحویل وظیفه در Swarm را با انتخاب‌کننده‌ی GroupChatManager مقایسه کنید. کدام الگو آسیب‌پذیری در برابر تزریق پرامپت را بدتر میکند و چرا؟
- راهنمای عملی (Cookbook) فریمورک Swarm در آدرس (https://developers.openai.com/cookbook/examples/orchestrating_agents) را بخوانید. یک تصمیم صریح در طراحی Swarm پیدا کنید که OpenAI Agents SDK آن را تغییر داده یا حفظ کرده است.
اصطلاحات کلیدی
| اصطلاح | برداشتی که رایج است | معنای واقعی آن در عمل |
|---|---|---|
| روتین (Routine) | «پرامپت ایجنت» | پرامپت سیستم + فهرست ابزارها. نقش ایجنت و دست‌به‌دست‌کردن‌های در دسترس را مشخص میکند. |
| دستبهدستکردن (Handoff) | «انتقال به ایجنت دیگر» | ابزاری که ایجنت فعال می‌تواند فراخوانی کند و یک ایجنت جدید برمی‌گرداند. محیط اجرا، ایجنت فعال را عوض میکند. |
| بیوضعیت (Stateless) | «بدون حافظه بین دفعات اجرا» | فریمورک Swarm هیچ داده‌ای را ذخیره نمی‌کند؛ مدیریت حافظه وظیفه‌ی کد فراخواننده است. |
| ایجنت فعال (Active agent) | «چه کسی الان حرف میزند» | ایجنتی که اکنون گفت‌وگو را در دست دارد. دستبهدستکردن این وضعیت را تغییر میدهد. |
| انتقال بافتار (Context transfer) | «چه چیزهایی منتقل می‌شود» | سیاستی برای تعیین این‌که ایجنت ورودی چه بخش از تاریخچه را ببیند: کامل، N پیام آخر یا خلاصه‌شده. |
| حلقه‌ی دستبهدستکردن (Handoff loop) | «پاس‌کاری مداوم ایجنت‌ها» | حالت خرابی که در آن دو ایجنت مدام کار را به یکدیگر بازمی‌گردانند. |
| فریمورک OpenAI Agents SDK | «نسخهی پروداکشن Swarm» | جانشین ارائه‌شده در مارس 2025؛ روی همان هسته‌ی دستبهدستکردن، امکانات نشست، گاردریلها و ردگیری محاسبات را اضافه کرده است. |
| فیلتر دستبهدستکردن (Handoff filter) | «گیتِ مرحله‌ی انتقال» | قابلیتی در SDK برای بررسی و اصلاح بافتار دقیقاً در مرز تحویل وظیفه. |
برای مطالعه‌ی بیشتر
- کتابچه‌ی راهنمای OpenAI — ارکستراسیون ایجنت‌ها: روتین‌ها و دستبهدستکردن — مرجع اصلی بیان این الگو
- مخزن کد OpenAI Swarm — پیاده‌سازی اولیه که به عنوان مرجع مفهومی حفظ شده است
- مستندات OpenAI Agents SDK — جانشین آماده‌ی پروداکشن با قابلیت مدیریت نشست‌ها و ردگیری محاسبات
- یادداشت‌های Anthropic درباره‌ی دستبهدستکردن در Claude — نحوه‌ی استفاده‌ی ساب‌ایجنت‌های Claude Code از الگوی مشابه دستبهدستکردن از طریق
Task