مجله ایرانیکاسرورآموزش سرور، هاست، وردپرس و شبکه
آموزشی

چگونه بفهمیم AI Agent کدام ابزار را اشتباه انتخاب کرده است؟

فرض کنید یک AI Agent برای پشتیبانی مشتریان ساخته‌اید. کاربر درخواست می‌کند وضعیت سفارش خود را بررسی کند. Agent ابتدا یک ابزار برای جست‌وجوی سفارش اجرا می‌کند، سپس سراغ ابزار دیگری می‌رود و در…

چگونه بفهمیم AI Agent کدام ابزار را اشتباه انتخاب کرده است؟
خلاصه سریع این آموزش

فرض کنید یک AI Agent برای پشتیبانی مشتریان ساخته‌اید. کاربر درخواست می‌کند وضعیت سفارش خود را بررسی کند. Agent ابتدا یک ابزار برای جست‌وجوی سفارش اجرا می‌کند، سپس سراغ ابزار…

۲۵ دقیقه مطالعه ۰ دیدگاه ۲۶ آبان ۱۴۰۵ آخرین به‌روزرسانی

فرض کنید یک AI Agent برای پشتیبانی مشتریان ساخته‌اید. کاربر درخواست می‌کند وضعیت سفارش خود را بررسی کند. Agent ابتدا یک ابزار برای جست‌وجوی سفارش اجرا می‌کند، سپس سراغ ابزار دیگری می‌رود و در نهایت اعلام می‌کند سفارش ارسال شده است؛ اما وقتی وضعیت واقعی را بررسی می‌کنید، سفارش هنوز در مرحله آماده‌سازی قرار دارد.

حالا سؤال مهم این است: مشکل از کدام مرحله بوده است؟ آیا Agent ابزار اشتباهی را انتخاب کرده؟ آیا شناسه سفارش را نادرست به ابزار داده؟ آیا API اطلاعات قدیمی برگردانده یا مدل نتیجه صحیح ابزار را اشتباه تفسیر کرده است؟

برای پاسخ به این سؤال‌ها به AI Agent Observability یا مشاهده‌پذیری ایجنت هوش مصنوعی نیاز داریم. این مفهوم به مجموعه روش‌ها و ابزارهایی گفته می‌شود که کمک می‌کنند رفتار Agent را در طول اجرای درخواست مشاهده، تحلیل و ارزیابی کنیم.

در این مقاله، مفاهیم Trace، Span و Tool Call را به زبان ساده توضیح می‌دهیم، با OpenTelemetry و Langfuse آشنا می‌شویم و یاد می‌گیریم چگونه مراحل اجرای Agent را ردیابی کنیم. همچنین روش اندازه‌گیری Latency، مصرف توکن، هزینه، مدیریت داده‌های حساس و ارزیابی تصمیم‌های Agent را بررسی خواهیم کرد.

فهرست مطالب

AI Agent Observability چیست؟

AI Agent Observability به معنای توانایی بررسی رفتار داخلی یک سیستم عامل‌محور هوش مصنوعی از طریق داده‌هایی مانند Trace، Log، Metric و نتیجه ارزیابی است.

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

برای مثال، یک Agent فروش ممکن است مراحل زیر را انجام دهد:

  1. درخواست کاربر را دریافت کند.
  2. برای پیدا کردن مشتری از ابزار جست‌وجو استفاده کند.
  3. وضعیت سفارش را از دیتابیس بخواند.
  4. شرایط ارسال را از ابزار دیگری دریافت کند.
  5. اطلاعات را به مدل زبانی بدهد.
  6. پاسخ نهایی را تولید کند.

اگر فقط نتیجه نهایی را ذخیره کنیم، نمی‌دانیم هر مرحله دقیقاً چه اتفاقی افتاده است. Observability کمک می‌کند مسیر اجرای درخواست را از ابتدا تا انتها بررسی کنیم.

البته مشاهده‌پذیری به معنی دانستن قطعی تمام دلایل درونی تصمیم مدل نیست. Trace رفتارهای قابل مشاهده را ثبت می‌کند؛ برای اثبات درست یا غلط بودن تصمیم، معمولاً به داده مرجع، قواعد اعتبارسنجی یا Evaluation نیاز داریم.

تفاوت Logging، Monitoring و Observability چیست؟

این سه مفهوم به یکدیگر مرتبط‌اند، اما هدف یکسانی ندارند.

مفهوم وظیفه مثال در Agent
Logging ثبت رویدادهای اجرایی ثبت خطای Timeout ابزار سفارش
Monitoring بررسی شاخص‌ها و هشدارها افزایش نرخ خطای Tool Calls
Tracing نمایش مسیر اجرای یک درخواست مشاهده ترتیب فراخوانی مدل و ابزارها
Observability تحلیل وضعیت و علت مشکلات شناسایی مرحله‌ای که پاسخ نادرست ایجاد کرده
Evaluation سنجش کیفیت و درستی رفتار بررسی انتخاب ابزار مناسب برای یک وظیفه

برای مثال، Log ممکن است نشان دهد ابزار get_order_status با موفقیت اجرا شده است. اما Trace مشخص می‌کند این ابزار در چه مرحله‌ای، با چه پارامترهایی و پس از کدام تصمیم اجرا شده است.

Evaluation یک قدم جلوتر می‌رود و بررسی می‌کند آیا اصلاً انتخاب آن ابزار درست بوده است یا خیر.

Trace و Span در AI Agent چه هستند؟

دو مفهوم اصلی در Distributed Tracing، یعنی ردیابی توزیع‌شده، عبارت‌اند از Trace و Span.

Trace چیست؟

Trace نمایانگر مسیر کامل یک عملیات است. در یک Agent، می‌توان تمام مراحل پاسخ‌گویی به یک درخواست کاربر را زیر یک Trace ثبت کرد.

