Agent Catalog و Typed Contracts

وقتی یک سیستم چندعاملی فقط فهرستی از نام‌ها و promptها دارد، orchestration عملاً روی حدس بنا می‌شود. «Researcher» خروجی آزاد می‌دهد، «Publisher» انتظار JSON ساخت‌یافته دارد، یک عامل ابزار پرریسک دارد اما authority آن معلوم نیست، و handoff دیگری داده‌ای را به عاملی می‌فرستد که memory boundary آن تعریف نشده است. تا وقتی این قراردادها صریح نباشند، موفقیت یک اجرای آزمایشی هیچ تضمینی برای سازگاری اجرای بعدی نیست.

خروجی این درس Agent Catalog & Typed Contract Registry v1 است؛ رجیستری‌ای که برای هر agent هویت پایدار، نسخه، هدف، مالک، قرارداد ورودی و خروجی، ابزارها، handoffها، authority class، مرز داده و حافظه، guardrailها، failure/retry semantics، وضعیت compatibility، deprecation و evidence را کنار هم قرار می‌دهد.

قاعده اول: اسم agent و کیفیت prompt جای contract قابل‌اعتبارسنجی را نمی‌گیرد.

مرز درس و مسیر یادگیری

AGN-003 مالک «Catalog و Typed Contracts» است. AGN-002 تصمیم‌سازی مبتنی بر evidence و confidence را پوشش می‌دهد؛ AGN-004 مالک Agent Authority Matrix است. این درس authority جدید صادر نمی‌کند و policy حافظه را هم جایگزین نمی‌کند؛ فقط interface و boundaryهایی را ثبت می‌کند که orchestration باید قبل از delegation بتواند اعتبارسنجی کند.

مسیر پایه با field map و یک baseline شروع می‌شود. مسیر باتجربه می‌تواند تعریف‌های مقدماتی را کوتاه کند، اما باید همان gateهای versioning، schema compatibility، tool/handoff contract، authority linkage و failure semantics را بگذراند.

پیش‌نیاز سخت AGN-001 و پیش‌نیاز نرم AGN-002 است. اگر evidence یکی از این دو شکننده باشد، learner باید bridge محدود بسازد؛ نه اینکه outcome این درس را پایین بیاورد.

مدل ذهنی: Agent یک نام نیست، یک endpoint قراردادی است

یک catalog entry را مثل endpoint قابل‌نسخه‌بندی ببینید. caller باید بدون خواندن prompt داخلی بتواند بداند:

1. چه کسی است؟ agent_id, agent_version, purpose, owner_ref.
2. چه چیزی می‌پذیرد و چه چیزی برمی‌گرداند؟ input_schema_ref, output_schema_ref, structured_output_mode.
3. به چه چیزهایی دسترسی دارد؟ tool_contract_ids, handoff_contract_ids, authority_class, allowed_actions, forbidden_actions.
4. داده کجا می‌رود؟ data_classification, memory_boundary_ref, guardrail_refs.
5. اگر شکست خورد چه می‌شود؟ failure_states, retry_contract_ref.
6. آیا مصرف‌کننده‌های فعلی هنوز با آن سازگارند؟ compatibility_state, deprecation_state, catalog_status, evidence_ref.

Typed contract باید failure را هم type کند. HOLD, INCOMPATIBLE, DEPRECATED و UNKNOWN شکست سیستم نیستند؛ حالت‌های سالمی هستند که جلوی delegation نامعتبر را می‌گیرند.

مبانی: FACT بیرونی در برابر DESIGN محلی

مستندات فعلی OpenAI Agents SDK، agent را یک LLM با instructions و tools و رفتارهای اختیاری مانند handoff، guardrail و structured output مدل می‌کند. در لایه function schema نیز پارامترهای تابع با Pydantic model و JSON Schema نمایش داده می‌شوند و strict JSON schema برای افزایش احتمال ورودی JSON درست توصیه شده است. JSON Schema Draft 2020-12 هم vocabulary استانداردی برای توصیف و اعتبارسنجی ساختار داده JSON ارائه می‌کند.

این‌ها FACT درباره mechanism هستند. اینکه MAKNOW چه فیلدهایی را برای catalog اجباری بداند، کدام تغییر breaking محسوب شود، چه authority classهایی وجود داشته باشند و چه gateهایی deployment را متوقف کنند، DESIGN محلی است.

سه تفکیک را حفظ کنید:

• schema صحت ساختار را بررسی می‌کند، نه مجوز side effect را؛
• typed output سازگاری داده را بالا می‌برد، نه اینکه business meaning را به‌خودی‌خود درست کند؛
• SDK قابلیت handoff/tool می‌دهد، اما permission استفاده از آن‌ها باید از authority محلی بیاید.

توضیح عمیق Registry و Gateها

قرارداد اصلی ۲۱ ستون دارد:

