agentrace شکست‌های پنهان در عامل‌های Claude Code را شناسایی می‌کند

تصور کنید یک گزارش ۳۴ مگابایتی دارید که حاوی ۱۵۲ اجرای مختلف از زیر-عامل‌های (subagents) هوش مصنوعی است؛ بررسی دستی این حجم از داده برای هر انسانی غیرممکن است. در اینجاست که agentrace وارد عمل می‌شود. هدف این ابزار، تضمین این موضوع است که توسعه‌دهندگان پاسخ‌های «مطمئن اما غلط» تولید شده توسط AI را به محیط عملیاتی یا تولید نهایی منتقل نکنند.

به نقل از گزارش وب‌سایت dev.to در ۱ اوت ۲۰۲۶، این ابزار دقیقاً برای حل سناریوهایی طراحی شده که در آن حجم داده‌ها فراتر از توان بررسی بشری است. بسیاری از توسعه‌دهندگان اکنون از Claude Code برای توزیع وظایف پژوهشی بین چندین زیر-عامل استفاده می‌کنند. این رویکرد در ادامه تحولاتی است که پس از آموزش ساخت عامل‌های هوش مصنوعی با Claude Code بدون نیاز به فریم‌ورک‌های پیچیده، شتاب گرفت. نویسنده گزارش اشاره می‌کند که حدود دو هفته وقت صرف توزیع ماموری‌های پژوهشی در گروه‌های ۱۰تایی کرده است. یافته‌ها نشان می‌دهد در حالی که این مدل‌ها در تولید کاندیداهای پاسخ عالی عمل می‌کنند، اما اغلب در تشخیص اینکه «چه چیزی واقعاً یک اثبات محسوب می‌شود» دچار مشکل می‌شوند. نتیجه این است که کاربر با یک «دیوار متنِ مطمئن» مواجه می‌شود، در حالی که خطاهای بحرانی در اعماق لاگ‌های جلسه (session logs) دفن شده‌اند. در واقع، مشکل تولید پاسخ نیست، بلکه اعتبارسنجی است؛ و شما نمی‌توانید چیزی را که نمی‌بینید، اعتبارسنجی کنید.

اکثر ابزارهای مدیریت عامل‌ها فرض می‌کنند که مدل، نقطه اصلی شکست است. با این حال، agentrace آشکار می‌کند که بخش قابل توجهی از شکست‌ها از مهندسی پرامپت (Prompt Engineering) خود کاربر ناشی می‌شود. این یافته‌ها با تحلیل‌های پیشین ما هم‌جهت است که نشان می‌داد پیچیدگی ارکستراسیون ابزارها در Claude Code، بیش از هوش ذاتی مدل، عامل اصلی بروز تکرارهای بی‌پایان است. در یک جلسه تست، ۱۲ مورد از ۳۶ اجرای علامت‌گذاری شده به این دلیل خطا داشتند که کاربر فراموش کرده بود «شکل خروجی» (output shape) را مشخص کند. در آن جلسه، یک‌سوم خطاها تقصیر کاربر بود، نه مدل.

سازوکار بدون نیاز به ابزار جانبی

برخلاف ابزارهای سنتی ردیابی (Tracing)، agentrace به هیچ SDK، Wrapper یا Decorator نیاز ندارد. این ابزار به جای اینکه یک Runtime باشد، به عنوان یک «خواننده» (Reader) عمل می‌کند. این سیستم از این واقعیت بهره می‌برد که Claude Code به‌طور خودکار تمام جلسات را در مسیر ~/.claude/projects/<slug>/<session-id>.jsonl روی دیسک ذخیره می‌کند.

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

این ابزار با تجزیهٔ (Parsing) فایل‌های JSONL موجود، هر فراخوانی زیر-عامل را با نتیجه‌اش جفت می‌کند. سپس با اعمال روش‌های تحلیل متنی خاص (Text Heuristics)، انسان را به سمت نتایجی هدایت می‌کند که نیاز به بررسی مجدد دارند. هدف این نیست که قضاوت انسانی جایگزین شود، بلکه هدف کوچک کردن محدوده جست‌وجو برای انسان است.

شکار الگوهای شکست خاموش

agentrace چندین الگوی شکست خاص را بر اساس رخدادهای واقعی (و نه حدسیات) شناسایی می‌کند:

• محدودیت‌های جلسه (Session Limits): عامل‌هایی که در میانه یک پیمایش (Sweep) می‌میرند. در این حالت، کار به‌طور خاموش از دست می‌رود و هیچ‌کس متوجه نمی‌شود تا زمانی که گزارش نهایی بیش از حد کوتاه بازگرداند.
• غیبت به مثابه دلیل (Absence as Evidence): زمانی رخ می‌دهد که یک عامل نتیجه می‌گیرد حقیقتی غلط است، صرفاً چون یک API برای حساب‌هایی که وجود ندارند، یک لیست خالی با کد HTTP 200 بازگردانده است. در اینجا، نبود داده دلیلی بر نبودنِ مورد نیست.
• ادعاهای مبهم (Hedged Claims): شناسایی عباراتی مانند «به نظر می‌رسد» (appears to be). این عبارات در سطح مدل صادقانه هستند، اما باگ زمانی رخ می‌دهد که این ابهام در مسیر رسیدن به تصمیم نهایی، به یک «واقعیت» تبدیل و ساده‌سازی شود.
• لینک‌های تأییدنشده (Unverified URLs): شناسایی زمانی که یک عامل تعداد زیادی لینک (پنج مورد یا بیشتر) ارائه می‌دهد، بدون اینکه در لاگ‌ها اثری از فرایندهای «تأیید»، «واکشی» (Fetching)، «تأییدیه» یا کد HTTP 200 باشد. این رفتار «تکمیل خودکار» است، نه «پژوهش».
• تسلیم شدن (Gave Up): شناسایی عباراتی مانند «نتوانستم پیدا کنم»، که ممکن است در یک نگاه سریع (Skim) نادیده گرفته شوند و شبیه به یک پاسخ به نظر برسند.
• شکست پرامپت (Prompt Failures): علامت‌گذاری موارد no_output_contract و thin_prompt. اگر یک وظیفه هیچ تعریف دقیقی از «پایان کار» (Done) نداشته باشد، قابل اعتبارسنجی نیست، زیرا سؤال هرگز به‌طور واقعی پرسیده نشده است.
• اجراهای کند (Slow Runs): هر زیر-عاملی که ۲۵ دقیقه در حال اجرا باشد، معمولاً در یک حلقه تکرار یا تلاش مجدد (Retry) گیر کرده است.

