التقييم

يتضمن إطار عمل العامل إطار تقييم مضمنا يتيح لك قياس جودة العامل وسلامته وصحته. يمكنك تشغيل عمليات فحص محلية سريعة أثناء التطوير، أو استخدام المقيمين المستندين إلى السحابة Microsoft Foundry للتقييم على مستوى الإنتاج، أو الجمع بين كليهما في عملية تقييم واحدة.

تم تصميم إطار التقييم حول بعض المبادئ الرئيسية:

• غير محددة الموفر — تعمل أنواع التقييم الأساسية ووظائف التنسيق مع أي موفر تقييم.
• عدم الاحتكاك — انتقل من "لدي وكيل" إلى "لدي نتائج تقييم" مع الحد الأدنى من التعليمات البرمجية.
• الكشف التدريجي - تتطلب السيناريوهات البسيطة تعليمة برمجية شبه صفرية. تعتمد السيناريوهات المتقدمة على نفس البدائيات.

المفاهيم الأساسية

يستند إطار التقييم إلى ثلاثة أنواع:

Type	الغرض
EvalItem	عنصر واحد لتقييمه — يلتف المحادثة الكاملة ويستمد الاستعلام/الاستجابة عبر استراتيجية الانقسام.
مقيم	موفر يسجل العناصر — عمليات التحقق المحلية أو Microsoft Foundry أو أي تنفيذ مخصص.
EvalResults	النتائج المجمعة من تشغيل التقييم — عدد مرات النجاح/الفشل وتفاصيل كل عنصر وارتباطات المدخل الاختيارية.

وفي .NET، يعتمد إطار التقييم على Microsoft. Extensions.AI.Evaluation. ينفذ المقيمون الواجهة IAgentEvaluator ، ويتم توفير التنسيق من خلال أساليب الامتداد في AIAgent و Run.

تعيش الأنواع الأساسية في Microsoft.Agents.AI مساحة الاسم:

using Microsoft.Agents.AI;

وفي Python، يشكل إطار التقييم جزءا من الحزمة الأساسيةagent_framework. ينفذ Evaluator المقيمون البروتوكول، ويتم توفير التنسيق من خلال evaluate_agent() الوظائف و evaluate_workflow() .

from agent_framework import (
    evaluate_agent,
    evaluate_workflow,
    EvalItem,
    EvalResults,
    LocalEvaluator,
)

المقيمون المحليون

LocalEvaluator تشغيل عمليات التحقق محليا دون استدعاءات واجهة برمجة التطبيقات — مثالية لتطوير الحلقة الداخلية واختبارات دخان CI والتكرار السريع. يقبل أي عدد من دوال الفحص ويطبق كل واحد على كل عنصر.

عمليات التحقق المضمنة

يتم شحن إطار عمل العامل مع عمليات التحقق المضمنة للسيناريوهات الشائعة:

using Microsoft.Agents.AI;

var local = new LocalEvaluator(
    EvalChecks.KeywordCheck("weather", "temperature"),  // Response must contain these keywords
    EvalChecks.ToolCalledCheck("get_weather")            // Agent must have called this tool
);

مقيمو الوظائف المخصصة

استخدم FunctionEvaluator.Create() لتضمين أي دالة كفحص مقيم. تتوفر حمولات زائدة متعددة استنادا إلى البيانات التي تحتاجها:

using Microsoft.Agents.AI;

var local = new LocalEvaluator(
    // Simple: check only the response text
    FunctionEvaluator.Create("is_concise",
        (string response) => response.Split(' ').Length < 500),

    // With expected output: compare against ground truth
    FunctionEvaluator.Create("mentions_city",
        (string response, string? expectedOutput) =>
            expectedOutput != null && response.Contains(expectedOutput, StringComparison.OrdinalIgnoreCase)),

    // Full context: access the complete EvalItem
    FunctionEvaluator.Create("used_search",
        (EvalItem item) => item.Conversation.Any(m =>
            m.Text?.Contains("search", StringComparison.OrdinalIgnoreCase) == true))
);

عمليات التحقق المضمنة

يتم شحن إطار عمل العامل مع عمليات التحقق المضمنة للسيناريوهات الشائعة:

