آشنایی با OpenAI Agents SDK: انتقال وظایف، گاردریل‌ها و ردگیری

وقتی پروژه‌های مبتنی بر هوش مصنوعی بزرگ‌تر می‌شوند، قرار دادن تمام دستورالعمل‌ها، ابزارها و محدودیت‌ها داخل یک پرامپت تکی خیلی زود با شکست روبه‌رو می‌شود. مدل سردرگم می‌شود، خطاهای امنیتی یا نشت اطلاعات حساس پیش می‌آید و هدایت جریان مکالمه عملاً ناممکن خواهد شد. راهکار استاندارد صنعت در چنین شرایطی، تقسیم وظایف میان ایجنت‌های تخصصی و اتصال کنترل‌شده‌ی آن‌ها به یکدیگر است.

فریم‌ورک رسمی OpenAI Agents SDK برای حل همین چالش ساخته شده و معماری چندایجنت را بر پایه‌ی پنج مفهوم کلیدی استاندارد می‌کند. با یادگیری سازوکار تحویل وظایف (Handoffs)، اعتبارسنجی ورودی و خروجی با گاردریل‌ها (Guardrails) و مشاهده‌پذیری رفتار سیستم با ردگیری محاسبات (Tracing)، ساختار برنامه‌های خود را از کدنویسی شکننده به استانداردی قابل نگهداری ارتقا می‌دهید.

از آنجا که کارت‌های بانکی ایرانی امکان پرداخت مستقیم برای اعتبار سرویس‌های خارجی مثل OpenAI را ندارند، آشنایی با نحوه‌ی جداسازی وظایف و بهینه‌سازی توکن‌ها حیاتی‌تر است. علاوه بر این، در صورت نیاز به استفاده از درگاه‌های سازگار داخلی یا اتصال به سامانه‌های محلی، پیاده‌سازی منطق استاندارد این SDK به شما کمک می‌کند کمترین تغییر ممکن را در کدهای اصلی خود اعمال کنید.

فریم‌ورک OpenAI Agents SDK یک چارچوب چندایجنت سبک است که روی Responses API ساخته شده است. این فریم‌ورک بر پایه‌ی پنج مفهوم بنیادین کار می‌کند: ایجنت (Agent)، دست‌به‌دست‌کردن (Handoff)، گاردریل (Guardrail)، نشست (Session) و ردگیری محاسبات (Tracing). عمل Handoff در قالب ابزارهایی با نام transfer_to_<agent> تعریف می‌شود. گاردریل‌ها روی ورودی یا خروجی فعال می‌شوند و ردگیری محاسبات نیز به‌طور پیش‌فرض روشن است.

اهداف یادگیری

• نام بردن پنج مفهوم بنیادین در OpenAI Agents SDK.
• توضیح handoff: چرا در قالب ابزار مدل‌سازی می‌شود، مدل چه ساختار نامی را می‌بیند و بافتار چگونه منتقل می‌شود.
• تشخیص تفاوت گاردریل‌های ورودی، خروجی و ابزار؛ و توضیح تفاوت حالت run_in_parallel با حالت مسدودکننده (blocking).
• پیاده‌سازی یک محیط اجرای ساده با کتابخانه‌ی استاندارد پایتون شامل handoff، گاردریل‌ها و ردگیری محاسبات مبتنی بر اسپن (span).

صورت مسئله

ایجنت‌هایی که راه تمیزی برای واگذاری وظایف نداشته باشند، در نهایت مجبور می‌شوند همه‌چیز را داخل یک پرامپت (Prompt) بگنجانند. از طرف دیگر، ایجنت‌های بدون گاردریل ممکن است اطلاعات هویتی حساس (PII) را نشت دهند، خروجی‌های ناقض سیاست تولید کنند یا در حلقه‌های بی‌نهایت بیفتند. ابزار Agents SDK شرکت OpenAI سه مفهوم بنیادین را استاندارد کرده تا کار با سیستم‌های چندایجنت مدیریت‌پذیر شود.

مفاهیم اصلی

پنج مفهوم بنیادین