عملیاتی کردن اعتبارسنجی

این ابزار برای مدیریت سلامت عامل‌ها دستورات مختلفی ارائه می‌دهد. خلاصه‌های سطح بالا از طریق agentrace stats مدیریت می‌شوند که مواردی مانند زمان کل عامل‌ها (مثلاً ۲.۳ ساعت)، کندترین اجرا (مثلاً ۹.۵ دقیقه) و تعداد کاراکترهای نوشته شده (۳۵۰,۱۳۴) در برابر بازگشتی (۲۵۷,۷۲۱) را نشان می‌دهد. همچنین از فلگ --json برای خروجی‌های قابل خواندن توسط ماشین پشتیبانی می‌کند.

بازرسی‌های دقیق از طریق این دستورات انجام می‌شود:

• agentrace check: شناسایی اجراهای مشکل‌دار (مثلاً ۳۹ یافته در ۱۵۲ اجرا).
• agentrace check --severity high: فیلتر کردن نتایجی که قطعاً اهمیت دارند.
• agentrace check --strict: خروج با کد ۱ در صورت یافتن هر یافته با شدت بالا، که آن را برای محیط‌های CI/CD مناسب می‌کند.
• agentrace list: نمایش هر اجرا به همراه توصیف، مدت زمان و اندازه‌ها.
• agentrace show <id>: نمایش دقیق پرامپت، نتیجه و یافته‌های یک اجرای خاص.

برای جلوگیری از «هشدار کاذب» (Crying Wolf)، توسعه‌دهنده تستی به نام test_clean_run_produces_nothing را پیاده کرده است. این کار تضمین می‌کند که پرامپت‌های کوتاه اما معتبر — مانند گزارش ID تست‌های شکست‌خورده به عنوان node id همراه با پیام‌های Assertion — به دلیل «بیش از حد کوتاه بودن» خطا نگیرند. یک پرامپت ۱۱۳ کاراکتری می‌تواند کاملاً قابل اعتبارسنجی باشد. به طور خاص، ابزار اکنون برای فعال شدن هشدار، به هر دو سیگنال «طول کوتاه» و «نبود تعریف پایان» نیاز دارد. این تنظیم دقیق، تعداد یافته‌ها را در یک نمونه آزمایشی از ۱۶ مورد به ۹ مورد کاهش داد، بدون اینکه حتی یک مورد مثبت واقعی (True Positive) از دست برود.

محدودیت‌های فنی و حریم خصوصی

این ابزار برای سرعت و حریم خصوصی طراحی شده است؛ هیچ وابستگی به کتابخانه‌ای جز rich ندارد، نیازی به API Key ندارد و هیچ درخواست شبکه‌ای نمی‌فرستد. تمام عملیات روی فایل‌های محلی انجام می‌شود.

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

این رویکرد، نقش توسعه‌دهنده را از اعتماد کورکورانه به خلاصه‌های عامل‌ها، به «حسابرسی هدفمند» تغییر می‌دهد. با علامت‌گذاری «شکل» شکست به جای «حقیقتِ» محتوا، مرزی سخت بین اسکن اکتشافی (Heuristic) و اعتبارسنجی واقعی حفظ می‌شود. هر یافته یک «راهنما» است، نه یک حکم قطعی. یک اجرای بدون علامت، به معنای تأیید صحت نیست؛ بلکه صرفاً به این معناست که هیچ‌کدام از ۷ الگوی شناسایی شده را فعال نکرده است.

برای کسانی که گردش‌کارهای عامل‌محور پیچیده را اجرا می‌کنند، گام فوری بعدی، بازرسی لاگ‌های محلی .jsonl برای یافتن زبان‌های مبهم (Hedged) است که ممکن است تصمیم نهایی پروژه را مخدوش کرده باشد. در کنار این ابزار تشخیصی، استفاده از استراتژی‌های پیشگیرانه مانند جداسازی محیط‌های کدنویسی در agents-concerto می‌تواند به کاهش چشمگیر توهمات و خطاهای عامل‌ها کمک کند.

Repo: https://github.com/royalpinto007/agentrace

گام بعدی شما

• اگر از گردش‌کارهای عامل‌محور پیچیده استفاده می‌کنید، لاگ‌های .jsonl محلی خود را برای یافتن عبارات مبهم (Hedged Language) بررسی کنید.
• ابزار agentrace را در خط لوله CI/CD خود با فلگ --strict ادغام کنید تا از نشت پاسخ‌های تأییدنشده جلوگیری شود.
• پرامپت‌های خود را بازبینی کنید تا حتماً شامل یک «تعریف از پایان» (Definition of Done) باشند.

اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.