هر Trace دارای شناسه‌ای به نام Trace ID است که برای ارتباط‌دادن مراحل مختلف به یکدیگر استفاده می‌شود.

Span چیست؟

Span یک عملیات مشخص درون Trace است. هر Span معمولاً زمان شروع، زمان پایان، نام عملیات، وضعیت اجرا و اطلاعات مرتبط را ثبت می‌کند.

برای مثال، یک Trace می‌تواند شامل Spanهای زیر باشد:

Trace: support-agent-request
|
+-- Span: classify-intent
|
+-- Span: llm-tool-selection
|
+-- Span: execute_tool get_customer
|
+-- Span: execute_tool get_order_status
|
+-- Span: llm-final-response
|
+-- Span: validate-final-answer

هر Span می‌تواند زیرمجموعه Span دیگری باشد. با این ساختار درختی می‌توان ترتیب عملیات، زمان اجرای هر بخش و ارتباط میان آن‌ها را بررسی کرد.

نکته: تمام Agentها دقیقاً همین مراحل را ندارند. ساختار Trace باید با معماری واقعی سیستم و ابزارهای آن هماهنگ باشد.

مثال واقعی‌نما: پیدا کردن تصمیم اشتباه Agent

فرض کنید کاربری می‌پرسد: «سفارش شماره ۸۴۲ ارسال شده است؟»

Agent پس از دریافت درخواست، ابزار دریافت وضعیت سفارش را اجرا می‌کند.

مرحله اتفاق ثبت‌شده نتیجه
۱. دریافت درخواست کاربر وضعیت سفارش ۸۴۲ را می‌خواهد صحیح
۲. انتخاب Tool انتخاب get_order_status صحیح
۳. ورودی Tool order_id = ۸۲۴ اشتباه
۴. اجرای Tool API وضعیت سفارش ۸۲۴ را برمی‌گرداند اجرای موفق
۵. پاسخ نهایی سفارش ارسال شده است پاسخ نادرست برای سفارش ۸۴۲

در این سناریو، Tool از نظر فنی سالم است؛ زیرا دقیقاً سفارش درخواستی خود را جست‌وجو کرده است.

اما Agent هنگام ساخت پارامترهای Tool، شناسه اشتباهی ارسال کرده است.

اگر فقط خطاهای HTTP یا وضعیت موفقیت Tool را بررسی کنیم، این مشکل شناسایی نمی‌شود. برای تشخیص آن باید پارامتر استخراج‌شده را با داده مرجع درخواست مقایسه کنیم.

این مثال نشان می‌دهد که موفقیت فنی یک Tool Call الزاماً به معنی صحیح بودن تصمیم Agent نیست.

انواع خطاهای Tool Call در AI Agent

برای عیب‌یابی دقیق، بهتر است خطاهای مربوط به ابزارها را به چند گروه تقسیم کنیم.

۱. Tool Selection Error

مدل ابزار نامناسبی را انتخاب کرده است. برای مثال، کاربر وضعیت سفارش می‌خواهد اما Agent ابزار جست‌وجوی محصولات را اجرا می‌کند.

۲. Tool Argument Error

ابزار مناسب انتخاب شده ولی پارامترهای آن اشتباه‌اند؛ مانند ارسال شناسه سفارش، تاریخ یا شناسه مشتری نادرست.

۳. Tool Execution Error

خود ابزار هنگام اجرا خطا می‌دهد؛ مانند Timeout، خطای اتصال دیتابیس یا پاسخ HTTP ناموفق.

۴. Tool Result Interpretation Error

ابزار نتیجه صحیح برگردانده است، ولی مدل آن را نادرست تفسیر می‌کند. برای مثال، مقدار pending به‌اشتباه به معنی «ارسال‌شده» تعبیر می‌شود.

۵. Missing Tool Call

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

۶. Unnecessary Tool Call

Agent ابزار غیرضروری را اجرا کرده و باعث افزایش تأخیر، هزینه یا دسترسی اضافی به داده شده است.

۷. Unsafe Tool Call

Agent تلاش می‌کند عملیاتی خارج از مجوز خود انجام دهد؛ مانند ثبت سفارش، حذف اطلاعات یا ارسال داده محرمانه بدون تأیید لازم.

برای هر گروه باید روش تشخیص و معیار ارزیابی مستقل تعریف شود. یک داشبورد ساده خطاهای 500 نمی‌تواند تمام این موارد را تشخیص دهد.

OpenTelemetry چه کمکی به Observability Agent می‌کند؟

OpenTelemetry مجموعه‌ای از استانداردها و ابزارهای متن‌باز برای جمع‌آوری Trace، Metric و Log است.

مزیت OpenTelemetry این است که می‌توان داده‌های مشاهده‌پذیری را با قالبی نسبتاً استاندارد از بخش‌های مختلف برنامه جمع‌آوری و به Backend مناسب ارسال کرد.

برای سیستم‌های هوش مصنوعی نیز Semantic Conventionهای مخصوص Generative AI در حال توسعه هستند.

در این قراردادها، عملیات‌هایی مانند فراخوانی مدل و اجرای ابزار با Attributeهای مشخص ثبت می‌شوند.

Attribute کاربرد
gen_ai.operation.name نوع عملیات AI
gen_ai.tool.name نام ابزار اجراشده
gen_ai.tool.call.id شناسه فراخوانی ابزار
gen_ai.request.model مدل درخواست‌شده
gen_ai.usage.input_tokens تعداد توکن ورودی گزارش‌شده
gen_ai.usage.output_tokens تعداد توکن خروجی گزارش‌شده
error.type نوع خطای ثبت‌شده

وضعیت و نام برخی Attributeهای Generative AI در نسخه‌های مختلف Semantic Convention ممکن است تغییر کند. بنابراین برای استقرار عملیاتی، نسخه Instrumentation و قرارداد داده را ثابت نگه دارید.

