Agent Failure, Retry & Reconciliation

وقتی اجرای Agent با timeout یا exception تمام می‌شود، این اتفاق ثابت نمی‌کند که هیچ اثر جانبی رخ نداده است. ممکن است درخواست ابزار ارسال شده و سامانهٔ بیرونی تغییر را ثبت کرده باشد، اما پاسخ به ما نرسیده باشد. از طرف دیگر ممکن است اجرا پیش از هر فراخوانی ابزار و فقط به‌دلیل عبور از max_turns متوقف شده باشد. این دو وضعیت نباید یک recovery یکسان داشته باشند.

خروجی این درس Agent Failure, Retry & Reconciliation Ledger v1 است؛ دفترچه‌ای قابل ممیزی برای ثبت فاز خرابی، قطعیت اثر جانبی، صلاحیت retry، بودجه تلاش، backoff، reconciliation و escalation.

قاعده اول: خطا، شاهد خرابی است؛ نه مدرک «هیچ اتفاقی نیفتاده».

جهت درس و مرز مالکیت

AGN-006 مالک failure/retry/reconciliation است. AGN-005 مرز حافظه را پوشش می‌دهد و AGN-007 هزینه را. در این درس ممکن است attemptهای retry ثبت شوند، اما تصمیم نگهداری حافظه یا محاسبه هزینه جذب نمی‌شود.

مدل ذهنی: شش لایه جدا

1. شاهد خرابی: چه چیزی، در چه فازی و با چه خطایی شکست خورد؟
2. قطعیت اثر جانبی: NOT_STARTED، CONFIRMED_ABSENT، CONFIRMED_APPLIED یا UNKNOWN_AFTER_TIMEOUT.
3. کنترل retry: eligibility، دلیل، بودجه attempt، شماره attempt، backoff و سلامت dependency.
4. کنترل ایمنی: idempotency key یا مسیر محدود compensation/reconciliation.
5. Reconciliation: مقایسه حالت مشاهده‌شده با منبع authoritative.
6. Disposition: success، retry امن، hold، compensate، escalate یا stop.

موفقیت attempt بعدی، ambiguity attempt قبلی را پاک نمی‌کند.

پایه‌ها: FACT فعلی در برابر DESIGN محلی

مستندات فعلی OpenAI Agents SDK failureهای متفاوتی مثل MaxTurnsExceeded، ModelTimeoutError، ToolTimeoutError و خطاهای رفتار مدل را از هم جدا می‌کنند. حتی timeout ابزار می‌تواند به‌صورت error قابل‌مشاهده برای مدل یا exception سخت تنظیم شود. این‌ها FACT اجرایی‌اند، نه سیاست retry کسب‌وکار.

راهنمای AWS نیز دربارهٔ retry، بار اضافی روی dependency خراب، backoff/jitter و اهمیت idempotency در عملیات side-effecting هشدار می‌دهد.

taxonomy دقیق MAKNOW، بودجه attempt، reconciliation و escalation همگی DESIGN محلی‌اند.

توضیح عمیق Ledger

Contract بحرانی ۱۸ بُعد دارد: run_id, attempt_id, failure_class, failure_phase, error_evidence_ref, side_effect_state, idempotency_key, retry_eligible, attempt_budget, attempt_number, backoff_policy_ref, dependency_health, reconciliation_required, authoritative_state_ref, reconciliation_state, human_escalation_required, final_disposition, audit_ref.

Gateهای اصلی:

• UNKNOWN_AFTER_TIMEOUT به‌تنهایی اجازه retry نمی‌دهد.
• retry عملیات side-effecting نیازمند idempotency یا کنترل compensation/reconciliation است.
• attempt نمی‌تواند از budget عبور کند.
• dependency خراب، retry فوری را بدون backoff/escallation نامعتبر می‌کند.
• reconciliation بدون authoritative state معتبر بسته نمی‌شود.
• success درحالی‌که side effect یا reconciliation هنوز unknown است پذیرفته نیست.

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

