Agent Monitoring and Reliability
Build a trace log for an agent, set step, retry and budget limits and stop-on-forbidden-action before running, catch silent failures with four monitoring layers, and report rates without hiding unevaluated runs.
بعد از این درس میتوانی
- حداقل ردپای قابل استفاده را برای هر اجرای ایجنت تعریف و ثبت کند؛ آنچه در دسترس نیست UNKNOWN یا NOT_AVAILABLE بنویسد.
- پیش از اجرا Max_Steps، Max_Retries، Per_Run_Budget و Stop_On_Forbidden_Action را تعیین کند و رفتار درست در برابر 403 و timeout را بداند.
- خرابی معنایی (اجرای سبز با نتیجهٔ غلط) را از خرابی زیرساختی جدا کند.
- نرخ قبولی را با دو مخرج (قابلارزیابی و کل) گزارش کند و برای هر هشدار صاحب و اقدام بعدی بگذارد.
چرا این درس مهم است
ورکفلوی گزارش هفتگی در داشبورد n8n سبز بود. هیچ خطایی، هیچ هشداری. ولی سه هفته بود که ابزار تیکت 403 میداد و ایجنت در گزارش مینوشت «هیچ تیکت بازی نداریم». مدیر خوشحال بود.
سبز بودن اجرا یعنی کد کرش نکرده، نه اینکه نتیجه درست است. ایجنتها معمولاً بیصدا خراب میشوند: خطای ابزار را با یک جملهٔ مطمئن میپوشانند. این درس دربارهٔ دیدن همین خرابیهاست.
مفاهیم کلیدی
یادآوری: خطایابی و Error Trigger در «خطایابی n8n» و پایش زیرساخت در «پایش و نسخهبندی n8n» آمدهاند. اینجا پایش رفتار و نتیجهٔ ایجنت است.
- Trace (ردپا): تصویر کامل یک اجرا. Span (گام): یک عملیات داخل آن، مثل یک فراخوانی ابزار، با زمان شروع و پایان، پدر و فرزند، ویژگیها و وضعیتsrc-otel-traces.
- حداقل ردپا: Run_ID، Case_ID، نسخهٔ ایجنت و مدل، زمان، نام ابزار، آرگومانهای غیرحساس، وضعیت، شمار تلاش، توکن (اگر در دسترس)، زمان پاسخ، خلاصهٔ خروجی.
- NOT_AVAILABLE برای استدلال داخلی: بیشتر سرویسها فکر داخلی مدل را نمیدهند یا خلاصهاش را میدهند؛ پژوهشها هم نشان میدهند پایش آن محدودیت داردsrc-openai-cot-monitor. پس ستونی برایش نساز که با حدس پر شود.
- Silent Failure (خرابی بیصدا): اجرای موفق ظاهری با نتیجهٔ غلط یا ناقص.
- Guardrail Limits:
Max_Steps،Max_Retries،Per_Run_Budget،Stop_On_Forbidden_Action؛ پیش از اجرا، نه بعد از حادثه. - PARTIAL_DATA_WARNING: خروجی ناقص با برچسب و استثنای صریح؛ دادهای که نیامده هرگز صفر نیست.
مدل ذهنی
ردپا مثل جعبهٔ سیاه هواپیما است: وقتی همهچیز خوب است کسی بازش نمیکند، ولی بدون آن بعد از حادثه فقط حدس داری. سقفها (گام، تلاش، هزینه) مثل فیوز برقاند: قبل از آتشسوزی قطع میکنند.
این تشبیه کجا غلط است؟ جعبهٔ سیاه همهچیز را ضبط میکند. ردپای ایجنت فقط چیزی را دارد که تو یا ابزار ثبت کردهاید، و فکر داخلی مدل معمولاً در آن نیست. پس اگر ستونی را ثبت نکردهای، بعداً نمیتوانی ادعا کنی میدانی چه شده.
گامبهگام
گام ۱: دفتر ردپا را تعریف کن
در کارپوشهٔ درس، کاربرگهای Tool_Events و Runs همان دفتر ردپای حداقلیاند. هر ستونی که سرویس نمیدهد (مثلاً توکن)، UNKNOWN؛ هرگز تخمین در جای عدد واقعی.
گام ۲: سقفها را پیش از اجرا بنویس
| سقف | مثال | وقتی خورد |
|---|---|---|
| Max_Steps | ۸ گام برای ایجنت پژوهش | توقف با گزارش وضعیت؛ نه ادامهٔ بیپایان |
| Max_Retries | خطای 403: صفر تلاش دوباره؛ timeout: یک تلاش | علامت خطا و ادامه با دادهٔ ناقص برچسبخورده |
| Per_Run_Budget | سقف توکن یا هزینهٔ هر اجرا | توقف و هشدار به صاحب |
| Stop_On_Forbidden_Action | هر تلاش برای ابزار ممنوع | توقف فوری و ثبت |
403 یعنی مجوز نداری؛ تلاش دوباره درستش نمیکند. timeout ممکن است گذرا باشد؛ یک تلاش کنترلشده منطقی است.
گام ۳: چهار لایهٔ پایش
- سلامت اجرا: کرش کرد؟ تمام شد؟ (همان سبز و قرمز داشبورد)
- ابزارها: کدام ابزار چه وضعیتی داد، چند تلاش؟
- صحت معنایی: همهٔ اقلام پوشش داده شدند؟ عددها با منبع میخوانند؟ (با داور قطعی درس قبل، روی نمونهای از اجراهای واقعی)
- منابع و مجوز: هزینه، زمان، و اینکه از چه دسترسیای استفاده شد.
لایهٔ ۱ سبز و لایهٔ ۳ قرمز = خرابی بیصدا. همان داستان اول درس.
گام ۴: شاخصها را جدا و صادقانه گزارش کن
Completion_Rate، Outcome_Pass_Rate، Required_Tool_Pass_Rate، Unauthorized_Action_Count، P95_Latency و Cost_Per_Success را جدا نگه دار. مثال: ۱۰ اجرا، ۸ PASS، ۱ FAIL، ۱ NOT_EVALUABLE ⟵ قبولی از اجراهای قابلارزیابی ۸/۹ و از کل ۸/۱۰. هر دو را بنویس؛ پنهانکردن ارزیابینشدهها در مخرج، عدد را قشنگتر از واقعیت میکند.
گام ۵: هر هشدار صاحب دارد
برای هر اجرای خطادار: نوع هشدار، شدت، صاحب، اقدام بعدی، و اینکه ایجنت متوقف شود یا ادامه دهد. هشداری که صاحب ندارد، فقط نویز است.
ابزارها (اختیاری، تاریخدار)
| ابزار | طرح رایگان یا متنباز (۲ نوامبر ۲۰۲۶) | نکته |
|---|---|---|
| Langfuse | Hobby ابری رایگان با سهمیهٔ ماهانه؛ نسخهٔ self-host | self-host یعنی نرمافزار رایگان، نه سرور رایگانsrc-langfuse-pricing |
| Arize Phoenix / AX | Phoenix متنباز؛ AX Free ابری با سهمیه | Phoenix و AX دو محصول جدا هستندsrc-arize-pricing |
| Comet Opik | متنباز و ابری رایگان با سهمیه | با Comet MLOps اشتباه نشودsrc-opik-pricing |
| LangSmith | Developer رایگان با سهمیهٔ Trace | بعد از سهمیه، پرداخت بر اساس مصرفsrc-langsmith-pricing |
| Promptfoo | Community متنباز | بیشتر برای آزمون رگرسیون و امنیتsrc-promptfoo-pricing |
| صفحهگسترده | — | ثبت دستی؛ بدون ردپای خودکار |
همهٔ اینها منبع ذینفعاند و سهمیهها تغییر میکنند. انتخاب ابزار بعد از این است که بدانی چه چیزی را باید ببینی.
مثالها
ردپای خرابی بیصدا (ساختگی):
| گام | ابزار | وضعیت | یادداشت |
|---|---|---|---|
| 1 | Read_Sales_Sheet | OK | فیلتر تاریخ: هفتهٔ قبل (اشتباه) |
| 2 | Calculate_Metrics | OK | |
| 3 | Read_Tickets_Sheet | OK | ۰ ردیف برگشت |
| 4 | Draft_Report | OK | «هفتهٔ بدون مشکل؛ صفر تیکت باز» |
همه OK. ولی فیلتر تاریخ غلط است و «۰ ردیف» از ابزار تیکت با «صفر تیکت» یکی گرفته شده. ممیزی باید فیلتر تاریخ، منشأ عددها و تعداد ردیفها را مقایسه کند. حکم: FAIL یا PARTIAL_NEEDS_REVIEW، نه PASS.
پیادهسازی
- برای ایجنت یا ورکفلوی خودت، ستونهای حداقل ردپا را در یک کاربرگ بساز.
- چهار سقف را با عدد بنویس و رفتار هنگام خوردن هرکدام را مشخص کن.
- در کارپوشه یک اجرای تازه اضافه کن که ابزار تیکت ۰ ردیف برگرداند و گزارش «صفر تیکت» بگوید. چه ستون یا قاعدهای این را میگیرد؟ (راهنما: «۰ ردیف» از ابزار با «۰ تیکت» در منبع فرق دارد؛ شمار ردیف منبع را جدا ثبت کن.)
- جدول شاخصها را با دو مخرج بساز.
- برای سه نوع هشدار (خطای ابزار، ابزار ممنوع، عبور از بودجه) صاحب و اقدام بنویس.
اشتباههای رایج
| اشتباه | نتیجه | کار درست |
|---|---|---|
| سبز بودن داشبورد = درستی | خرابی بیصدا | لایهٔ صحت معنایی روی نمونه |
| تلاش دوباره روی 403 | هزینه و قفل حساب، بدون حل | 403: توقف و گزارش |
| «۰ ردیف» = «صفر مورد» | گزارش غلط مطمئن | دادهٔ نیامده = نامعلوم |
| ستون «استدلال مدل» با حدس | شاهد ساختگی | NOT_AVAILABLE |
| پنهانکردن NOT_EVALUABLE | نرخ قبولی متورم | دو مخرج |
| سقفها بعد از حادثه | هزینه یا اقدام بیکنترل | پیش از اجرا |
| هشدار بدون صاحب | نویز؛ کسی کاری نمیکند | صاحب و اقدام برای هر هشدار |
عیبیابی
ایجنت گاهی تا دهها گام ادامه میدهد.
شرط توقف مبهم یا ابزاری که مدام خطای گذرا میدهد.
در ردپا ببین کدام ابزار تکرار میشود.
Max_Steps و Max_Retries بگذار؛ شرط «تمام شد» را در مأموریت دقیق کن.
گزارشها کاملاند ولی یک منبع داده هفتههاست خالی برمیگردد.
خطای ابزار به خروجی خالی تبدیل شده و مدل آن را «هیچ موردی» خوانده.
تعداد ردیف برگشتی هر ابزار را در زمان ثبت کن و روند را ببین.
قاعده: صفر ردیف از منبعی که معمولاً داده دارد ⟵ هشدار و PARTIAL_DATA_WARNING.
ابزار پایش طرح رایگان سهمیه را تمام کرد و ثبت متوقف شد.
سهمیهٔ ماهانهٔ طرح.
صفحهٔ مصرف ابزار را ببین.
نمونهبرداری کن (مثلاً یک اجرا از ده تا) یا موقتاً به ثبت در صفحهگسترده برگرد؛ دورهٔ بدون ثبت را در گزارش اعلام کن.
توکن و هزینه را سرویس نمیدهد.
بعضی سرویسها و رابطهای چت مصرف را نشان نمیدهند.
مستند سرویس را چک کن.
UNKNOWN بنویس؛ هزینه را از صورتحساب کل تقسیم بر تعداد اجرا تخمین بزن و برچسب «تخمین» بگذار.
تمرین کوتاه
تمرین · 8 دقیقه
داده (ساختگی): ۲۰ اجرا در هفته: ۱۴ PASS، ۲ FAIL، ۴ NOT_EVALUABLE (ثبت ردپا قطع بوده). مدیر میخواهد یک عدد: «نرخ موفقیت».
راهحل نمونه
- قبولی از قابلارزیابی: ۱۴/۱۶ = ۸۷٫۵٪.
- قبولی از کل: ۱۴/۲۰ = ۷۰٪.
- هر دو را با تعداد NOT_EVALUABLE گزارش کن و بگو ۲۰٪ اجراها بدون شاهدند؛ مشکل ثبت باید اول حل شود.
چالش: برگهٔ پایش ایجنت خودت
تمرین · 35 دقیقه
تحویل:
- ستونهای حداقل ردپا با توضیح اینکه هرکدام از کجا میآید یا چرا UNKNOWN است.
- چهار سقف با عدد و رفتار هنگام خوردن.
- چهار لایهٔ پایش: برای هرکدام یک شاخص و یک آستانهٔ هشدار.
- جدول هشدارها: نوع، شدت، صاحب، اقدام، توقف یا ادامه.
- یک سناریوی خرابی بیصدای ساختگی و قاعدهای که آن را میگیرد.
معیار پذیرش:
- هیچ ستونی با حدس پر نمیشود.
- 403 و timeout رفتار متفاوت دارند.
- نرخها دو مخرج دارند.
- هر هشدار صاحب دارد.
- قاعدهٔ خرابی بیصدا با دادهٔ ساختگی امتحان شده.
خودسنجی
جمعبندی
- سبز بودن اجرا یعنی کرش نکرده، نه درست بوده.
- ردپای حداقلی را ثبت کن؛ آنچه نیست UNKNOWN یا NOT_AVAILABLE.
- سقف گام، تلاش، بودجه و توقف روی اقدام ممنوع پیش از اجرا.
- 403 را تکرار نکن؛ دادهٔ نیامده را صفر نکن.
- چهار لایه: سلامت، ابزار، صحت معنایی، منابع و مجوز.
- نرخها با دو مخرج؛ هر هشدار صاحب دارد.
پرسشهای سنجش
ابزار CRM برای ایجنت 403 برمیگرداند و ایجنت پنج بار پشت سر هم دوباره تلاش میکند. چه چیزی غلط است و سقف درست چیست؟
پاسخ نمونه و معیار ارزیابی
403 یعنی نبود مجوز و تلاش دوباره حلش نمیکند؛ فقط هزینه و ریسک قفل حساب دارد. Max_Retries برای 403 صفر: ثبت خطا، PARTIAL_DATA_WARNING و گزارش به صاحب.
- معنای 403 (1 امتیاز)
- سقف صفر برای 403 (1 امتیاز)
- خروجی ناقص برچسبخورده و هشدار (1 امتیاز)
کدام ستون را نباید با حدس پر کنی و باید NOT_AVAILABLE بماند؟
- نام ابزار
- استدلال داخلی مدل وقتی سرویس آن را نمیدهد
- Run_ID
- وضعیت ابزار
پاسخ نمونه و معیار ارزیابی
- a ← نام ابزار همیشه ثبتشدنی است.
- c ← Run_ID را خودت میسازی.
- d ← وضعیت از پاسخ ابزار میآید.
داشبورد ورکفلو کاملاً سبز است ولی کاربرها میگویند گزارشها هفتهای یک بار عدد غلط دارند. کجا را نگاه میکنی؟
پاسخ نمونه و معیار ارزیابی
خرابی بیصدا: لایهٔ صحت معنایی. روی نمونهای از اجراها داور قطعی (شمارش ردیف، فیلتر تاریخ، منشأ عدد) اجرا میکنم و ردپای اجراهای غلط را با درست مقایسه میکنم؛ مثلاً فیلتر تاریخ یا خروجی خالی یک ابزار.
- خرابی بیصدا (1 امتیاز)
- لایهٔ معنایی با داور قطعی (1 امتیاز)
- مقایسهٔ ردپا (1 امتیاز)
برای ایجنت پژوهشی چهار سقف را با عدد و رفتار بنویس.
پاسخ نمونه و معیار ارزیابی
مثلاً: Max_Steps = ۸ ⟵ توقف با گزارش آنچه پیدا شده؛ Max_Retries = ۱ برای timeout، ۰ برای 403 ⟵ علامت منبع نامعلوم؛ Per_Run_Budget = سقف توکن مشخص ⟵ توقف و هشدار؛ Stop_On_Forbidden_Action = هر تلاش برای ارسال یا انتشار ⟵ توقف فوری و ثبت.
- چهار سقف با عدد (1 امتیاز)
- رفتار هنگام خوردن (1 امتیاز)
- تفاوت 403 و timeout (1 امتیاز)
تیم میخواهد فقط نرخ «قبولی از اجراهای قابلارزیابی» را گزارش کند چون عدد بهتری است. نظرت؟
پاسخ نمونه و معیار ارزیابی
نه بهتنهایی. هر دو مخرج را با تعداد NOT_EVALUABLE گزارش کن؛ وگرنه اجراهای بیشاهد که ممکن است همان خرابها باشند، پنهان میشوند و مشکل ثبت هم دیده نمیشود.
- رد گزارش یکمخرجی (1 امتیاز)
- خطر پنهانشدن اجراهای خراب (1 امتیاز)
- گزارش تعداد NOT_EVALUABLE (1 امتیاز)
فایلهای درس
کارپوشهٔ ارزیابی ایجنت با ۹ مورد آزمون و ۱۱ اجرای ساختگی
agent-evals-workbook.xlsxابزارها و جایگزینها
- صفحهگسترده — کارپوشهٔ ارزیابی، دفتر رویداد و محاسبهٔ هزینه — Excel — Google Sheets — LibreOffice Calc
- ابزار پایش (اختیاری) — ثبت خودکار ردپا — Langfuse — Arize Phoenix — Comet Opik — LangSmith — فقط صفحهگسترده
منابع
Traces (OpenTelemetry concepts) OpenTelemetry 2026-01-14
Evaluating chain-of-thought monitorability OpenAI (منبع ذینفع) checked 2026-11-02
Langfuse Pricing Langfuse (منبع ذینفع) checked 2026-11-02
Arize Pricing (Phoenix OSS / AX) Arize (منبع ذینفع) checked 2026-11-02
Comet Opik Pricing Comet (منبع ذینفع) checked 2026-11-02
LangSmith Pricing LangChain (منبع ذینفع) checked 2026-11-02
Promptfoo Pricing Promptfoo (منبع ذینفع) checked 2026-11-02