مستندات رسمی:
OpenTelemetry Generative AI Semantic Conventions.

مقایسه ابزارهای Observability برای AI Agent

ابزارهای مختلفی برای مشاهده و ارزیابی اجرای Agent وجود دارند. انتخاب مناسب به زبان برنامه‌نویسی، Framework، نیازهای امنیتی و نوع استقرار وابسته است.

ابزار نقطه قوت مناسب برای
Langfuse Tracing، Usage، Cost، Scores و Evaluation تیم‌های توسعه LLM و Agent
LangSmith Trace و ارزیابی رفتار Agent پروژه‌های LangChain و LangGraph
OpenTelemetry استاندارد جمع‌آوری داده و اتصال ابزارها سیستم‌های چندسرویسی
Jaeger نمایش و تحلیل Trace توزیع‌شده عیب‌یابی عملیاتی
OpenAI Agents SDK Tracing ردیابی اجرای Agent و Toolها برنامه‌های مبتنی بر Agents SDK

OpenTelemetry در درجه اول یک استاندارد و مجموعه ابزار Instrumentation است، نه جایگزین کامل سیستم ارزیابی کیفیت Agent.

همچنین Jaeger بیشتر بر Distributed Tracing تمرکز دارد؛ برای تحلیل کیفیت پاسخ و تصمیم‌های مدل ممکن است به لایه Evaluation جداگانه نیاز داشته باشید.

در ادامه، Langfuse را برای نمونه عملی انتخاب می‌کنیم؛ زیرا از Traceهای مرتبط با LLM، ثبت Usage و ساختار چندمرحله‌ای پشتیبانی می‌کند.

منابع:
مستندات Langfuse،
LangSmith و
OpenAI Agents SDK Tracing.

پیش‌نیازهای آموزش عملی

برای ساخت نمونه آموزشی به Python، محیط مجازی و یک پروژه Langfuse نیاز داریم.

در این آموزش برای جلوگیری از هزینه API و وابستگی به مدل واقعی، رفتار Agent و Tool را شبیه‌سازی می‌کنیم.

پس از اطمینان از صحت Traceها، می‌توانید همین ساختار را به Agent واقعی و ابزارهای پروژه خود اضافه کنید.

پیش‌نیازها:

  • Python 3.11 یا نسخه سازگار با SDK نصب‌شده.
  • دسترسی به یک نمونه Langfuse Cloud یا Self-hosted.
  • کلیدهای پروژه Langfuse.
  • دسترسی شبکه HTTPS برای ارسال داده‌های Trace.
  • آشنایی مقدماتی با اجرای اسکریپت Python.

اگر داده‌های پروژه محرمانه هستند، قبل از استفاده از سرویس مدیریت‌شده باید محل پردازش، سیاست نگهداری و الزامات قراردادی آن را بررسی کنید.

مرحله اول: ایجاد پروژه Python

روی سیستم توسعه یا سرور Ubuntu، پوشه جدیدی ایجاد کنید.

mkdir -p ~/agent-observability
cd ~/agent-observability

python3 -m venv .venv
source .venv/bin/activate

python -m pip install --upgrade pip
python -m pip install langfuse

سپس نسخه نصب‌شده را بررسی کنید:

python -m pip show langfuse

نمونه این مقاله بر اساس الگوی API نسخه‌های جدید Langfuse با get_client() و start_as_current_observation() نوشته شده است.

برای استقرار واقعی، نسخه سازگار و بررسی‌شده کتابخانه را در فایل وابستگی پروژه ثابت کنید.

مرحله دوم: اتصال به Langfuse

در Langfuse یک پروژه ایجاد و اطلاعات احراز هویت آن را دریافت کنید. سپس متغیرهای محیطی لازم را تنظیم کنید.

export LANGFUSE_PUBLIC_KEY="YOUR_PUBLIC_KEY"
export LANGFUSE_SECRET_KEY="YOUR_SECRET_KEY"

export LANGFUSE_BASE_URL="https://cloud.langfuse.com"

export LANGFUSE_OBSERVE_DECORATOR_IO_CAPTURE_ENABLED="false"

آدرس بالا برای یکی از مناطق ارائه سرویس Langfuse Cloud است. اگر از نمونه Self-hosted یا منطقه دیگری استفاده می‌کنید، آدرس واقعی همان محیط را قرار دهید.

متغیر آخر، ضبط خودکار ورودی و خروجی در Observe Decorator را غیرفعال می‌کند؛ اما به‌تنهایی تضمین نمی‌کند تمام Instrumentationها، کتابخانه‌ها یا Spanهای دستی از ثبت داده حساس جلوگیری کنند.

برای محیط واقعی باید هر ابزار Instrumentation را جداگانه بررسی کنید.

مرحله سوم: ثبت اولین Trace برای Agent

حالا یک Agent آزمایشی تعریف می‌کنیم که وضعیت سفارش را بررسی می‌کند.

این مثال عمداً از یک دیکشنری ثابت به‌جای دیتابیس یا API واقعی استفاده می‌کند تا تفاوت خطای انتخاب پارامتر و خطای اجرای ابزار روشن باشد.

فایل agent_trace.py را ایجاد کنید:

from langfuse import get_client

langfuse = get_client()

ORDERS = {
    "842": "preparing",
    "824": "shipped",
}


def get_order_status(order_id):
    return ORDERS.get(order_id, "not_found")


