Evaluation

Az Agent Framework beépített kiértékelési keretrendszert tartalmaz, amely lehetővé teszi az ügynökök minőségének, biztonságának és helyességének mérését. A fejlesztés során gyors helyi ellenőrzéseket futtathat, Microsoft Foundry felhőalapú kiértékelőit használhatja éles szintű értékeléshez, vagy kombinálhatja mindkettőt egyetlen kiértékelési futtatásban.

Az értékelési keretrendszer néhány fő alapelv köré van kialakítva:

• Provider-agnostic – Az alapvető kiértékelési típusok és a vezénylési függvények bármely kiértékelési szolgáltatóval együttműködnek.
• Nulla súrlódás – Az "Van ügynököm" állapottól az "Értékelési eredményekhez", minimális kóddal.
• Progresszív közzététel – Az egyszerű forgatókönyvekhez közel nulla kód szükséges. A speciális forgatókönyvek ugyanazokra a primitívekre épülnek.

Alapfogalmak

A kiértékelési keretrendszer három típusra épül:

Típus	Alkalmazás célja
EvalItem	Egyetlen kiértékelendő elem – a teljes beszélgetés körbefuttatása és a lekérdezés/válasz kinyerése osztott stratégián keresztül.
Értékelő	Olyan szolgáltató, amely elemeket – helyi ellenőrzéseket, Microsoft Foundryt vagy bármilyen egyéni megvalósítást – értékel.
EvalResults	Kiértékelési futtatás összesített eredményei – sikeres/sikertelen számlálások, elemenként részletezés és választható portállinkek.

A .NET rendszerben az értékelési keretrendszer a Microsoft.Extensions.AI.Evaluation-ra épül. Az értékelők implementálják az interfésztIAgentEvaluator, és a vezénylés a bővítménymetóciókon keresztül történik.AIAgentRun

Az alapvető típusok a Microsoft.Agents.AI névtérben élnek:

using Microsoft.Agents.AI;

A Python az értékelési keretrendszer az alapvető agent_framework csomag része. Az értékelők implementálják a protokollt Evaluator, és a vezénylést a evaluate_agent() és evaluate_workflow() függvények biztosítják.

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

Helyi kiértékelők

LocalEvaluator Helyileg futtatja az ellenőrzéseket API-hívások nélkül – ideális belső ciklusú fejlesztéshez, CI füsttesztekhez és gyors iterációhoz. Tetszőleges számú ellenőrző függvényt fogad el, és mindegyiket alkalmazza minden elemre.

Beépített ellenőrzések

Az Agent Framework beépített ellenőrzéseket tartalmaz a gyakori esetekre.

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
);

Egyéni függvényértékelők

Bármely FunctionEvaluator.Create() függvényt kiértékelő ellenőrzésként körbefuttathat. A szükséges adatoktól függően több túlterhelés is rendelkezésre áll:

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))
);

Beépített ellenőrzések

Az Agent Framework beépített ellenőrzéseket tartalmaz a gyakori esetekre.

Ellenőriz	Mire szolgál?
keyword_check(*keywords)	A válasznak tartalmaznia kell az összes megadott kulcsszót
tool_called_check(*tool_names)	Az ügynöknek meg kell hívnia a megadott eszközöket
tool_calls_present	Minden expected_tool_calls név megjelenik a beszélgetésben (rendezetlen, extrák OK)
tool_call_args_match	A várt eszközhívások egyeznek a névvel és az argumentumokkal (az args részhalmaz-egyezése)

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
)

Egyéni függvényértékelők

@evaluator dekorátor használatával bármely függvényt becsomagolhat értékelő ellenőrzésként. A függvény paraméternevei határozzák meg, hogy milyen adatokat kap a EvalItemkövetkezőtől:

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)

Támogatott paraméternevek: query, response, expected_output, expected_tool_calls, conversation, toolscontext.

Visszatérési típusok: bool, float (≥ 0,5 = átment), dictscore vagy passed kulccsal, vagy CheckResult. Az aszinkron függvények kezelése automatikusan megtörténik.

Microsoft Foundry értékelési szakemberei

FoundryEvalscsatlakozik Microsoft Foundry felhőalapú LLM-mint bírói kiértékelési szolgáltatásához. Az eredmények irányítópultokkal és összehasonlító nézetekkel tekinthetők meg az Foundry portálon.

A projekt beállításával, a nyomkövetési értékeléssel, a rubrica-kiértékelőkkel és a futtatható szolgáltatásspecifikus mintákkal kapcsolatban lásd Microsoft Foundry-kiértékelőt.

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],
)

Alapértelmezés szerint a FoundryEvals, a koherencia és a feladatbetartás kiértékelői futnak. Ha az elemek eszközdefiníciókat tartalmaznak, automatikusan hozzáadja az eszközhívás pontosságát.

