تصور کنید یک درخواست ساده از کاربر، زنجیره‌ای کور از فراخوانی‌های مدل و اجرای ابزارها را فعال می‌کند که هیچ راهی برای دیدن درون آن ندارید؛ این همان واقعیت «جعبه سیاه» در عیب‌یابی سامانه‌های عامل‌محور است. برای حل این بحران، در ۱۴ سپتامبر ۲۰۲۶، راهکاری جامعه‌محور به نام dsh-plugin-agent-insights منتشر شد تا قابلیت مشاهده‌پذیری (Observability) دقیق و محدود به جلسه را برای اکوسیستم DeepSeek Harness فراهم کند.
بسیاری از توسعه‌دهندگان در حال حاضر فقط خروجی نهایی یک عامل (Agent) — شبیه به مدیری که فقط گزارش نهایی را می‌بیند و نمی‌داند کارمندش کجا گیر کرده است — را مشاهده می‌کنند و نمی‌دانند چرا یک گردش‌کار خاص شکست خورده یا کدام ابزار باعث ایجاد گلوگاه شده است. این افزونه با تبدیل مشاهده‌پذیری به یک لایه مجزا که چرخه حیات عامل را از بیرون می‌پاید، تجربه عیب‌یابی را تغییر می‌دهد. این سیستم را می‌توان به جعبه سیاه هواپیما تشبیه کرد؛ ابزاری که هواپیما را نمی‌راند، اما هر چرخش و لرزش موتور را برای تحلیل‌های بعدی ثبت می‌کند. این رویکرد در واقع تکامل یافته‌ی همان ساختاری است که DeepSeek برای تبدیل قابلیت‌های LLM به پلاگین‌های کاربردی در ساخت عامل‌های خودمختار به کار گرفته بود.
همان‌طور که در تحلیل‌های پیشین ما درباره‌ی امنیت و پایداری مدل‌های زبانی اشاره کردیم، شفافیت در لایه‌های میانی اجرای مدل، کلید رسیدن به سیستم‌های قابل اعتماد است.
نیاز به مشاهده‌پذیری در سطح جلسه
وقتی یک درخواست به چندین فراخوانی مدل، گام‌های عامل و اجرای ابزارها تبدیل می‌شود، توسعه‌دهندگان برای عیب‌یابی مؤثر به پاسخ‌های دقیقی نیاز دارند. طبق مستندات این پروژه، سوالات کلیدی که این افزونه به آن‌ها پاسخ می‌دهد عبارت‌اند از:
- چه تعداد گام توسط عامل اجرا شد؟
- چند درخواست به مدل زبانی بزرگ (LLM) — مثل کتابخانه‌داری که میلیاردها صفحه را خوانده و حالا با همان لحن جواب می‌دهد — ارسال شد و چند مورد از آن‌ها با شکست مواجه شد؟
- کدام ابزارهای خاص فراخوانی شدند؟
- اجرای کدام ابزار بیشترین زمان را گرفت و باعث کندی شد؟
- کل زمان اجرای یک جلسه از ابتدا تا انتها چقدر بود؟
- پس از پایان جلسه، چه اتفاقی برای وضعیت و داده‌های جمع‌آوری‌شده می‌افتد؟
معماری ردیابی غیرتهاجمی
این افزونه به عنوان یک سرویس Cordis پیاده‌سازی شده و خود را به عنوان ctx.agentInsights ثبت می‌کند. به گزارش وب‌سایت dev.to، فلسفه اصلی طراحی این است که لایه مشاهده‌پذیری هرگز نباید به یک نقطه شکست (Failure Point) تبدیل شود. اگر ثبت یک معیار (Metric) با خطا مواجه شود، افزونه خطا را مدیریت کرده و اجازه می‌دهد عامل به فعالیت عادی خود ادامه دهد. این سازوکار از طریق یک بلوک try-catch داخلی مدیریت می‌شود که تنها یک هشدار با متن [agent-insights] Failed to record metric ثبت می‌کند و هرگز جریان اجرای عامل را متوقف نمی‌کند. این متدولوژی ردیابی بدون وقفه، یادآور رویکرد سیستم AgentSight در تجزیه توکن‌ها بدون تغییر در کد است که بر حفظ پایداری سیستم در حین نظارت تأکید دارد.
برای جلوگیری از نشت حافظه (Memory Leak) در فرآیندهای طولانی‌مدت، افزونه از معماری WeakMap<Session, SessionAgentInsights> استفاده می‌کند. این ساختار تضمین می‌کند که آمار جلسات به‌طور مستقل ذخیره شده و پس از حذف جلسه (Dispose)، به‌طور خودکار توسط Garbage Collector پاک شوند تا از کند شدن برنامه در طول زمان جلوگیری شود. این معماری «بدون نشت» (Zero-Leak) اجازه می‌دهد افزونه کندترین فراخوانی ابزار را در تمام جلسات فعال ردیابی کند، بدون اینکه ارجاعات دائمی به آن جلسات نگه دارد.
جمع‌آوری دقیق معیارها
افزونه برای جمع‌آوری داده‌ها بدون دخالت در مسیر اجرای عامل، به رویدادهای خاص چرخه حیات متصل می‌شود:
- معیارهای LLM و عامل: رصد رویداد
agent/requestبرای افزایش شمارنده کل درخواست‌ها (stats.totalLlmRequests += 1) و رصدagent/request-errorبرای ردیابی درخواست‌های شکست‌خورده مدل (stats.failedLlmRequests += 1). همچنین گام‌های تکمیل‌شده از طریق رویدادsession/eventشمارش می‌شوند. - عملکرد ابزار: با پوشاندن (Wrapping) اجرای ابزار حول تابع
next()، افزونه ازperformance.now()برای اندازه‌گیری دقیق مدت‌زمان اجرا استفاده می‌کند. برای هر فراخوانی، یک شیء داده‌ای شاملcallId(شناسه فراخوانی)،name(نام ابزار)،durationMs(مدت‌زمان به میلی‌ثانیه)،isError(وضعیت خطا) وerrorMessage(پیام خطا) ثبت می‌شود. - چرخه حیات جلسه: زمان دقیق شروع و مدت‌زمان کل elapsed ثبت می‌شود. با فعال شدن رویداد
session/disposed(حذف جلسه)، افزونه معیارها را استخراج کرده، مدت‌زمان نهایی را محاسبه می‌کند و ورودی مربوط به آن جلسه را از WeakMap حذف می‌کند.
تفکیک معیارهای ثبت‌شده
این افزونه چهار حوزه اصلی از عملیات عامل را به‌طور تفکیک شده ردیابی می‌کند:
- گام‌های عامل: مجموع گام‌های بسته شده (Closed Steps) و کل درخواست‌های ارسالی به مدل.
- اجرای ابزار: مجموع فراخوانی‌ها، تعداد فراخوانی‌های موفق، تعداد فراخوانی‌های شکست‌خورده و شناسایی دقیق کندترین ابزار.
- عملکرد: مدت‌زمان دقیق اجرای هر بخش و زمان کل جلسه.
- چرخه حیات: زمان شروع جلسه و وضعیت نهایی پاک‌سازی یا حذف.
پیاده‌سازی و پیکربندی
توسعه‌دهندگان می‌توانند از طریق Context در Cordis یا با استفاده از دستور dsh plugin --profile <name> add dsh-plugin-agent-insights در CLI مربوط به Harness، این افزونه را یکپارچه کنند. سیستم از طریق فایل cordis.patch.yml به‌شدت قابل تنظیم است.
گزینه‌های پیکربندی عبارت‌اند از:
maxToolHistoryPerSession: کنترل تعداد رکوردهای اجرای ابزار که در هر جلسه نگه داشته می‌شوند (مقدار پیش‌فرض ۱۰۰۰ است).logSummaryOnDisposed: یک مقدار بولی (Boolean) برای فعال یا غیرفعال کردن ثبت خلاصه گزارش در لحظه پایان جلسه.
برای نصب برنامه‌نویسی‌شده، توسعه‌دهندگان از الگوی زیر استفاده می‌کنند:import { Context } from '@deepseek-ai/cordis'import AgentInsights from 'dsh-plugin-agent-insights'const ctx = new Context()await ctx.plugin(AgentInsights, { maxToolHistoryPerSession: 500, logSummaryOnDisposed: true })
این افزونه سه API اصلی برای پرس‌وجوی وضعیت عامل در لحظه (Real-time) ارائه می‌دهد: getMetrics(session) برای دریافت معیارها، getSlowestTool(session?) برای یافتن کندترین ابزار و reset(session?) برای بازنشانی آمار.
اسنپ‌شات‌های جلسه و خروجی
یک اسنپ‌شات از جلسه، نمایی فشرده از کل نشست عامل را ارائه می‌دهد که شامل موارد زیر است: sessionId (شناسه جلسه)، sessionStartTime (زمان شروع)، sessionDurationMs (مدت‌زمان به میلی‌ثانیه)، totalSteps (کل گام‌ها)، totalLlmRequests (کل درخواست‌های مدل)، failedLlmRequests (درخواست‌های شکست‌خورده)، totalToolCalls (کل فراخوانی ابزارها)، successfulToolCalls (فراخوانی‌های موفق)، failedToolCalls (فراخوانی‌های شکست‌خورده)، toolExecutions (لیست اجراها) و slowestTool (کندترین ابزار).
یک نمونه از خلاصه نهایی لاگ به این شکل است:
"Session completed 8 steps, 5 LLM requests, 1 failed request, 12 tool calls, 2 failed tools, 14.32s duration. Slowest tool: database-query."
تحلیل: تغییر پارادایم عیب‌یابی عامل‌ها
این توسعه نشان‌دهنده تغییری در نگاه جامعه به چارچوب‌های عامل‌محور است. با انتقال مشاهده‌پذیری به یک افزونه به‌جای قرار دادن آن در هسته (Core)، DeepSeek Harness اجازه می‌دهد یک پشته تله‌متری ماژولار ایجاد شود. تیم‌های مختلف اکنون می‌توانند افزونه‌های تخصصی خود را برای حسابداری توکن‌ها، ردیابی (Tracing) یا داشبوردهای سفارشی پیاده کنند بدون اینکه موتور اجرای اصلی را سنگین و حجیم کنند. این جداسازی تضمین می‌کند که چارچوب اصلی فقط بر اجرای عامل، اجرای ابزار و مدیریت جلسات تمرکز کند، در حالی که افزونه‌ها رویدادهای چرخه حیات را رصد می‌کنند.
برای یک توسعه‌دهنده کاربردی، این موضوع چرخه «آزمون و خطا» در مهندسی پرامپت (Prompt Engineering) — هنر سؤال درست پرسیدن برای گرفتن بهترین جواب — و تعریف ابزارها را کاهش می‌دهد. به‌جای حدس زدن دلیل کندی عامل، شما یک عدد concrete دارید؛ مثلاً یک کوئری دیتابیس خاص که ۱۴ ثانیه زمان برده است و مستقیماً شما را به منبع اصطکاک می‌برد.
تست و توسعه
برای تضمین پایداری، افزونه یک گردش‌کار مستقل برای ساخت و تست دارد. توسعه‌دهندگان می‌توانند دستورات pnpm run build برای ساخت، pnpm run typecheck برای بررسی تایپ‌ها، pnpm run test برای اجرای تست‌ها و pnpm run prepublishOnly را اجرا کنند. این استقلال تضمین می‌کند که اعتبارسنجی افزونه به عملکردهای غیرمرتبط Harness وابسته نباشد.
گام‌های بعدی
با در دسترس قرار گرفتن این معیارهای بنیادی، گام منطقی بعدی توسعه ویژگی‌های پیشرفته‌تر مشاهده‌پذیری است. این موارد شامل موارد زیر است:
- ایجاد داشبوردهای عملکرد و تحلیل تأخیر (Latency) ابزارها.
- تحلیل شکست‌های عامل و مقایسه جلسات مختلف.
- شناسایی رگرسیون (Regression Detection) و یکپارچه‌سازی تله‌متری سفارشی.
- ردیابی توزیع‌شده (Distributed Tracing) برای سیستم‌های چند-عاملی (Multi-agent).
توسعه‌دهندگان می‌توانند مخزن dsh-plugin-agent-insights را بررسی کنند تا پیاده‌سازی این لایه‌های تله‌متری پیشرفته را آغاز کنند. تمرکز فعلی همچنان بر جمع‌آوری اطلاعات مفید در حالی است که افزونه به‌طور کامل خارج از مسیر اجرای عامل باقی بماند.
گام بعدی شما
- بررسی مخزن
dsh-plugin-agent-insightsبرای پیاده‌سازی لایه‌های تله‌متری پیشرفته. - تحلیل تأخیر ابزارها در محیط عملیاتی برای شناسایی گلوگاه‌های دیتابیس یا API.
- طراحی داشبوردهای بصری بر اساس داده‌های خروجی
getMetricsبرای نظارت بر سلامت عامل‌ها.
اما داستان سخت‌افزاری این تحول حتی شگفت‌انگیزتر است — به تحلیل ما درباره‌ی تراشه‌های Blackwell مراجعه کنید.
گفتگو