def run_agent(requested_order_id, selected_order_id):
    with langfuse.start_as_current_observation(
        as_type="span",
        name="support-agent-run",
    ) as root:

        root.update(
            metadata={
                "workflow": "order-status",
                "environment": "demo",
            }
        )

        with langfuse.start_as_current_observation(
            as_type="span",
            name="tool-argument-validation",
        ) as validation:

            arguments_match = (
                requested_order_id == selected_order_id
            )

            validation.update(
                metadata={
                    "arguments_match": arguments_match,
                    "error_category": (
                        "none" if arguments_match
                        else "tool_argument_error"
                    ),
                }
            )

        with langfuse.start_as_current_observation(
            as_type="span",
            name="execute_tool get_order_status",
        ) as tool_span:

            status = get_order_status(
                selected_order_id
            )

            tool_span.update(
                metadata={
                    "tool_name": "get_order_status",
                    "tool_success": True,
                    "result_status": status,
                }
            )

        answer = f"Order status: {status}"

        root.update(
            metadata={
                "final_status": status,
                "validation_passed": arguments_match,
            }
        )

        return {
            "answer": answer,
            "arguments_match": arguments_match,
        }


if __name__ == "__main__":
    result = run_agent(
        requested_order_id="842",
        selected_order_id="824",
    )

    print(result)

    langfuse.flush()

این کد سه مرحله را ثبت می‌کند: اجرای کلی Agent، اعتبارسنجی پارامتر ابزار و اجرای Tool.

در سناریوی آزمایشی، شناسه سفارش موردنظر ۸۴۲ است، اما شناسه ۸۲۴ به ابزار داده می‌شود. نتیجه ابزار از نظر فنی صحیح است؛ ولی فیلد arguments_match مقدار False خواهد داشت.

شناسه‌های سفارش در این مثال داده‌های ساختگی هستند. در برنامه واقعی نباید اطلاعات شخصی یا شناسه حساس را بدون ضرورت در Telemetry ارسال کرد.

برای اجرای برنامه:

python agent_trace.py

در صورت معتبر بودن تنظیمات و ارتباط با Langfuse، می‌توانید Trace مربوط به اجرای Agent را در محیط مشاهده‌پذیری بررسی کنید.

خروجی مورد انتظار برنامه به‌صورت مفهومی:

{
  "answer": "Order status: shipped",
  "arguments_match": False
}

با وجود موفقیت Tool، اعتبارسنجی نشان می‌دهد پارامتر ارسالی با درخواست موردنظر مطابقت ندارد.

محدودیت مثال: این یک شبیه‌سازی قطعی است، نه Agent متصل به مدل زبانی واقعی. برای تشخیص خطای تصمیم‌گیری مدل، باید خروجی واقعی انتخاب ابزار نیز در اجرای واقعی ثبت و با مرجع مورداعتماد مقایسه شود.

مرجع:
Instrumentation در Langfuse.

برای هر Tool Call چه اطلاعاتی ثبت کنیم؟

یک Trace مفید باید به اندازه‌ای اطلاعات داشته باشد که بتوان علت خطا را تشخیص داد، اما نباید بدون دلیل محتوای حساس را ذخیره کند.

اطلاعات کاربردی برای هر Tool Call عبارت‌اند از:

  • نام ابزار اجراشده.
  • شناسه یکتای فراخوانی ابزار.
  • شماره مرحله در اجرای Agent.
  • نوع عملیات و نسخه Schema ابزار.
  • نتیجه اعتبارسنجی پارامترهای ورودی.
  • کد وضعیت اجرا یا گروه خطا.
  • زمان شروع و پایان عملیات.
  • تعداد Retryها.
  • نسخه Prompt یا سیاست انتخاب ابزار.
  • نتیجه ارزیابی خروجی ابزار.

در بسیاری از موارد، ذخیره وضعیت‌هایی مانند schema_valid=true، result_count=2 و http_status=200 برای عیب‌یابی اولیه کافی است و نیازی به ضبط متن کامل پاسخ نیست.

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

چگونه Latency هر مرحله را اندازه بگیریم؟

Latency یا تأخیر، مدت زمان اجرای یک عملیات است. در Agentهای چندمرحله‌ای، تأخیر کل ممکن است حاصل چندین فراخوانی مدل، ابزار، دیتابیس و شبکه باشد.

برای مثال، فرض کنید یک درخواست شامل مراحل زیر است:

مرحله زمان فرضی
انتخاب ابزار توسط مدل ۱٫۲ ثانیه
جست‌وجوی مشتری ۰٫۲ ثانیه
دریافت وضعیت سفارش ۰٫۸ ثانیه
تولید پاسخ نهایی ۱٫۵ ثانیه

اگر این مراحل کاملاً پشت‌سرهم اجرا شوند، مجموع مدت آن‌ها ۳٫۷ ثانیه خواهد بود؛ البته سربارهای دیگر مانند شبکه و اعتبارسنجی نیز ممکن است به تأخیر اضافه شوند.

اما در اجراهای موازی نباید زمان Spanهای فرزند را ساده با یکدیگر جمع کرد. زمان Trace اصلی ممکن است از مجموع زمان تمام Spanها کمتر باشد.

برای تحلیل عملکرد بهتر است شاخص‌های زیر بررسی شوند:

  • زمان کل اجرای Agent.
  • میانگین و P95 زمان اجرای هر Tool.
  • زمان انتظار برای پاسخ مدل.
  • زمان دریافت اولین توکن در Streaming.
  • تعداد و مدت Retryها.
  • میزان هم‌پوشانی عملیات موازی.

با این اطلاعات می‌توان فهمید کندی برنامه ناشی از مدل زبانی است یا ابزارهای جانبی.

چگونه مصرف توکن و هزینه Agent را ردیابی کنیم؟

در یک Agent، ممکن است برای یک درخواست کاربر چندین بار مدل زبانی فراخوانی شود.

برای مثال، مدل ابتدا تصمیم می‌گیرد چه ابزاری اجرا شود، سپس نتیجه ابزار را بررسی می‌کند و در نهایت پاسخ را تولید می‌کند.

اگر مصرف توکن هر مرحله جداگانه ثبت نشود، مشخص نخواهد بود کدام بخش هزینه بیشتری ایجاد کرده است.