تحقق	ماذا تفعل
keyword_check(*keywords)	يجب أن تحتوي الاستجابة على جميع الكلمات الأساسية المحددة
tool_called_check(*tool_names)	يجب أن يكون العامل قد استدعى الأدوات المحددة
tool_calls_present	تظهر جميع expected_tool_calls الأسماء في المحادثة (غير مرتبة، إضافية موافق)
tool_call_args_match	تطابق استدعاءات الأدوات المتوقعة على الاسم والوسيطات (تطابق المجموعة الفرعية على args)

from agent_framework import (
    LocalEvaluator,
    keyword_check,
    tool_called_check,
    tool_calls_present,
    tool_call_args_match,
)

local = LocalEvaluator(
    keyword_check("weather", "temperature"),  # Response must contain these keywords
    tool_called_check("get_weather"),          # Agent must have called this tool
    tool_calls_present,                        # All expected tool call names were made
    tool_call_args_match,                      # Expected tool calls match on name + args
)

مقيمو الوظائف المخصصة

@evaluator استخدم مصمم الديكور لتضمين أي دالة كفحص مقيم. تحدد أسماء معلمات الدالة البيانات التي تتلقاها من EvalItem:

from agent_framework import evaluator, LocalEvaluator

@evaluator
def is_concise(response: str) -> bool:
    """Check response is under 500 words."""
    return len(response.split()) < 500

@evaluator
def mentions_city(response: str, expected_output: str) -> bool:
    """Check response contains the expected city name."""
    return expected_output.lower() in response.lower()

@evaluator
def used_tools(conversation: list, tools: list) -> float:
    """Score based on tool usage. Returns 0.0–1.0 (>= 0.5 passes)."""
    tool_calls = [c for m in conversation for c in (m.contents or []) if c.type == "function_call"]
    return min(len(tool_calls) / max(len(tools), 1), 1.0)

local = LocalEvaluator(is_concise, mentions_city, used_tools)

أسماء المعلمات المدعومة: query، response، expected_output، expected_tool_calls، conversation، ، tools. context

أنواع إرجاع: bool، float (≥ 0.5 = تمرير)، dict مع score أو passed مفتاح، أو CheckResult. تتم معالجة الدوال غير المتزامنة تلقائيا.

مقيمو Microsoft Foundry

FoundryEvalsيتصل بخدمة تقييم Microsoft Foundry لتقييم LLM-as-judge المستند إلى السحابة. النتائج قابلة للعرض في مدخل Foundry مع لوحات المعلومات وطرق عرض المقارنة.

لإعداد المشروع وتقييم التتبع والمقيمين الأساسيين والعينات الخاصة بالخدمة القابلة للتشغيل، راجع Microsoft تقييم Foundry.

using Microsoft.Agents.AI.AzureAI;

var foundry = new FoundryEvals(chatConfiguration, FoundryEvals.Relevance, FoundryEvals.Coherence);

from agent_framework.foundry import FoundryEvals

evals = FoundryEvals(
    project_client=project_client,
    model="gpt-4o",
    evaluators=[FoundryEvals.RELEVANCE, FoundryEvals.COHERENCE],
)

بشكل افتراضي، FoundryEvals يقوم بتشغيل تقييم الصلةوالاتساق والالتزام بالمهمة . عندما تحتوي العناصر على تعريفات الأدوات، فإنها تضيف تلقائيا دقة استدعاء الأداة.

المقيمون المتاحون

FoundryEvals يوفر ثوابت لجميع أسماء المقيمين المضمنة:

Category	Evaluators
سلوك العامل	intent_resolution، ، task_adherence، task_completiontask_navigation_efficiency
استخدام الأداة	tool_call_accuracy، tool_selection، tool_input_accuracy، ، tool_output_utilizationtool_call_success
نوعيه	coherence، fluency، relevance، groundedness، ، response_completenesssimilarity
السلامة	violence، ، sexual، self_harmhate_unfairness

Note

FoundryEvalsيتطلب مشروع Microsoft Foundry مع نشر نموذج الذكاء الاصطناعي. model تحدد المعلمة النموذج الذي يجب استخدامه كقاضي LLM.