agent_id, agent_version, purpose, owner_ref, input_schema_ref, output_schema_ref, structured_output_mode, tool_contract_ids, handoff_contract_ids, authority_class, allowed_actions, forbidden_actions, data_classification, memory_boundary_ref, guardrail_refs, failure_states, retry_contract_ref, compatibility_state, deprecation_state, catalog_status, evidence_ref.

Gate 1 — Stable identity

agent_id باید پایدار باشد و تغییر behavior ناسازگار نباید زیر همان version پنهان شود. اگر output schema عوض شده ولی version همان است، نتیجه success نیست؛ catalog باید آن را HOLD کند.

Gate 2 — Typed input/output

Caller نباید مجبور باشد free-text convention را از prompt حدس بزند. input/output contract باید reference قابل‌ردیابی داشته باشد. تغییر optional به required یک breaking change بالقوه است و باید compatibility مصرف‌کننده‌ها دوباره محاسبه شود.

Gate 3 — Tools و authority

ثبت tool در catalog به معنی مجازبودن اجرای آن نیست. tool پرریسک جدید باید authority class و allowed actions متناظر داشته باشد. اضافه‌کردن refund.execute به agentی که فقط read/recommend authority دارد یک mismatch است، حتی اگر function schema کاملاً معتبر باشد.

Gate 4 — Handoff dependency

Handoff یک dependency قراردادی است. اگر نسخه جدید handoff را حذف کند و consumer هنوز روی آن تکیه کند، consumer incompatible است؛ orchestration نباید صرفاً چون agent جدید «بهتر» است آن را active کند.

Gate 5 — Data/Memory boundary

هر agent باید data classification و memory boundary مشخص داشته باشد. customer_profile و public_web یک کلاس نیستند. catalog نباید به‌دلیل حضور یک agent در workflow، boundary حافظه یا داده را استنتاج کند.

Gate 6 — Failure و retry semantics

timeout, validation_error, guardrail_block, tool_denied, handoff_unavailable باید failure stateهای قابل‌نام‌گذاری باشند. retry نیز قرارداد جدا می‌خواهد؛ retry کور روی side effect خطرناک است.

Gate 7 — Compatibility و deprecation

COMPATIBLE, REVIEW_REQUIRED, INCOMPATIBLE, UNKNOWN باید جدا باشند. DEPRECATED یعنی «برای مصرف جدید انتخاب نکن»، نه اینکه داده‌های قبلی ناگهان invalid شوند. status نهایی باید با compatibility و deprecation سازگار باشد.

مثال‌های حل‌شده

۱. Baseline سالم: research-agent v1.2.0

ورودی ResearchRequest@1, خروجی ResearchBrief@2, structured output سخت‌گیرانه، tools فقط web.search و docs.read، handoff به editor-agent, authority برابر READ_RECOMMEND, data class برابر PUBLIC_OR_APPROVED_INTERNAL و memory boundary محدود به run/session ثبت شده است. failure stateها و retry contract مشخص‌اند و consumerها با output schema فعلی سازگارند. نتیجه ACTIVE / COMPATIBLE است.

۲. میان‌بُر غلط: schema عوض می‌شود، version نه

تیم خروجی را از ResearchBrief@2 به ResearchBrief@3 تغییر می‌دهد، یک فیلد required اضافه می‌کند، اما agent_version=1.2.0 می‌ماند. تست unit خود agent شاید سبز باشد، اما consumer قبلی contract جدید را نمی‌شناسد. Gate versioning باید این مورد را HOLD_VERSION_NOT_INCREMENTED کند.

۳. tool پرریسک بدون authority جدید

به support-agent ابزار refund.execute اضافه می‌شود، ولی authority_class=READ_RECOMMEND و allowed actions هنوز فقط read/recommend است. درست‌بودن JSON Schema ابزار مهم است، اما permission اجرای refund را نمی‌سازد. نتیجه HOLD_AUTHORITY_NOT_RECOMPUTED است.

۴. Transfer: نسخه جدید handoff را حذف می‌کند

publisher-agent v2 output schema را تغییر می‌دهد و handoff به legal-review-agent را حذف می‌کند. دو consumer هنوز output v1 را می‌خواهند و یکی به legal handoff وابسته است. نسخه جدید می‌تواند در catalog ثبت شود، اما consumerهای ناسازگار باید INCOMPATIBLE یا HOLD شوند تا migration انجام شود؛ baseline قبلی oracle نیست.

Failure modeهای رایج