برای هر فراخوانی مدل بهتر است اطلاعات زیر را نگهداری کنیم:

  • شناسه یا نام مدل.
  • تعداد توکن ورودی.
  • تعداد توکن خروجی.
  • توکن‌های Cached یا سایر انواع مصرف، در صورت گزارش ارائه‌دهنده.
  • تعرفه معتبر مدل در زمان درخواست.
  • هزینه محاسبه‌شده یا گزارش‌شده.
  • شناسه Trace و Span مربوط به فراخوانی.

برای یک مدل با تعرفه ورودی و خروجی مشخص، هزینه پایه به‌صورت زیر محاسبه می‌شود:

هزینه = (توکن ورودی ÷ واحد تعرفه × قیمت ورودی) + (توکن خروجی ÷ واحد تعرفه × قیمت خروجی)

واحد تعرفه معمولاً در صفحه قیمت‌گذاری ارائه‌دهنده مشخص می‌شود و ممکن است بر اساس یک میلیون توکن باشد.

هزینه نهایی می‌تواند شامل موارد دیگری مانند ابزارهای پولی، Cache، پردازش تصویر یا صوت و Retryها باشد؛ بنابراین این رابطه فقط برای محاسبه بخش متنی پایه کاربرد دارد.

ثبت Usage در Langfuse

در ساختار جدید Langfuse، می‌توان برای یک Generation جزئیات مصرف را ثبت کرد.

from langfuse import get_client

langfuse = get_client()

with langfuse.start_as_current_observation(
    as_type="generation",
    name="agent-llm-decision",
    model="your-model-id",
) as generation:

    # Example usage values from a fictional request.
    generation.update(
        usage_details={
            "input_tokens": 1200,
            "output_tokens": 350,
        },
        metadata={
            "operation": "tool-selection",
            "usage_source": "demo",
        },
    )

langfuse.flush()

مقادیر توکن این مثال ساختگی هستند. در برنامه واقعی باید آن‌ها را از Usage گزارش‌شده توسط API مدل بخوانید.

همچنین برای گزارش هزینه دقیق، تعرفه و نوع مصرف باید با مدل و زمان اجرای درخواست تطبیق داده شود. صرف ثبت تعداد توکن، محاسبه مالی دقیق را تضمین نمی‌کند.

Evaluation چیست و چگونه تصمیم اشتباه Agent را تشخیص می‌دهد؟

Tracing نشان می‌دهد Agent چه کاری انجام داده است؛ اما Evaluation بررسی می‌کند که آیا آن رفتار صحیح بوده یا خیر.

برای ارزیابی Agent می‌توان از مجموعه‌ای از وظایف آزمایشی استفاده کرد که رفتار مورد انتظار در آن‌ها مشخص است.

برای مثال، اگر کاربر وضعیت سفارش می‌خواهد، ممکن است Tool مورد انتظار get_order_status باشد.

ولی در درخواست دیگری، Agent باید ابتدا هویت کاربر را تأیید کند و سپس به ابزار اطلاعات سفارش دسترسی پیدا کند.

بنابراین Evaluation باید علاوه بر انتخاب ابزار، ترتیب عملیات، مجوز دسترسی و صحت پاسخ نهایی را نیز بررسی کند.

معیارهای مهم Agent Evaluation

معیار سؤال اصلی
Tool Selection Accuracy آیا ابزار مناسب انتخاب شده است؟
Argument Accuracy آیا پارامترهای ابزار صحیح‌اند؟
Tool Execution Success آیا ابزار بدون خطای فنی اجرا شده است؟
Trajectory Validity آیا ترتیب مراحل و ابزارها معتبر است؟
Answer Correctness آیا پاسخ نهایی صحیح است؟
Policy Compliance آیا محدودیت‌های امنیتی رعایت شده‌اند؟
Cost Efficiency آیا تعداد فراخوانی‌ها و هزینه منطقی بوده‌اند؟

هیچ‌یک از این شاخص‌ها به‌تنهایی کیفیت کامل Agent را نشان نمی‌دهند. برای مثال، انتخاب Tool صحیح می‌تواند به پاسخ نادرست منجر شود، یا Agent ممکن است با مسیر متفاوتی به پاسخ معتبر برسد.

نمونه عملی بررسی صحت انتخاب Tool

برای شروع، می‌توان یک تست ساده و قطعی ایجاد کرد که رفتار مشاهده‌شده را با نتیجه مورد انتظار مقایسه کند.

فایل evaluate_agent.py را با محتوای زیر بسازید:

TEST_CASES = [
    {
        "expected_tool": "get_order_status",
        "actual_tool": "get_order_status",
        "expected_order_id": "842",
        "actual_order_id": "842",
    },
    {
        "expected_tool": "get_order_status",
        "actual_tool": "search_products",
        "expected_order_id": "517",
        "actual_order_id": None,
    },
    {
        "expected_tool": "get_order_status",
        "actual_tool": "get_order_status",
        "expected_order_id": "619",
        "actual_order_id": "691",
    },
]


def evaluate(case):
    tool_correct = (
        case["expected_tool"] ==
        case["actual_tool"]
    )

    arguments_correct = (
        tool_correct
        and case["expected_order_id"] ==
        case["actual_order_id"]
    )

    return {
        "tool_correct": tool_correct,
        "arguments_correct": arguments_correct,
    }


results = [
    evaluate(case)
    for case in TEST_CASES
]

total = len(results)

tool_accuracy = sum(
    result["tool_correct"]
    for result in results
) / total

argument_accuracy = sum(
    result["arguments_correct"]
    for result in results
) / total

print(f"Tool accuracy: {tool_accuracy:.2%}")
print(f"Argument accuracy: {argument_accuracy:.2%}")

خروجی مورد انتظار:

Tool accuracy: 66.67%
Argument accuracy: 33.33%

در این مثال، از سه سناریوی آزمایشی فقط دو مورد ابزار درست انتخاب کرده‌اند و فقط یک مورد هم ابزار و هم پارامتر صحیح داشته است.