تقييم وكيل

يقوم سيناريو التقييم الأبسط بتشغيل عامل مقابل استعلامات الاختبار ويسجل الاستجابات. توفير استعلامات متنوعة متعددة للتقييم ذي المعنى الإحصائي.

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Foundry;

var foundry = new FoundryEvals(chatConfiguration, FoundryEvals.Relevance, FoundryEvals.Coherence);

AgentEvaluationResults results = await agent.EvaluateAsync(
    new[]
    {
        "What's the weather in Seattle?",
        "Plan a weekend trip to Portland",
        "What restaurants are near Pike Place?",
    },
    foundry);

results.AssertAllPassed();  // Throws if any item failed

EvaluateAsync هو أسلوب ملحق في AIAgent. يقوم بتشغيل العامل مرة واحدة لكل استعلام، ويحول كل تفاعل إلى EvalItem، ويمرر الدفعة إلى المقيم.

from agent_framework import evaluate_agent
from agent_framework.foundry import FoundryEvals

evals = FoundryEvals(
    project_client=project_client,
    model="gpt-4o",
    evaluators=[FoundryEvals.RELEVANCE, FoundryEvals.COHERENCE],
)

results = await evaluate_agent(
    agent=my_agent,
    queries=[
        "What's the weather in Seattle?",
        "Plan a weekend trip to Portland",
        "What restaurants are near Pike Place?",
    ],
    evaluators=evals,
)

for r in results:
    print(f"{r.provider}: {r.passed}/{r.total}")
    r.raise_for_status()  # Raises EvalNotPassedError if any item failed

evaluate_agent يشغل العامل مرة واحدة لكل استعلام، ويحول كل تفاعل إلى EvalItem، ويمرر الدفعة إلى المقيم. يقوم بإرجاع واحد EvalResults لكل موفر تقييم.

قياس التناسق مع التكرارات

قم بتشغيل كل استعلام عدة مرات للكشف عن السلوك غير المحدد:

AgentEvaluationResults results = await agent.EvaluateAsync(
    new[] { "What's the weather in Seattle?" },
    foundry,
    numRepetitions: 3);  // Each query runs 3 times independently
// Results contain 3 items (1 query × 3 repetitions)

results = await evaluate_agent(
    agent=my_agent,
    queries=["What's the weather in Seattle?"],
    evaluators=evals,
    num_repetitions=3,  # Each query runs 3 times independently
)
# Results contain 3 items (1 query × 3 repetitions)

تقييم مع المخرجات المتوقعة

تقديم إجابات متوقعة للحقيقة الأرضية لتقييم الصحة. يتم إقران المخرجات المتوقعة بشكل موضعي مع الاستعلامات:

AgentEvaluationResults results = await agent.EvaluateAsync(
    new[] { "What's 2+2?", "Capital of France?" },
    foundry,
    expectedOutput: new[] { "4", "Paris" });

يمكنك أيضا تحديد استدعاءات الأدوات المتوقعة:

AgentEvaluationResults results = await agent.EvaluateAsync(
    new[] { "What's the weather in NYC?" },
    new LocalEvaluator(EvalChecks.ToolCalledCheck("get_weather")),
    expectedToolCalls: new[]
    {
        new[] { new ExpectedToolCall("get_weather") },
    });

from agent_framework import evaluate_agent, ExpectedToolCall

results = await evaluate_agent(
    agent=my_agent,
    queries=["What's 2+2?", "Capital of France?"],
    expected_output=["4", "Paris"],
    evaluators=evals,
)

يمكنك أيضا تحديد استدعاءات الأدوات المتوقعة:

results = await evaluate_agent(
    agent=my_agent,
    queries=["What's the weather in NYC?"],
    expected_tool_calls=[ExpectedToolCall("get_weather", {"location": "NYC"})],
    evaluators=local,
)

تقييم الاستجابات الموجودة مسبقا

عندما يكون لديك بالفعل استجابات عامل من السجلات أو عمليات التشغيل السابقة، قم بتقييمها مباشرة دون إعادة تشغيل العامل:

var response = await agent.RunAsync(new[] { new ChatMessage(ChatRole.User, "What's the weather?") });

