agentevals: حذف اسکریپت‌های واسط در تحلیل خطاهای عامل‌های هوش مصنوعی

اگر امروز برای نظارت بر عامل‌های هوش مصنوعی خود از داشبوردهای مجزا یا اسکریپت‌های دست‌نویس برای متصل کردن یک ردپای اجرا (Trace) به امتیاز آن استفاده می‌کنید، احتمالاً می‌دانید که پیدا کردن دلیل شکست یک تسک چقدر زمان‌بر است. نسخه ۰.۱۰.۰ ابزار agentevals که در ۱۲ اکتبر ۲۰۲۶ منتشر شد، این اصطکاک را با تبدیل امتیازهای ارزیابی به رویدادهای استاندارد OpenTelemetry (OTel) از بین می‌برد.

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

همان‌طور که در تحلیل قبلی ما درباره‌ی ارزیابی عامل‌های kagent اشاره کردیم، این به‌روزرسانی نیاز به پل‌های ارتباطی سفارشی را از بین می‌برد. طبق مستندات این ابزار، پیش از این توسعه‌دهندگان مجبور بودند تلمتری را به‌صورت دستی به فرمت‌های خاص تبدیل کنند تا بتوانند به یک امتیاز دست یابند. برای مثال، ارزیابی عامل‌های kagent تا سه هفته پیش نیازمند خواندن مستقیم جدول رویدادهای ADK و تبدیل دستی بخش‌های function_call و function_response به پیام‌های فرمت OpenAI بود. اکنون هر عاملی که اسپان‌های استاندارد GenAI OTel ارسال کند، بدون نیاز به سیم‌کشی اضافی امتیازدهی می‌شود.

معماری بومی OTel

تغییر بنیادین در نسخه ۰.۱۰.۰، حذف مسیر دریافت داده از طریق WebSocket است. agentevals دیگر به یک SDK اختصاصی، مدل نشست (Session) مالکانه یا استریم WebSocket برای دریافت داده‌ها نیاز ندارد. در عوض، این ابزار به‌عنوان یک گیرنده OTLP عمل می‌کند و داده‌ها را از طریق HTTP روی پورت ۴۳۱۸ یا gRPC روی پورت ۴۳۱۷ می‌پذیرد.

به نقل از تیم توسعه، این یعنی ابزار اکنون از هر تولیدکننده‌ای که از کنوانسیون‌های معنایی GenAI در OpenTelemetry پیروی کند، پشتیبانی می‌کند؛ از جمله:

• Google ADK
• LangChain
• Pydantic AI
• OpenAI Agents SDK
• Strands
• ابزارهای رسمی instrumentation در OpenTelemetry GenAI

در این میان، استفاده از چارچوب ADK گوگل پیش از این نشان داده بود که استانداردسازی تلمتری می‌تواند نرخ خطاهای عملیاتی را به‌طور چشم‌گیری کاهش دهد.

مدل گفتگوهای یکپارچه

فراتر از دریافت داده، نسخه ۰.۱۰.۰ یک مدل گفتگوی واحد را معرفی کرده است که در CLI، API، سرور MCP، رابط کاربری زنده و Worker اجرا مشترک است. این ساختار تضمین می‌کند که یک فراخوانی مدل که توسط یک چارچوب پیچیده شده است، تنها یک‌بار شمرده شود و دورهای استفاده از ابزار در سراسر ردپای اجرا به هم متصل شوند.

به دلیل این یکپارچه‌سازی، کاربران باید توجه کنند که مرزهای نوبت‌های گفتگو و تعداد توکن‌ها (Token) — تکه‌های کوچکی از متن که مثل برش‌های یک کیک طولانی توسط مدل مصرف می‌شوند — ممکن است در پردازش یک تلمتری یکسان با نسخه ۰.۹.x متفاوت باشد. این یک تغییر اساسی در نحوه تفسیر توالی تعاملات عامل توسط سیستم است.

بستن حلقه با خروجی امتیازها

مهم‌ترین تغییر، اضافه شدن پرچم --emit-otel است. وقتی این گزینه فعال باشد، agentevals هر امتیاز ارزیابی را به OTEL_EXPORTER_OTLP_ENDPOINT بازمی‌گرداند. این همان متغیر محیطی است که توسط تمام صادرکننده‌های OTel در یک استک استاندارد استفاده می‌شود. این امتیازها در قالب رویدادهای لاگ gen_ai.evaluation.result وارد سیستم می‌شوند.