این اعداد نتیجه آزمایش واقعی یک مدل نیستند؛ صرفاً برای توضیح روش محاسبه استفاده شده‌اند.

برای Agentهای پیچیده‌تر، ممکن است چند مسیر متفاوت قابل قبول باشند. در این حالت Evaluation نباید فقط یک توالی ثابت از ابزارها را معتبر بداند، بلکه باید مجموعه مسیرهای مجاز و شرایط موفقیت را تعریف کند.

Trajectory Evaluation چیست؟

Trajectory به مسیر تصمیم‌ها و عملیات Agent در طول اجرای یک وظیفه گفته می‌شود.

برای مثال، یک Agent ممکن است برای پاسخ به یک سؤال ابتدا جست‌وجو کند، سپس سندی را بازیابی کند و در پایان پاسخ بدهد.

در Trajectory Evaluation بررسی می‌شود که آیا مراحل طی‌شده مناسب و مجاز بوده‌اند یا خیر.

این ارزیابی می‌تواند چند شکل داشته باشد:

  • مقایسه توالی ابزارها با مسیر مورد انتظار.
  • بررسی وجود مرحله‌های اجباری مانند احراز هویت.
  • بررسی نبود فراخوانی ابزارهای ممنوع.
  • کنترل تعداد تلاش‌های تکراری و حلقه‌های بی‌نتیجه.
  • سنجش کیفیت پاسخ نهایی مستقل از مسیر اجرا.

برای مثال، اگر Agent قبل از تأیید هویت کاربر اطلاعات حساب او را دریافت کند، حتی با تولید پاسخ صحیح نیز ممکن است از نظر امنیتی مردود باشد.

در این شرایط، Policy Compliance باید مستقل از Answer Correctness محاسبه شود.

آیا می‌توان از LLM-as-a-Judge برای ارزیابی Agent استفاده کرد؟

بله. در روش LLM-as-a-Judge از یک مدل زبانی برای ارزیابی رفتار یا خروجی مدل دیگر استفاده می‌شود.

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

اما این روش محدودیت دارد. مدل ارزیاب نیز ممکن است اشتباه کند، تحت تأثیر نحوه نگارش Prompt قرار بگیرد یا نسبت به بعضی پاسخ‌ها سوگیری داشته باشد.

بنابراین بهتر است برای مواردی مانند اعتبار Schema، رعایت مجوز دسترسی و تطبیق شناسه‌ها از تست‌های قطعی استفاده شود.

برای مواردی که نیاز به قضاوت معنایی دارند، می‌توان از LLM-as-a-Judge در کنار مجموعه داده برچسب‌خورده انسانی استفاده کرد.

همچنین داده‌های ارسال‌شده به مدل ارزیاب باید مطابق سیاست محرمانگی سازمان باشند؛ نباید برای ارزیابی، اطلاعاتی را به سرویس دیگری ارسال کنیم که انتقال آن مجاز نیست.

Redaction چیست و چرا برای Tracing اهمیت دارد؟

یکی از خطرات مهم Agent Observability، ثبت اطلاعات حساس در Trace است.

برای مثال، ورودی یک Tool ممکن است شامل توکن احراز هویت، شماره تماس، اطلاعات مالی یا بخشی از اطلاعات خصوصی مشتری باشد.

اگر همه ورودی‌ها و خروجی‌ها بدون فیلتر ذخیره شوند، سامانه Observability به محل دیگری برای نگهداری داده محرمانه تبدیل می‌شود.

Redaction به معنی حذف یا پوشاندن اطلاعات حساس پیش از ذخیره یا ارسال آن‌ها است.

مثلاً به‌جای ثبت مقدار واقعی API Key، می‌توان یک مقدار جایگزین ذخیره کرد:

{
  "tool_name": "customer_lookup",
  "authorization": "[REDACTED]",
  "user_email": "[REDACTED]",
  "http_status": 200,
  "result_count": 1
}

این JSON صرفاً یک مثال است و نشان می‌دهد چگونه می‌توان اطلاعات عملیاتی را نگه داشت، بدون اینکه اعتبارنامه یا نشانی ایمیل کاربر ذخیره شود.

روش‌های پیشنهادی محافظت از داده‌های Trace

  • ورودی و خروجی خام را به‌صورت پیش‌فرض ذخیره نکنید.
  • فقط Attributeهای موردنیاز برای عیب‌یابی را ثبت کنید.
  • از فهرست مجاز یا Allowlist برای Metadata استفاده کنید.
  • اطلاعات حساس را در خود برنامه و پیش از Export حذف کنید.
  • دسترسی به Traceها را بر اساس نقش محدود کنید.
  • مدت نگهداری و سیاست حذف داده مشخص باشد.
  • از ارسال داده محرمانه در Baggage یا هدرهای عمومی خودداری کنید.
  • نمونه‌های واقعی Trace را به‌صورت دوره‌ای از نظر نشت داده بررسی کنید.

OpenTelemetry Collector ابزارهایی مانند Redaction، Filter و Transform Processor دارد؛ اما حذف داده در Collector آخرین لایه دفاعی است و تضمین نمی‌کند داده حساس قبل از آن در حافظه یا سرویس دیگری ثبت نشده باشد.

مرجع:
Handling Sensitive Data در OpenTelemetry.

آیا خود Observability هزینه دارد؟

بله. ذخیره Trace، پردازش رویدادها، انتقال داده، نگهداری متریک‌ها و اجرای Evaluation می‌توانند هزینه ایجاد کنند.

برای مثال، اگر هر درخواست Agent شامل ۱۰ Span باشد و روزانه ۱۰۰ هزار درخواست ثبت شود، تعداد Spanهای روزانه می‌تواند به حدود یک میلیون برسد.