1. ایجنت (Agent): ترکیب مدل زبانی بزرگ (LLM) + دستورالعمل‌ها + ابزارها + handoffها.
2. دست‌به‌دست‌کردن (Handoff): واگذاری کار به ایجنتی دیگر. این عمل برای مدل در قالب ابزاری به نام transfer_to_<agent_name> نمایش داده می‌شود.
3. گاردریل (Guardrail): اعتبارسنجی روی ورودی (فقط برای ایجنت اول)، خروجی (فقط برای ایجنت آخر) یا فراخوانی ابزار (به‌ازای هر ابزار تابعی).
4. نشست (Session): تاریخچه‌ی خودکار گفت‌وگو در طول نوبت‌های مختلف (turns).
5. ردگیری محاسبات (Tracing): اسپن‌های توکار برای خروجی‌های LLM، فراخوانی‌های ابزار، handoffها و گاردریل‌ها.

پیاده‌سازی تحویل کار در قالب ابزار

مدل در فهرست ابزارهای خود transfer_to_billing_agent را می‌بیند. فراخوانی این ابزار به محیط اجرا پیام می‌دهد تا:

1. بافتار گفت‌وگو را کپی کند (یا با قابلیت آزمایشی nest_handoff_history آن را فشرده و جمع کند).
2. ایجنت مقصد را با دستورالعمل‌های اختصاصی آن راه‌اندازی کند.
3. اجرای فرآیند را با ایجنت مقصد ادامه دهد.

این در واقع پیاده‌سازی کاربردی و محصول‌شده‌ی الگوی ناظر (Supervisor Pattern در درس 13 و درس 28) است.

گاردریل‌ها

سه نوع گاردریل داریم:

• گاردریل‌های ورودی (Input guardrails): روی ورودی اولین ایجنت اجرا می‌شوند. این گاردریل‌ها درخواست‌های ناامن یا خارج از دامنه (scope) را پیش از هرگونه فراخوانی LLM رد می‌کنند.
• گاردریل‌های خروجی (Output guardrails): روی خروجی آخرین ایجنت اجرا می‌شوند تا جلوی نشت PII، نقض سیاست‌ها و پاسخ‌های بدساخت را بگیرند.
• گاردریل‌های ابزار (Tool guardrails): به‌ازای هر ابزار تابعی اجرا می‌شوند؛ آرگومان‌ها را اعتبارسنجی می‌کنند، مجوزها را می‌سنجند و اجرای عملیات را حسابرسی می‌کنند.

حالت‌های اجرا:

• موازی (Parallel - پیش‌فرض): مدل ارزیاب گاردریل هم‌زمان با LLM اصلی اجرا می‌شود. تاخیر (Latency) دم را کاهش می‌دهد؛ اما اگر گاردریل فعال شود، کارهای انجام‌شده توسط LLM اصلی دور ریخته می‌شود (اتلاف توکن).
• مسدودکننده (run_in_parallel=False): ابتدا مدل ارزیاب گاردریل اجرا می‌شود. اگر فعال شود، هیچ توکنی روی فراخوانی اصلی هدر نمی‌رود.

تله‌ها (Tripwires) خطاهای InputGuardrailTripwireTriggered یا OutputGuardrailTripwireTriggered را صادر می‌کنند.

ردگیری محاسبات

به‌طور پیش‌فرض فعال است. هر بار تولید متن توسط LLM، فراخوانی ابزار، handoff و گاردریل یک اسپن صادر می‌کند. با متغیر OPENAI_AGENTS_DISABLE_TRACING=1 می‌توانید آن را خاموش کنید. همچنین با تابع add_trace_processor(processor) می‌توانید اسپن‌ها را علاوه بر سرورهای OpenAI، به بک‌اند اختصاصی خودتان نیز ارسال کنید.

نشست‌ها

کلاس Session تاریخچه‌ی گفت‌وگو را در یک بک‌اند (مثل SQLite، Redis یا سفارشی) ذخیره می‌کند. متد Runner.run(agent, input, session=session) این تاریخچه را به‌طور خودکار بارگذاری کرده و پیام‌های جدید را به آن اضافه می‌کند.

خطاهای رایج در این الگو