AgentEvaluationResults results = await agent.EvaluateAsync(
    new[] { response },
    new[] { "What's the weather?" },
    foundry);

from agent_framework import Message, evaluate_agent

response = await agent.run([Message("user", ["What's the weather?"])])

results = await evaluate_agent(
    agent=agent,
    responses=response,
    queries="What's the weather?",
    evaluators=evals,
)

استراتيجيات تقسيم المحادثة

يجب تقسيم المحادثات متعددة الأدوار إلى نصفي الاستعلام والاستجابة للتقييم. تحدد كيفية التقسيم ما تقوم بتقييمه.

الاستراتيجية	السلوك	الأفضل ل
آخر دور (افتراضي)	انقسام في رسالة المستخدم الأخيرة. كل شيء متروك له هو سياق الاستعلام؛ كل شيء بعد هو الاستجابة.	جودة الاستجابة في نقطة محددة
الكامل	رسالة المستخدم الأولى هي الاستعلام؛ الباقي بأكمله هو الاستجابة.	إكمال المهمة والمسار العام
كل دور	يتم تسجيل كل مستخدم→استبدال أساسي بشكل مستقل مع سياق تراكمي.	تحليل دقيق

// Full conversation as context
AgentEvaluationResults results = await agent.EvaluateAsync(
    new[] { "Plan a 3-day trip to Paris" },
    foundry,
    splitter: ConversationSplitters.Full);

// Per-turn: each exchange scored independently
var items = EvalItem.PerTurnItems(conversation);
var perTurnResults = await evaluator.EvaluateAsync(items);

يمكنك أيضا تنفيذ مقسم مخصص عن طريق تنفيذ IConversationSplitter:

public class SplitBeforeToolCall : IConversationSplitter
{
    public (IReadOnlyList<ChatMessage> QueryMessages, IReadOnlyList<ChatMessage> ResponseMessages) Split(
        IReadOnlyList<ChatMessage> conversation)
    {
        // Custom split logic
        for (int i = 0; i < conversation.Count; i++)
        {
            if (conversation[i].Text?.Contains("tool_call") == true)
                return (conversation.Take(i).ToList(), conversation.Skip(i).ToList());
        }
        return ConversationSplitters.LastTurn.Split(conversation);
    }
}

from agent_framework import evaluate_agent, ConversationSplit

# Full conversation as context
results = await evaluate_agent(
    agent=agent,
    queries=["Plan a 3-day trip to Paris"],
    evaluators=evals,
    conversation_split=ConversationSplit.FULL,
)

# Per-turn: each exchange scored independently
from agent_framework import EvalItem

items = EvalItem.per_turn_items(conversation)
# Pass items directly to an evaluator
per_turn_results = await evaluator.evaluate(items)

يمكنك أيضا توفير مقسم مخصص — أي قابل للاستدعاء يأخذ محادثة ويرجع (query_messages, response_messages):

def split_before_memory(conversation):
    """Split just before a memory-retrieval tool call."""
    for i, msg in enumerate(conversation):
        for c in msg.contents or []:
            if c.type == "function_call" and c.name == "retrieve_memory":
                return conversation[:i], conversation[i:]
    # Fallback to default
    return EvalItem._split_last_turn_static(conversation)

results = await evaluate_agent(
    agent=agent,
    queries=queries,
    evaluators=evals,
    conversation_split=split_before_memory,
)

تقييم مهام سير العمل

تقييم مهام سير العمل متعددة العوامل مع تصنيف تفصيلي لكل عامل. يستخرج إطار العمل تفاعلات كل وكيل فرعي ويقيمها بشكل فردي، جنبا إلى جنب مع الإخراج الإجمالي لسير العمل.

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.AzureAI;

Run run = await workflowRunner.RunAsync(workflow, "Plan a trip to Paris");

AgentEvaluationResults results = await run.EvaluateAsync(
    new FoundryEvals(chatConfiguration, FoundryEvals.Relevance));

Console.WriteLine($"Overall: {results.Passed}/{results.Total}");

// Per-agent breakdown
if (results.SubResults != null)
{
    foreach (var (name, sub) in results.SubResults)
    {
        Console.WriteLine($"  {name}: {sub.Passed}/{sub.Total}");
    }
}