البته هزینه واقعی به اندازه داده هر Span، سیاست نمونه‌برداری، مدت نگهداری و زیرساخت ذخیره‌سازی بستگی دارد.

برای کنترل هزینه می‌توان از Sampling استفاده کرد؛ یعنی فقط بخشی از Traceها ثبت یا نگهداری شوند.

برای مثال:

  • نگهداری نمونه‌ای از درخواست‌های موفق و معمولی.
  • نگهداری Traceهای دارای خطای فنی در صورت امکان.
  • اولویت دادن به Traceهای دارای نتیجه Evaluation ناموفق.
  • ثبت Traceهای کندتر از آستانه موردنظر.
  • نگهداری خلاصه‌های آماری به‌جای ورودی کامل.

نکته: اگر تصمیم Sampling در ابتدای درخواست گرفته شود، هنوز مشخص نیست درخواست در آینده خطا خواهد داد یا نه. برای نگهداری هدفمند Traceهای خطادار، ممکن است به Tail Sampling یا بافرکردن کنترل‌شده رویدادها نیاز باشد.

برای داده‌های حساس باید حتی در حالت Sampling نیز سیاست Redaction رعایت شود.

Observability در سیستم‌های Multi-Agent

در معماری Multi-Agent، چند Agent می‌توانند مسئول وظایف متفاوتی باشند و نتیجه کار را به یکدیگر تحویل دهند.

برای مثال، یک Agent درخواست را تحلیل می‌کند، Agent دیگری اطلاعات مالی را بررسی می‌کند و Agent سوم پاسخ نهایی را تولید می‌کند.

در چنین معماری‌ای باید بتوان مسیر درخواست را میان Agentها و سرویس‌های مختلف دنبال کرد.

مفاهیم مهم شامل موارد زیر است:

  • شناسه Trace مشترک میان مراحل مرتبط.
  • شناسه Span مستقل برای هر عملیات.
  • ثبت Handoff میان Agentها.
  • نام و نسخه هر Agent.
  • ثبت Tool Calls هر Agent به‌صورت جداگانه.
  • اندازه‌گیری هزینه و تأخیر هر Agent.
  • ارزیابی پاسخ نهایی و مراحل میانی.

اگر Agentها روی سرویس‌های جدا اجرا شوند، باید Trace Context به‌شکل معتبر میان آن‌ها منتقل شود. انتشار Trace ID در همه Logها بدون کنترل دسترسی و طراحی صحیح، جایگزین ردیابی توزیع‌شده استاندارد نیست.

داشبورد مناسب Agent Observability چه شاخص‌هایی دارد؟

یک داشبورد مؤثر نباید فقط تعداد درخواست‌ها و مصرف توکن را نمایش دهد. برای تصمیم‌گیری عملیاتی، شاخص‌های کیفیت Agent نیز اهمیت دارند.

شاخص کاربرد
Agent Success Rate درصد وظایف موفق بر اساس معیار معتبر
Tool Selection Accuracy درستی انتخاب ابزار
Argument Error Rate درصد پارامترهای نامعتبر
Tool Failure Rate خطاهای فنی ابزارها
Latency P95 شناسایی درخواست‌های کند
Tokens per Task مصرف توکن برای هر وظیفه
Cost per Successful Task هزینه متوسط وظیفه موفق
Retry / Loop Rate تشخیص تکرارهای غیرضروری
Policy Violation Rate میزان نقض سیاست‌های عملیاتی و امنیتی

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

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

چگونه یک Agent خطادار را مرحله‌به‌مرحله عیب‌یابی کنیم؟

اگر Agent پاسخ اشتباه تولید کرده است، می‌توانید از روند زیر استفاده کنید:

  1. Trace مربوط به درخواست را پیدا کنید. از شناسه درخواست یا Trace ID استفاده کنید.
  2. مراحل اجرا را بررسی کنید. مشخص کنید چه مدل‌ها و ابزارهایی اجرا شده‌اند.
  3. اولین انحراف را شناسایی کنید. بررسی کنید کدام مرحله برای نخستین بار از رفتار مورد انتظار فاصله گرفته است.
  4. انتخاب Tool را اعتبارسنجی کنید. آیا ابزار مناسب وظیفه بوده است؟
  5. پارامترهای Tool را بررسی کنید. آیا ورودی با درخواست و داده مرجع مطابقت دارد؟
  6. خروجی ابزار را ارزیابی کنید. آیا ابزار نتیجه معتبر و تازه برگردانده است؟
  7. تفسیر مدل را بررسی کنید. آیا Agent داده ابزار را درست به پاسخ تبدیل کرده است؟
  8. علت خطا را ثبت کنید. خطا را در یک دسته مشخص قرار دهید.
  9. تست رگرسیون بسازید. سناریو را به مجموعه Evaluation اضافه کنید.
  10. اصلاح را دوباره ارزیابی کنید. مطمئن شوید تغییر جدید باعث خرابی سایر رفتارها نشده است.

این روش باعث می‌شود اصلاح Agent فقط بر اساس حدس یا تغییر تصادفی Prompt انجام نشود.

اشتباه‌های رایج در AI Agent Observability

۱. ثبت فقط پاسخ نهایی

اگر مراحل میانی ثبت نشوند، تشخیص اینکه کدام ابزار یا تصمیم باعث مشکل شده دشوار خواهد بود.

۲. یکی دانستن موفقیت API با صحت تصمیم

پاسخ HTTP 200 نشان‌دهنده اجرای فنی موفق است، نه لزوماً درستی انتخاب ابزار یا داده‌های ورودی.

۳. ذخیره تمام Promptها بدون Redaction

این کار ممکن است اطلاعات حساس را در سیستم Observability ذخیره کند و سطح خطر امنیتی را افزایش دهد.

۴. تمرکز صرف بر Latency و Token Cost

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

۵. استفاده از LLM-as-a-Judge بدون داده مرجع