۱. Timeout بعد از ارسال ابزار

درخواست synthetic اصلاح سفارش ارسال می‌شود و سپس model timeout رخ می‌دهد. side_effect_state=UNKNOWN_AFTER_TIMEOUT است. به‌جای retry کور، وضعیت authoritative سفارش خوانده می‌شود و مشخص می‌شود تغییر قبلاً اعمال شده است. نتیجه MATCHED_APPLIED و disposition برابر RECONCILED_SUCCESS_NO_RETRY می‌شود.

۲. Shortcut غلط

side effect را unknown نگه دار، retry_eligible=true بگذار و idempotency key را حذف کن. این وضعیت HOLD می‌شود؛ چون timeout عدم وقوع اثر را ثابت نکرده است.

۳. Transfer

اجرای دوم پیش از هر ابزار به max_turns می‌رسد اما dependency پایین‌دستی degraded است. ambiguity اثر جانبی baseline دیگر وجود ندارد، ولی retry باید بر اساس سلامت dependency و backoff دوباره محاسبه شود.

failure modeها

• timeout را oracle «هیچ اتفاقی نیفتاده» دانستن؛
• retry کور عملیات side-effecting؛
• عبور از attempt budget؛
• hot-loop روی dependency degraded؛
• پنهان‌کردن attempt مبهم با success بعدی؛
• reconciliation بدون authoritative state؛
• compensation بدون evidence؛
• reuse تصمیم baseline در context جدید.

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

سیاست recovery می‌تواند fail-fast، retry، reconcile، compensate یا escalate باشد. retry سریع latency را کم می‌کند ولی می‌تواند بار failure را تشدید کند. idempotency retry را ایمن‌تر می‌کند اما جای budget را نمی‌گیرد. reconciliation correctness را بالا می‌برد ولی latency و نیاز به authoritative state دارد. escalation انسانی ریسک automation را کم می‌کند ولی هزینه عملیاتی دارد.

پل برای افراد باتجربه

پنج سؤال را جواب بده:

1. failure نسبت به side effect کجا رخ داده؟
2. چه evidenceای نبودن/اعمال‌شدن/unknown بودن اثر را ثابت می‌کند؟
3. attempt بعدی داخل budget و با سلامت dependency سازگار است؟
4. authoritative state چیست؟
5. final disposition با کدام evidence قابل بازسازی است؟

اگر یکی unknown است، success خودکار بیش از حد قوی است.

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

فایل derived_text/tables/AGN-006-T1.csv را ببین و اجرا کن:

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

در تمرین مستقل، یک failure بعد از side-effecting tool و یک failure قبل از همه ابزارها بساز و نشان بده چرا recovery آن‌ها یکسان نیست.

شواهد تأیید

شاهد قبولی، exception screenshot نیست؛ Ledger قابل بازسازی است. Lab باید retry با side effect مبهم، idempotency گمشده، budget تمام‌شده، dependency degraded بدون backoff، reconciliation بدون authority و success با state حل‌نشده را رد کند.

ارزیابی و Transfer

Transfer همان incident baseline نیست: max-turn پیش از tool رخ می‌دهد و dependency هم degraded است. side-effect ambiguity baseline حذف شده، اما dependency health و backoff مهم‌تر شده‌اند. disposition باید از evidence جدید ساخته شود و decision baseline قابل کپی نیست.

منابع و تازگی

• OpenAI Agents SDK — Running agents / Exceptions / Tool timeout behavior: فقط مکانیزم‌های runtime فعلی.
• AWS Builders Library — Timeouts, retries and backoff with jitter: راهنمای retry محدود، overload، jitter و idempotency.
• Frozen Lesson Bible lesson://AGN-006: authority محلی MAKNOW برای taxonomy، budget، reconciliation و escalation.

معانی SDK تا ۲۰۲۶-۱۰-۱۸ یا زودتر در صورت تغییر مهم دوباره بررسی شوند. Lab کاملاً synthetic است و هیچ اقدام زنده انجام نمی‌دهد.