Evaluation

Agent Framework innehåller ett inbyggt utvärderingsramverk som gör att du kan mäta agentkvalitet, säkerhet och korrekthet. Du kan köra snabba lokala kontroller under utvecklingen, använda Microsoft Foundrys molnbaserade utvärderare för utvärdering i produktionsklass eller kombinera båda i en enda utvärderingskörning.

Utvärderingsramverket är utformat kring några viktiga principer:

• Provider-agnostic – Grundläggande utvärderingstyper och orkestreringsfunktioner fungerar med valfri utvärderingsprovider.
• Noll friktion – Gå från "Jag har en agent" till "Jag har eval-resultat" med minimal kod.
• Progressivt avslöjande – Enkla scenarier kräver nästan noll kod. Avancerade scenarier bygger på samma primitiver.

Grundläggande begrepp

Utvärderingsramverket bygger på tre typer:

Type	Avsikt
EvalItem	Ett enskilt objekt att utvärdera – omsluter den fullständiga konversationen och härleder frågor/svar via en delad strategi.
Utvärderaren	En provider som poängsätter objekt – lokala kontroller, Microsoft Foundry eller någon anpassad implementering.
EvalResults	Aggregerade resultat från en utvärderingskörning – antal pass/fail, information per objekt och valfria portallänkar.

I .NET bygger utvärderingsramverket på Microsoft. Extensions.AI.Evaluation. Utvärderare implementerar IAgentEvaluator gränssnittet och orkestrering tillhandahålls via tilläggsmetoder på AIAgent och Run.

Kärntyperna finns i namnområdet Microsoft.Agents.AI:

using Microsoft.Agents.AI;

I Python är utvärderingsramverket en del av kärnpaketet agent_framework. Utvärderare implementerar Evaluator protokollet och orkestrering tillhandahålls via evaluate_agent() och evaluate_workflow() funktioner.

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

Lokala utvärderare

LocalEvaluator kör kontroller lokalt utan API-anrop – perfekt för utveckling av inre loopar, CI-röktester och snabb iteration. Den accepterar valfritt antal kontrollfunktioner och tillämpar var och en på varje objekt.

Inbyggda kontroller

Agent Framework levereras med inbyggda kontroller för vanliga scenarier:

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

Anpassade funktionsutvärderingar

Använd FunctionEvaluator.Create() för att omsluta alla funktioner som en utvärderarkontroll. Flera överbelastningar är tillgängliga beroende på vilken data du behöver.

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

Inbyggda kontroller

Agent Framework levereras med inbyggda kontroller för vanliga scenarier:

Kontrollera	Vad det gör
keyword_check(*keywords)	Svaret måste innehålla alla angivna nyckelord
tool_called_check(*tool_names)	Agenten måste ha anropat de angivna verktygen
tool_calls_present	Alla expected_tool_calls namn visas i konversationen (osorterade, extrafunktioner OK)
tool_call_args_match	Förväntade verktygsanrop matchar namn och argument (delmängdsmatchning på 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
)

Anpassade funktionsutvärderingar

Använd dekoratören @evaluator för att omsluta alla funktioner som en utvärderarkontroll. Funktionens parameternamn avgör vilka data den tar emot från 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)

Parameternamn som stöds: query, response, expected_output, expected_tool_calls, conversation, , tools. context

Returtyper: bool, float (≥ 0,5 = pass), dict med score eller passed nyckel eller CheckResult. Asynkrona funktioner hanteras automatiskt.

Microsoft Foundry-utvärderare

FoundryEvalsansluter till Microsoft Foundrys utvärderingstjänst för molnbaserad LLM-as-judge-utvärdering. Resultaten visas i Foundry-portalen med instrumentpaneler och jämförelsevyer.

Information om projektkonfiguration, spårningsutvärdering, utvärdering av kriterier och körbara tjänstspecifika exempel finns i Microsoft Foundry-utvärdering.

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

Som standardinställning kör FoundryEvalsutvärderare för relevans, konsekvens och uppgiftsefterlevnad. När objekt innehåller verktygsdefinitioner läggs verktygsanropsprecision automatiskt till.