Elérhető kiértékelők

FoundryEvals konstansokat biztosít az összes beépített kiértékelőnévhez:

Kategória	Értékelők
Ügynök viselkedése	intent_resolution, task_adherence, task_completiontask_navigation_efficiency
Eszközhasználat	tool_call_accuracy, tool_selection, tool_input_accuracy, tool_output_utilization, , tool_call_success
Minőségű	coherence, fluency, relevance, groundednessresponse_completenesssimilarity
Safety	violence, sexual, self_harmhate_unfairness

Megjegyzés:

FoundryEvalsegy Microsoft Foundry-projektet igényel AI-modell üzembe helyezésével. A model paraméter megadja, hogy melyik modellt használja LLM-bíróként.

Ügynök kiértékelése

A legegyszerűbb kiértékelési forgatókönyv egy ügynököt futtat teszt-lekérdezések alapján, és pontszámot ad a válaszoknak. Több különböző lekérdezést biztosít a statisztikailag értelmezhető kiértékeléshez.

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 egy kiterjesztési metódus a AIAgent Lekérdezésenként egyszer futtatja az ügynököt, átalakítja az egyes interakciókat egy EvalItem-vá, majd átadja a köteget az értékelőhöz.

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 Lekérdezésenként egyszer futtatja le az ügynököt, az egyes interakciókat átalakítja egyé EvalItem, majd a köteget átadja a kiértékelőnek. Kiértékelő szolgáltatónként egy EvalResults értéket ad vissza.

Ismétlődések konzisztenciájának mérése

Futtassa az egyes lekérdezéseket többször a nem determinisztikus viselkedés észleléséhez:

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)

Kiértékelés a várt kimenetekkel

Adja meg a helyesség értékelésére várt alapigaz válaszokat. A várt kimenetek pozícióban vannak párosítva a lekérdezésekkel:

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

Megadhatja a várt eszközhívásokat is:

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,
)

Megadhatja a várt eszközhívásokat is:

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

Meglévő válaszok kiértékelése

Ha már rendelkezik ügynökválaszokkal a naplókból vagy az előző futtatásokból, értékelje ki őket közvetlenül az ügynök újrafuttatása nélkül:

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,
)

Beszélgetések felosztási stratégiái

A többfordulós beszélgetéseket lekérdezésekre és válaszfelesekre kell felosztani a kiértékeléshez. A felosztás határozza meg , hogy mit értékelünk.

Stratégia	Magatartás	A következőkre alkalmas
Utolsó turn (alapértelmezett)	Felosztás az utolsó felhasználói üzenetnél. Minden, ami rajta múlik, lekérdezési környezet; minden után a válasz.	Válaszminőség egy adott ponton
teljes	Az első felhasználói üzenet a lekérdezés; a teljes fennmaradó rész a válasz.	Tevékenység befejezése és teljes pályája
Fordulatonként	Minden felhasználó→asszisztens válasz önállóan, kumulatív kontextussal kerül pontozásra.	Részletes elemzés

// 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);

Egyéni felosztót is készíthet az IConversationSplitter megvalósításával.

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)

Egyéni osztót is megadhat – bármilyen hívhatót, amely beszélgetést tart, és visszaadja a következőt (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,
)

Munkafolyamatok kiértékelése

Többügynök-munkafolyamatok kiértékelése ügynökenkénti bontással. A keretrendszer kinyeri az egyes alügynökök interakcióit, és egyenként értékeli ki őket a munkafolyamat általános kimenetével együtt.

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}")

Közvetlenül is átadhatja queries-t, és a keretrendszer futtatja majd a munkafolyamatot ön helyett:

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

Több értékelő kombinálása

Helyi ellenőrzéseket és felhőalapú kiértékelőket futtathat együtt egyetlen értékelésben. Minden kiértékelő saját 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-kiértékelők

A .NET kiértékelési keretrendszer közvetlenül integrálódik a Microsoft.Extensions.AI.Evaluation kiértékelőkkel. A MEAI minőség- és biztonsági kiértékelői adapter nélkül dolgoznak:

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));

Jótanács

Amikor MEAI-kiértékelőket használ, adjon meg egy chatConfiguration paramétert egy, a kiértékelési modellhez konfigurált chatklienssel. Ezt az ügyfelet használják az LLM-et bíraként értékelők, hogy pontozzák a válaszokat.

Megjegyzés:

A funkció Go-támogatása hamarosan érkezik. A legújabb állapotot az Agent Framework Go-adattárában tekinthet meg.

Következő lépések

Ügynöki készségek

Kapcsolódó tartalom

• Megfigyelhetőség
• Ügynökbiztonság
• Microsoft Foundry kiértékelése – áttekintés