• Prompt folklore: interface فقط در متن prompt وجود دارد.
• Display-name identity: دو agent با نام مشابه بدون stable id/version ثبت می‌شوند.
• Schema-without-semantics: JSON معتبر است ولی business meaning یا authority غلط است.
• Version camouflage: schema یا handoff breaking عوض می‌شود، version ثابت می‌ماند.
• Tool creep: ابزار جدید اضافه می‌شود، authority class و allowed actions بازبینی نمی‌شوند.
• Handoff drift: consumer به handoff وابسته است ولی producer آن را حذف کرده است.
• Memory ambiguity: memory boundary برابر UNKNOWN است اما agent ACTIVE می‌شود.
• Failure collapse: همه failureها به یک exception عمومی تبدیل می‌شوند و retry کور می‌شود.
• Deprecation contradiction: entry هم DEPRECATED است و هم برای مصرف جدید ACTIVE معرفی می‌شود.
• Baseline oracle: تصمیم نسخه قبلی بدون recompute به نسخه جدید کپی می‌شود.

گزینه‌ها و Trade-offها

قرارداد آزاد و کم‌ساختار onboarding سریع‌تری دارد، اما integration debt را به runtime منتقل می‌کند. Typed contract upfront هزینه بیشتری دارد، ولی failure را زودتر و قابل‌تکرارتر می‌کند. strict schema احتمال input ساختاری درست را بالا می‌برد، اما اگر schema بیش‌ازحد تنگ باشد evolution را سخت می‌کند. versioning محافظه‌کارانه migration را کندتر می‌کند، اما consumer breakage را آشکار می‌سازد.

Catalog مرکزی visibility بالایی می‌دهد ولی governance overhead دارد. catalog توزیع‌شده استقلال تیم‌ها را بالا می‌برد اما discovery و compatibility audit سخت‌تر می‌شود. هیچ trade-offی مجوز حذف authority، provenance یا compatibility state نیست.

پل مسیر باتجربه

برای هر تغییر agent فقط هفت سؤال بپرسید:

1. stable id/version چیست؟
2. input/output contract نسبت به نسخه قبل چه تغییری کرده؟
3. کدام tool یا handoff اضافه/حذف شده؟
4. authority و allowed actions هنوز دقیقاً همان تغییر را پوشش می‌دهند؟
5. data/memory boundary عوض شده؟
6. consumerهای موجود چه compatibility stateای می‌گیرند؟
7. failure/retry و deprecation چه تغییری می‌کنند؟

اگر پاسخ هر سؤال UNKNOWN است، ACTIVE را به‌صورت پیش‌فرض انتخاب نکنید.

تمرین هدایت‌شده و مستقل

ابتدا جدول derived_text/tables/AGN-003-T1.csv را ببینید و baseline را بخوانید. سپس اجرا کنید:

python -B lab/AGN-003-LAB1/learner/run_checks.py

در تمرین مستقل یک نسخه جدید بسازید که هم output schema را تغییر دهد و هم یک handoff را حذف کند. بدون نگاه‌کردن به decision baseline، catalog entry و وضعیت consumerها را دوباره محاسبه کنید. اگر consumer هنوز schema یا handoff قبلی را لازم دارد، آن را ناسازگار یا HOLD کنید؛ silent upgrade ممنوع است.

شواهد Verification

قبولی یعنی registry و تصمیم از fixtureهای آشکار بازتولید شود. Lab باید دست‌کم این موارد را رد کند:

• output schema changed + version unchanged؛
• high-impact tool added + authority unchanged؛
• required handoff removed while consumer still depends on it؛
• input optional→required without incompatible/review state؛
• decisive evidence missing but catalog forced to ACTIVE؛
• baseline decision reused in transfer.

هیچ reasoning پنهانی یا اتصال شبکه برای oracle لازم نیست. نتیجه باید از fieldها و ruleهای قابل‌مشاهده به‌دست آید.

Assessment و Transfer

ارزیابی سه بخش دارد: boundary، mutation diagnosis و transfer. در transfer، publisher-agent v2 هم output schema را عوض می‌کند و هم یک handoff را حذف می‌کند. learner باید مشخص کند کدام consumerها migrate می‌شوند، کدام‌ها INCOMPATIBLE یا HOLD می‌شوند و چرا.

جواب خوب فقط «نسخه را بالا ببر» نیست. باید نشان دهد version bump، schema compatibility، handoff dependency، authority و consumer state چگونه با هم تصمیم را می‌سازند. اگر تصمیم baseline عیناً کپی شود، transfer مردود است.

منابع و تازگی

• OpenAI Agents SDK — Agents: تعریف جاری agent، tools، handoffs، guardrails و structured outputs.
• OpenAI Agents SDK — Function schema: Pydantic model، JSON Schema و توصیه strict schema.
• JSON Schema Draft 2020-12: specification و validation vocabulary برای ساختار JSON.
• Frozen Lesson Bible lesson://AGN-003: authority محلی MAKNOW برای fieldها، compatibility stateها و release gateها.

ادعاهای Agents SDK تا 2026-10-18 یا زودتر در صورت تغییر مادی دوباره بررسی می‌شوند. JSON Schema 2020-12 به‌عنوان استاندارد پایه ثبت شده است. این درس هیچ action زنده، billing mutation یا داده واقعی کاربر را اجرا یا persist نمی‌کند.