results.AssertAllPassed();

from agent_framework import evaluate_workflow
from agent_framework.foundry import FoundryEvals

evals = FoundryEvals(project_client=project_client, model="gpt-4o")
result = await workflow.run("Plan a trip to Paris")

eval_results = await evaluate_workflow(
    workflow=workflow,
    workflow_result=result,
    evaluators=evals,
)

for r in eval_results:
    print(f"{r.provider}: {r.passed}/{r.total}")
    for name, sub in r.sub_results.items():
        print(f"  {name}: {sub.passed}/{sub.total}")

يمكنك أيضا التمرير queries مباشرة وسيشغل إطار العمل سير العمل نيابة عنك:

eval_results = await evaluate_workflow(
    workflow=workflow,
    queries=["Plan a trip to Paris", "Book a flight to London"],
    evaluators=evals,
)

خلط مقيمين متعددين

قم بتشغيل عمليات الفحص المحلية والمقيمين المستندين إلى السحابة معا في تقييم واحد. ينتج كل مقيم خاص EvalResultsبه.

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.AzureAI;

IReadOnlyList<AgentEvaluationResults> results = await agent.EvaluateAsync(
    new[] { "What's the weather in Seattle?" },
    evaluators: new IAgentEvaluator[]
    {
        new LocalEvaluator(
            EvalChecks.KeywordCheck("weather"),
            FunctionEvaluator.Create("is_helpful", (string r) => r.Split(' ').Length > 10)),
        new FoundryEvals(chatConfiguration, FoundryEvals.Relevance, FoundryEvals.Coherence),
    });

// results[0] = local evaluator results
// results[1] = Foundry evaluator results
foreach (var r in results)
{
    Console.WriteLine($"{r.Provider}: {r.Passed}/{r.Total}");
}

from agent_framework import evaluate_agent, evaluator, LocalEvaluator, keyword_check
from agent_framework.foundry import FoundryEvals

@evaluator
def is_helpful(response: str) -> bool:
    return len(response.split()) > 10

foundry = FoundryEvals(
    project_client=project_client,
    model="gpt-4o",
    evaluators=[FoundryEvals.RELEVANCE, FoundryEvals.COHERENCE],
)

results = await evaluate_agent(
    agent=agent,
    queries=["What's the weather in Seattle?"],
    evaluators=[
        LocalEvaluator(is_helpful, keyword_check("weather")),
        foundry,
    ],
)

# results[0] = local evaluator results
# results[1] = Foundry evaluator results
for r in results:
    print(f"{r.provider}: {r.passed}/{r.total}")

مقيمو MEAI

يتكامل إطار التقييم .NET مباشرة مع Microsoft. مقيمو Extensions.AI.Evaluation. يعمل مقيمو الجودة والسلامة من MEAI دون أي محول:

using Microsoft.Extensions.AI.Evaluation;
using Microsoft.Extensions.AI.Evaluation.Quality;
using Microsoft.Extensions.AI.Evaluation.Safety;

// Quality evaluators
AgentEvaluationResults results = await agent.EvaluateAsync(
    new[] { "What's the weather?" },
    new CompositeEvaluator(
        new RelevanceEvaluator(),
        new CoherenceEvaluator(),
        new GroundednessEvaluator()),
    chatConfiguration: new ChatConfiguration(evalClient));

// Safety evaluators
AgentEvaluationResults safetyResults = await agent.EvaluateAsync(
    new[] { "What's the weather?" },
    new ContentHarmEvaluator(),
    chatConfiguration: new ChatConfiguration(evalClient));

Tip

عند استخدام مقيمي MEAI، قم بتوفير معلمة chatConfiguration مع عميل دردشة تم تكوينه لنموذج التقييم. يستخدم مقيمو LLM-as-judge هذا العميل لتسجيل الردود.

Note

سيتوفر الدعم لهذه الميزة قريبا. راجع مستودع Agent Framework Go للحصول على أحدث حالة.

الخطوات التالية

مهارات العامل

المحتوى ذو الصلة

• إمكانية المراقبة
• أمان العامل
• نظرة عامة على تقييم Microsoft Foundry