از آنجا که این رویدادها همان Trace ID اجرای اصلی عامل را حمل می‌کنند، دقیقاً در کنار اسپان‌های مربوطه در هر بک‌اِند ردیابی قرار می‌گیرند. دیگر نیازی به جدول‌های Join یا کارهای صادراتی مجزا نیست تا بفهمید چرا یک نوبت خاص شکست خورده است. جریان به این سادگی است: عامل با ابزار OTel $ \rightarrow $ OTLP $ \rightarrow $ جمع‌کننده OpenTelemetry $ \rightarrow $ بک‌اِند ردیابی $ \rightarrow $ agentevals $ \rightarrow $ gen_ai.evaluation.result $ \rightarrow $ جمع‌کننده.

پیاده‌سازی فنی و آزمایش

در نمایش اخیر توسط یکی از مهندسان Solo.io، این چرخه با استفاده از یک جمع‌کننده OTel حداقلی اثبات شد. در این تست از یک کانتینر otel/opentelemetry-collector-contrib با یک صادرکننده لاگ استفاده شد. این تنظیمات شامل دو ردپای ضبط‌شده از عامل و یک مجموعه ارزیابی مرجع (Golden Set) از نمونه‌های agentevals (تحت لایسنس Apache-2.0) بود.

تست روی یک عامل Helm متمرکز بود که از او خواسته شده بود لیست نسخه‌ها (releases) را در یک فضای نام kagent استخراج کند. ارزیابی بر این محور بود که آیا عامل واقعاً تابع helm_list_releases را فراخوانی کرده است یا خیر:

• مورد موفق (PASS): یک ردپا با موفقیت ابزار را فراخوانی کرد و منجر به امتیاز ۱ (PASSED) با زمان اجرای ۷ میلی‌ثانیه برای هر فراخوانی شد.
• مورد شکست (FAIL): یک ردپا در فراخوانی ابزار شکست خورد و امتیاز ۰ (FAILED) با زمان ۱۶ میلی‌ثانیه برای هر فراخوانی گرفت. لاگ به‌طور مشخص به «عدم تطابق مسیر» (trajectory mismatch) اشاره کرد، زیرا فراخوانی مورد انتظار helm_list_releases({}) در ردپا وجود نداشت.

متادیتای دقیق رویدادها

رویدادهای OTel حاصل، شامل متادیتای حیاتی برای یکپارچگی بدون نقص با بک‌اِندها بودند:

• gen_ai.evaluation.name: معیار خاص در حال تست (مثلاً tool_trajectory_avg_score).
• gen_ai.evaluation.score.value: نتیجه عددی به‌صورت Double (مثلاً ۱.۰ یا ۰.۰).
• gen_ai.evaluation.score.label: برچسب متنی مانند pass یا fail (یا not_evaluated).
• gen_ai.conversation.id: شناسه منحصربه‌فرد جلسه (مثلاً ctx-7ed9780f-3688-4fc0-b10b-2e4df2f83cf0).
• agentevals.eval.case.id و agentevals.eval_set.id: شناسه‌های مورد تست (مثلاً helm_list_releases) و مجموعه تست (مثلاً helm_eval_set).
• agentevals.evaluator.type: نوع ارزیاب استفاده شده (مثلاً deterministic).
• Trace ID: کلید پیونددهنده امتیاز به تلمتری (مثلاً 3e289017fe03ffd7c4145316d2eb3d0d).

تغییرات ساختاری و محدودیت‌ها

این نسخه یک بازنویسی کلی است و تغییرات سازنده‌شکن (Breaking Changes) دارد. مدل مشترک گفتگو باعث می‌شود مرزهای نوبت و تعداد توکن‌ها با نسخه ۰.۹.x متفاوت باشد. همچنین، ارزیاب openai_eval پیش از بسته شدن API ارزیابی OpenAI در ۳۱ اکتبر ۲۰۲۶، به‌طور کامل حذف شده است.

یکپارچگی با kagent در حال حاضر «تجربی» (Experimental) است. در حالی که عامل‌های Go ADK در kagent تمام فراخوانی‌های مدل و ابزار را — شامل آرگومان‌ها، نتایج و توکن‌ها — از طریق OTel دریافت می‌کنند، سایر محیط‌ها شکاف‌هایی دارند:

• Claude Code harness (v1.0.0-alpha9): نام فراخوانی‌های ابزار و مصرف توکن‌های فراخوانی مدل را ثبت می‌کند، اما هنوز آرگومان‌های ابزار را ضبط نمی‌کند. در نتیجه، امتیازهای مسیر (trajectory scores) که آرگومان‌های خاص را چک می‌کنند، در این محیط شکست می‌خورند.
• Codex harness: در حال حاضر مورد آزمایش قرار نگرفته است.

چرخش در متدولوژی نظارت