ارزیابی مدل‌محور ممکن است اشتباه باشد. برای بخش‌های قابل بررسی با قواعد قطعی باید تست‌های مستقل تعریف شود.

۶. تغییر مداوم Prompt بدون تست رگرسیون

یک اصلاح می‌تواند مسئله خاصی را برطرف کند اما باعث ایجاد خطا در سناریوهای دیگر شود. مجموعه Evaluation باید قبل و بعد از تغییر اجرا شود.

۷. ثبت Trace بدون سیاست نگهداری

نگهداری نامحدود رویدادها می‌تواند هزینه ذخیره‌سازی و ریسک امنیتی را افزایش دهد.

چک‌لیست پیاده‌سازی Agent Observability در Production

  • تعریف Trace و Span برای عملیات اصلی Agent.
  • استفاده از Trace ID برای ارتباط مراحل.
  • ثبت نام و نسخه مدل‌ها و ابزارها.
  • اندازه‌گیری Latency و مصرف توکن.
  • ثبت وضعیت اجرای Toolها.
  • اعتبارسنجی پارامترها و خروجی ابزار.
  • تعریف دسته‌بندی خطاهای تصمیم‌گیری و اجرا.
  • حذف یا پوشاندن داده حساس پیش از Export.
  • کنترل دسترسی به داشبورد و Traceها.
  • تعریف Sampling و Retention.
  • ایجاد مجموعه آزمون برای Evaluation.
  • اندازه‌گیری نرخ موفقیت وظایف.
  • مقایسه کیفیت، هزینه و سرعت بین نسخه‌های Agent.
  • تنظیم هشدار برای افزایش خطا و هزینه.
  • تست رگرسیون پس از تغییر Prompt، مدل یا Tool.

جمع‌بندی؛ چگونه بفهمیم کدام Tool تصمیم اشتباه گرفته است؟

AI Agent Observability کمک می‌کند رفتار Agent را فراتر از پاسخ نهایی مشاهده کنیم. با ثبت Trace و Span می‌توان ترتیب فراخوانی مدل‌ها و ابزارها، زمان اجرا، خطاهای فنی و مصرف منابع را بررسی کرد.

اما برای تشخیص تصمیم اشتباه، صرف داشتن Trace کافی نیست. باید داده‌های ثبت‌شده با قواعد معتبر، خروجی مورد انتظار یا مجموعه Evaluation مقایسه شوند.

برای شروع، بهتر است مراحل انتخاب Tool، ساخت پارامتر، اجرای ابزار و تولید پاسخ را جداگانه ردیابی کنید. سپس معیارهای کیفیت، هزینه و امنیت را اضافه کنید.

هدف نهایی این است که وقتی Agent اشتباه می‌کند، بتوانید با شواهد مشخص بفهمید خطا از انتخاب ابزار بوده، از اجرای ابزار، از داده ورودی یا از تفسیر نتیجه توسط مدل. چنین رویکردی اصلاح Agent را دقیق‌تر، قابل‌آزمایش‌تر و کم‌هزینه‌تر می‌کند.

سؤالات متداول درباره AI Agent Observability

AI Agent Observability چیست؟

مجموعه روش‌ها و ابزارهایی برای بررسی مراحل اجرا، تصمیم‌ها، Tool Calls، مصرف منابع و کیفیت رفتار Agent هوش مصنوعی است.

تفاوت Trace و Span چیست؟

Trace مسیر کامل یک عملیات را نشان می‌دهد، درحالی‌که Span یک مرحله مشخص درون همان عملیات است.

آیا Trace می‌تواند تصمیم اشتباه Agent را تشخیص دهد؟

Trace داده‌های لازم برای بررسی رفتار را فراهم می‌کند؛ اما تشخیص قطعی خطا معمولاً به اعتبارسنجی، داده مرجع یا Evaluation نیاز دارد.

برای Agent Observability، Langfuse بهتر است یا OpenTelemetry؟

این دو الزاماً جایگزین یکدیگر نیستند. OpenTelemetry استاندارد جمع‌آوری داده است و Langfuse ابزارهای تخصصی مشاهده و ارزیابی برنامه‌های LLM را ارائه می‌دهد.

آیا ثبت Tool Calls خطر امنیتی دارد؟

بله. ورودی و خروجی ابزارها ممکن است شامل اطلاعات حساس باشند. باید از Data Minimization، Redaction، محدودیت دسترسی و سیاست نگهداری داده استفاده کرد.

چگونه هزینه هر Agent را اندازه بگیریم؟

با ثبت مصرف توکن و هزینه هر فراخوانی مدل و جمع‌کردن آن‌ها در سطح Trace، همراه با هزینه ابزارها و سایر اجزای پردازش.

Agent Evaluation چه تفاوتی با Monitoring دارد؟

Monitoring وضعیت و عملکرد سیستم را دنبال می‌کند، اما Evaluation درستی تصمیم‌ها و کیفیت انجام وظایف را بر اساس معیارهای مشخص می‌سنجد.

زیرساخت پایش و اجرای هوش مصنوعی

برای اجرای Agentهای هوش مصنوعی، زیرساخت قابل اطمینان انتخاب کنید

اگر قصد اجرای AI Agent، Langfuse، OpenTelemetry Collector یا سرویس‌های مانیتورینگ هوش مصنوعی را دارید، سرور مناسب می‌تواند به مدیریت منابع، نگهداری داده‌ها و پایداری پروژه کمک کند. برای انتخاب زیرساخت متناسب با نیازتان، خدمات ایرانیکاسرور را بررسی کنید.

اشتراک‌گذاری مقاله
گفت‌وگو درباره آموزش

دیدگاه‌ها (۰)

هنوز دیدگاهی ثبت نشده است.

دیدگاه یا سؤال خود را بنویسید

نشانی ایمیل شما منتشر نخواهد شد. بخش‌های موردنیاز علامت‌گذاری شده‌اند *