Tillgängliga utvärderare

FoundryEvals innehåller konstanter för alla inbyggda utvärderarnamn:

Kategori	Utvärderarna
Agentbeteende	intent_resolution, task_adherence, , task_completiontask_navigation_efficiency
Verktygsanvändning	tool_call_accuracy, tool_selection, tool_input_accuracy, , , tool_output_utilizationtool_call_success
Kvalitet	coherence, fluency, relevance, groundedness, , , response_completenesssimilarity
Safety	violence, sexual, , self_harmhate_unfairness

Anmärkning

FoundryEvalskräver ett Microsoft Foundry-projekt med en AI-modelldistribution. Parametern model anger vilken modell som ska användas som LLM-domare.

Utvärdera en agent

Det enklaste utvärderingsscenariot kör en agent mot testfrågor och poängsätter svaren. Ange flera olika frågor för statistiskt meningsfull utvärdering.

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 är en tilläggsmetod på AIAgent. Den kör agenten en gång per fråga, konverterar varje interaktion till en EvalItemoch skickar batchen till utvärderaren.

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 kör agenten en gång per fråga, konverterar varje interaktion till en EvalItemoch skickar batchen till utvärderaren. Den returnerar en EvalResults per utvärderareleverantör.

Mäta konsekvens med upprepningar

Kör varje fråga flera gånger för att identifiera icke-deterministiskt beteende:

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)

Utvärdera med förväntade utdata

Ge förväntade svar baserat på referensdata för att utvärdera korrekthet. Förväntade utdata parkopplas positionmässigt med frågor:

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

Du kan också ange förväntade verktygsanrop:

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

Du kan också ange förväntade verktygsanrop:

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

Utvärdera befintliga svar

När du redan har agentsvar från loggar eller tidigare körningar utvärderar du dem direkt utan att köra agenten igen:

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

Strategier för konversationsdelning

Konversationer med flera turer måste delas upp i fråge- och svarshalvor för utvärdering. Hur du delar avgör vad du utvärderar.

Strategi	Beteende	Passar bäst för
Senaste sväng (standard)	Dela vid senaste användarmeddelandet. Allt upp till det är frågekontext; allt efter är svaret.	Svarskvalitet vid en viss punkt
Fullständig	Det första användarmeddelandet är frågan. hela resten är svaret.	Slutförd uppgift och övergripande bana
Per tur	Varje användare→assistant interaktion poängsätts oberoende med kumulativ kontext.	Detaljerad analys

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

Du kan också implementera en anpassad splitter genom att implementera 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)

Du kan också ange en anpassad splitter – vilken som helst anropbar funktion som tar en konversation och returnerar (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,
)

Utvärdera arbetsflöden

Utvärdera arbetsflöden för flera agenter med uppdelning per agent. Ramverket extraherar varje underagents interaktioner och utvärderar dem individuellt, tillsammans med arbetsflödets övergripande utdata.

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

Du kan också skicka queries direkt och ramverket kör arbetsflödet åt dig:

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

Blanda flera utvärderare

Kör lokala kontroller och molnbaserade utvärderare tillsammans i en enda utvärdering. Varje utvärderare skapar sin egen 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-utvärderare

.NET-utvärderingsramverket integreras direkt med Microsoft. Extensions.AI.Evaluation utvärderare. Kvalitets- och säkerhetsutvärderingar från MEAI fungerar utan adapter:

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

Tips/Råd

När du använder MEAI-utvärderare anger du en chatConfiguration parameter med en chattklient som konfigurerats för utvärderingsmodellen. Den här klienten används av LLM-as-judge-utvärderarna för att bedöma svar.

Anmärkning

Go-stöd för den här funktionen kommer snart. Se Agent Framework Go-lagringsplatsen för den senaste statusen.

Nästa steg

Agentkunskaper

Relaterat innehåll

• Observerbarhet
• Agentsäkerhet
• översikt över Microsoft Foundry-utvärdering