این حرکت نشان‌دهنده چرخش به سمت «ارزیابی مبتنی بر نظارت» (Observability-driven evaluation) است. با تبدیل امتیاز به یک رویداد لاگ ساده، ارزیابی به‌جای اینکه یک مرحله پس‌پردازش مجزا باشد، بخشی از جریان استاندارد تلمتری می‌شود.

برای متخصصان، این یعنی «داشبورد ارزیابی» دیگر یک مقصد نیست، بلکه امتیاز صرفاً یکی از ویژگی‌های (Attribute) یک ردپای اجراست. این رویکرد بدهی فنی مربوط به نگهداری خط لوله‌های ارزیابی سفارشی را کاهش می‌دهد و به تیم‌ها اجازه می‌دهد از زیرساخت‌های موجود مانند Grafana یا Honeycomb برای ردیابی کیفیت هوش مصنوعی استفاده کنند. در کنار این بهبودهای نظارتی، امنیت داده‌ها نیز حیاتی است؛ به‌ویژه زمانی که سیاست «ممنوعیت پیش‌فرض» برای جلوگیری از فرار داده‌ها توسط عامل‌ها به کار گرفته می‌شود.

اگر عامل‌ها را در محیط عملیاتی اجرا می‌کنید، ارزش فوری این تغییر در توانایی ایجاد گیت‌های CI بر اساس رویدادهای OTel است. توجه داشته باشید که دستور agentevals run به‌درستی به‌عنوان یک گیت CI عمل کرده و در صورت شکست، کد خروجی غیرصفر برمی‌گرداند. این بدان معناست که اسکریپت‌هایی که از set -e استفاده می‌کنند، متوقف خواهند شد مگر اینکه دستور در || true پیچیده شود یا کد خروجی به‌طور عمدی بررسی شود.

ملاحظات استقرار در محیط عملیاتی

در حالی که در دمو از یک ساختار ساده «گیرنده به صادرکننده-دیباگ» استفاده شد، یک توپولوژی Collector در محیط عملیاتی نیازمند دستورالعمل‌های قوی‌تری است. طبق مستندات خط لوله‌های OpenTelemetry در agentevals، یک استقرار عملیاتی باید شامل موارد زیر باشد:

• یک جمع‌کننده (Collector) با دو شاخه.
• حذف محتوا (Content stripping) در شاخه‌ای که به بک‌اِند می‌رود برای کاهش هزینه‌ها و فضای ذخیره‌سازی.
• حفظ کامل محتوا در شاخه‌ای که به agentevals می‌رسد.
• یک کانکتور که رویدادهای gen_ai.evaluation.result را به یک متریک هیستوگرام امتیاز برای تحلیل روند بلندمدت تبدیل کند.

این معماری تضمین می‌کند که داده‌های با fidelity بالا برای ارزیابی را دریافت کنید بدون اینکه بک‌اِند ردیابی اصلی خود را بیش از حد حجیم کنید.

بازتولید چرخه اجرا

برای تأیید این ادعاها، مخزن themsquared/agentevals-otel-roundtrip یک اسکریپت ارکستراسیون کامل ارائه می‌دهد. اسکریپت run.sh پنج اقدام مشخص را انجام می‌دهد:
۱. اجرای یک جمع‌کننده OTel روی localhost:14318 (با فاصله ۱۰۰۰۰ واحد از پیش‌فرض برای جلوگیری از تداخل).
۲. ساخت محیط مجازی با agentevals-cli==0.10.0.
۳. اجرای ردپای موفق (samples/helm.json) با پرچم --emit-otel.
۴. اجرای ردپای شکست (samples/k8s.json) با همان فرآیند.
۵. استفاده از grep روی خروجی لاگ جمع‌کننده برای تأیید رویدادهای حاصل.

این فرآیند ثابت می‌کند که امتیاز و ردپای اجرا بدون هیچ کد واسطی، Trace ID یکسانی دارند. نتایج با کلون کردن مخزن و اجرای اسکریپت قابل بازتولید هستند. پروژه اصلی در agentevals-dev/agentevals و کنوانسیون‌های معنایی در opentelemetry.io تعریف شده‌اند.

گام بعدی شما

• اگر از LangChain یا Pydantic AI استفاده می‌کنید، نسخه ۰.۱۰.۰ را نصب کرده و خروجی‌های خود را به یک Collector محلی متصل کنید تا سرعت عیب‌یابی را بسنجید.
• پرچم --emit-otel را در خط لوله CI/CD خود جایگزین اسکریپت‌های بررسی دستی کنید تا گیت‌های کیفی خودکار داشته باشید.
• معماری دو‌شاخه‌ای جمع‌کننده را برای بهینه‌سازی هزینه‌های ذخیره‌سازی در Grafana یا Honeycomb پیاده‌سازی کنید.

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