• سرگردانی در handoff (یا Handoff drift): ایجنت A کار را به B واگذار می‌کند و B دوباره آن را به A پس می‌دهد. برای حل این مشکل یک شمارنده‌ی گام لغزش (hop counter) بگذارید.
• دور زدن گاردریل: گاردریل‌های ابزار فقط روی ابزارهای تابعی فعال می‌شوند؛ ابزارهای توکار (مانند فایل‌خوان یا وب‌فچ) به سیاست‌های جداگانه‌ای نیاز دارند.
• ردگیری بیش‌ازحد (Over-tracing): ثبت داده‌های حساس در اسپن‌ها. این موضوع را با قواعد ضبط محتوای OpenTelemetry GenAI (درس 23) هماهنگ کنید — داده‌ها را بیرون ذخیره کرده و در اسپن صرفاً به شناسه‌ی آن‌ها ارجاع دهید.

پیاده‌سازی از صفر

فایل code/main.py ساختار SDK را با استفاده از کتابخانه‌ی استاندارد پایتون پیاده‌سازی می‌کند:

• کلاس‌های Agent، FunctionTool و Handoff (به‌عنوان یک ابزار تابعی با معناشناسی انتقال).
• کلاس Runner همراه با گاردریل‌های ورودی/خروجی/ابزار، ارسال handoff و شمارنده‌ی گام لغزش.
• یک صادرکننده‌ی ساده‌ی اسپن برای نمایش ساختار ردگیری محاسبات.
• یک ایجنت تریاژ که بر اساس درخواست کاربر کار را به بخش مالی یا پشتیبانی می‌سپارد؛ گاردریل هم روی یک ورودی فعال می‌شود.

اجرای برنامه:

python3 code/main.py

خروجی ردگیری دو تحویل موفق، یک بار فعال شدن گاردریل ورودی و ساختار درختی اسپن‌ها را نشان می‌دهد که دقیقاً بازتاب‌دهنده‌ی خروجی SDK واقعی است.

استفاده از ابزارهای واقعی

• OpenAI Agents SDK: برای محصولاتی که بر پایه‌ی مدل‌های OpenAI توسعه می‌یابند.
• Claude Agent SDK (درس 17): برای محصولاتی که اولویتشان مدل‌های Claude است.
• LangGraph (درس 13): برای زمان‌هایی که به وضعیت صریح (explicit state) و ادامه‌ی پایدار اجرا (durable resume) نیاز دارید.
• پیاده‌سازی اختصاصی (Custom): وقتی به کنترل دقیق نیاز دارید (صوت، چند ارائه‌دهنده‌ای، یا استقرارهای توزیع‌شده).

تحویل به محیط عملیاتی

فایل outputs/skill-agents-sdk-scaffold.md زیرساخت اولیه‌ی یک برنامه‌ی مبتنی بر Agents SDK را همراه با ایجنت تریاژ، handoffها، گاردریل‌های ورودی/خروجی/ابزار، مخزن ذخیره‌سازی نشست و یک پردازنده‌ی ردگیری محاسبات پیاده‌سازی می‌کند.

تمرین‌ها

1. یک شمارنده‌ی گام لغزش برای handoff اضافه کنید: بعد از N بار جابه‌جایی درخواست را متوقف کنید. این رفتار را ردگیری کنید.
2. قابلیت nest_handoff_history را به‌عنوان یک گزینه پیاده‌سازی کنید — پیام‌های پیشین قبل از انتقال در قالب یک خلاصه فشرده شوند.
3. یک گاردریل خروجی مسدودکننده (blocking) بنویسید. تاخیر را روی پرامپت‌هایی که آن را فعال می‌کنند با پرامپت‌هایی که تایید می‌شوند مقایسه کنید.
4. متد add_trace_processor را به یک لاگر JSON متصل کنید. ساختار خروجی آن به‌ازای هر اسپن چیست؟
5. مستندات SDK را بخوانید. کدهای ساده‌ی پایتونی خود را به openai-agents-python پورت کنید. چه بخش‌هایی را در مدل‌سازی اشتباه متوجه شده بودید؟

اصطلاحات کلیدی

برای مطالعه‌ی بیشتر

• مستندات OpenAI Agents SDK — مفاهیم پایه، handoffها، گاردریل‌ها، ردگیری محاسبات
• مروری بر Claude Agent SDK — همتای طراحی‌شده برای Claude
• آنتروپیک، ساخت ایجنت‌های موثر — چه زمان‌هایی اصلاً باید سراغ handoff رفت
• قراردادهای معنایی OpenTelemetry GenAI — استانداردی که اسپن‌های Agents SDK با آن تطبیق داده می‌شوند