Utvärdera distribuerade agent- och modellinteraktioner

Utvärdera lagrade svar eller OpenTelemetry-spårningar från distribuerade agenter och modeller utan att spela upp de ursprungliga begärandena igen.

Förutsättningar

• Slutför kraven för molnutvärderingen och klientkonfigurationen.
• ID:n för lagrade svar för svarsutvärdering eller en Application Insights-resurs som är ansluten till ditt Foundry-projekt för spårutvärdering.
• OpenTelemetry-intervall som uppfyller kraven för spårningsdata när du utvärderar spårningar.

I exemplen används SDK-klienten som konfigurerats i Konfigurera SDK-klienten.

Utvärdera interaktioner efter svars-ID

Hämta och utvärdera Foundry-agentsvar med svars-ID:t med hjälp av azure_ai_responses datakällans typ. Använd det här scenariot för att utvärdera specifika agentinteraktioner när de inträffar.

Ett svars-ID är en unik identifierare som returneras varje gång en Foundry-agent genererar ett svar. Du kan samla in svars-ID:n från agentinteraktioner med hjälp av svars-API :et eller från programmets spårningsloggar. Ange ID:na direkt i filinnehållet.

Samla in svar-ID:n

Varje anrop till svars-API:et returnerar ett svarsobjekt med ett unikt id fält. Samla in dessa ID:er från ditt programs interaktioner eller generera dem direkt:

# Generate response IDs by calling a model through the Responses API
response = openai_client.responses.create(
    model=model_deployment_name,
    input="What is machine learning?",
)
print(response.id)  # Example: resp_abc123

Du kan också samla in svars-ID:er från agentinteraktioner i programmets spårningsloggar eller övervakningspipeline. Varje svars-ID identifierar unikt ett lagrat svar som utvärderingstjänsten kan hämta.

Skapa utvärdering och kör

from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

data_source_config = {"type": "azure_ai_source", "scenario": "responses"}

testing_criteria = [
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="coherence",
        evaluator_name="builtin.coherence",
        initialization_parameters={"model": model_deployment_name},
    ),
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="violence",
        evaluator_name="builtin.violence",
    ),
]

eval_object = openai_client.evals.create(
    name="Agent Response Evaluation",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,
)

data_source = {
    "type": "azure_ai_responses",
    "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
            "type": "file_content",
            "content": [
                {"item": {"resp_id": "resp_abc123"}},
                {"item": {"resp_id": "resp_def456"}},
            ]
        },
    },
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-response-evaluation",
    data_source=data_source,
)

const evalObject = await openaiClient.evals.create({
    name: "Agent Response Evaluation",
    data_source_config: { type: "azure_ai_source", scenario: "responses" },
    testing_criteria: [
        {
            type: "azure_ai_evaluator",
            name: "coherence",
            evaluator_name: "builtin.coherence",
            initialization_parameters: { model: modelDeploymentName },
        },
        {
            type: "azure_ai_evaluator",
            name: "violence",
            evaluator_name: "builtin.violence",
        },
    ],
});

const responseEvalRun = await openaiClient.evals.runs.create(evalObject.id, {
    name: "agent-response-evaluation",
    data_source: {
        type: "azure_ai_responses",
        item_generation_params: {
            type: "response_retrieval",
            data_mapping: { response_id: "{{item.resp_id}}" },
            source: {
                type: "file_content",
                content: [
                    { item: { resp_id: "resp_abc123" } },
                    { item: { resp_id: "resp_def456" } },
                ],
            },
        },
    },
});
console.log(`Evaluation run created: ${responseEvalRun.id}`);

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/v1/evals/${EVAL_ID}/runs" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "agent-response-evaluation",
    "data_source": {
      "type": "azure_ai_responses",
      "item_generation_params": {
        "type": "response_retrieval",
        "data_mapping": {"response_id": "{{item.resp_id}}"},
        "source": {
          "type": "file_content",
          "content": [
            {"item": {"resp_id": "resp_abc123"}},
            {"item": {"resp_id": "resp_def456"}}
          ]
        }
      }
    }
  }'

Ett fullständigt körbart exempel finns i sample_agent_response_evaluation.py på GitHub. Om du vill kontrollera om processen är slutförd och tolka resultaten, se Hämta resultat för molnutvärdering.

Utvärdera spårningar (förhandsversion)

Utvärdera agentinteraktioner som Application Insights redan har samlat in. Använd datakällans azure_ai_traces typ. Det här scenariot är användbart för utvärdering efter distributionen av verklig produktionstrafik. Du väljer spår från ditt övervakningsflöde och kör utvärderare på dem utan att köra om några förfrågningar.

Spårningsutvärdering stöder två lägen:

• Med spårnings-ID :n – Utvärdera specifika agentinteraktioner genom att ange deras operation_Id värden från Application Insights.
• Efter agentfilter – Identifiera och utvärdera de senaste spårningarna automatiskt för en viss agent, utan att manuellt samla in spårnings-ID:t.

Intelligent insamling

Spårningsutvärdering stöder intelligent sampling, som väljer en representativ delmängd av spårningar för utvärdering i stället för att utvärdera varje samlad spårning. Aktivera växlingsreglaget Intelligent sampling i Foundry-portalen när du konfigurerar en körning för spårningsutvärdering. Intelligent sampling minskar utvärderingskostnaden samtidigt som spårningsdiversitet bevaras – vilket säkerställer att gränsfall, felsökvägar och olika konversationsmönster ingår i den utvärderade uppsättningen.

Så här fungerar intelligent sampling

Urvalsalgoritmen använder en MinHash-baserad farthest-first-metod för diversitet som utförs i flera steg:

1. Exakt deduplicering – Tar bort duplicerade spårningar från poolen.
2. Hårda filter – Tar bort brutna sessioner, trunkerade spårningar och felformade verktygsanrop som inte är lämpliga för utvärdering.
3. Sammansättning – Kombinerar spårningsnivåsignaler till en enhetlig representation.
4. MinHash farthest-first-urval – Beräknar lokalitetskänsliga hashvärden (MinHash-signaturer) för användartext för att uppskatta likheten mellan spår, och väljer sedan iterativt det minst liknande spåret ur den återstående mängden. Varje efterföljande val maximerar avståndet från alla tidigare valda spårningar.

Denna metod ger betydligt högre lexikal mångfald och bredare vokabulärtäckning jämfört med slumpmässig sampling, vilket innebär att den utvärderade uppsättningen bättre representerar hela utbudet av agentinteraktioner - inklusive sällsynta, hårda och nya fall som slumpmässig sampling tenderar att missa.

Intelligent sampling är särskilt effektivt för:

• Utvärdering och riktmärken – Maximerar täckningen av indatafördelningen så att utvärderingspoängen återspeglar verklig mångfald.
• Generering av kriterier – Ger mer fokuserade och användbara kriterier genom att exponera olika konversationsmönster.
• Finjustering av datamängdskuration – Väljer spårningar som hjälper modeller att lära sig mer effektivt.

Algoritmen körs helt på lokal beräkning utan extra API-anrop, så det medför inte extra kostnader för modellinferens utöver själva utvärderingen.

Exempel på intelligent sampling

# Eval group for trace-based evaluations
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

print("Creating trace-based evaluation group")
eval_object = client.evals.create(
    name="Trace Evaluation (Agent Smart Filter)",
    data_source_config=data_source_config,  # type: ignore
    testing_criteria=testing_criteria,
)
print(f"Evaluation created (id: {eval_object.id})")

# Compute time window in unix seconds
# Pad end_time by +600s (10 min) to avoid ingestion-delay edge exclusion
now_unix = int(time.time())
end_time = now_unix + 600
start_time = now_unix - (args.lookback_hours * 3600)

# Build trace_source based on mode
trace_source: dict = {
    "type": "agent_filter",
    "start_time": start_time,
    "end_time": end_time,
    "max_traces": args.max_traces,
    "filter_strategy": "smart_filtering"
}

# Add agent name/version or agent id
trace_source["agent_name"] = agent_name
trace_source["agent_version"] = agent_version
## trace_source["agent_id"] = args.agent_id

data_source = {
    "type": "azure_ai_trace_data_source_preview",
    "trace_source": trace_source,
}

eval_run = client.evals.runs.create(
    eval_id=eval_object.id,
    name="trace-evaluation-agent-smart-filter-run",
    data_source=data_source,  # type: ignore
)

Krav för spårningsdata

Spårningsutvärdering kräver att din agent genererar intervall som följer OpenTelemetry-semantiska konventioner för generativ AI. Mer specifikt läser utvärderingstjänsten intervall från Application Insights och extraherar konversationsdata från deras attribut.

Följande span-attribut används:

För Python-agenter som skapats med Azure AI Agent Server SDK lägger du till [tracing] extra för att aktivera automatisk emission av span.

pip install "azure-ai-agentserver-core[tracing]"

Krav för spårningsutvärdering

Förutom de allmänna kraven kräver spårningsutvärdering:

• En Application Insights-resurs som är ansluten till ditt Foundry-projekt. Se också Ställ in spårning i Microsoft Foundry.
• Projektets hanterade identitet måste ha rollen Log Analytics Reader på både Application Insights-resursen och dess länkade Log Analytics arbetsyta. Om tabellerna som lagrar dina spårningar är skyddade (deras skyddsnivå är inställd på Skyddad) tilldelar du även rollen Privileged Monitoring Data Reader i samma omfång så att tjänsten kan läsa de skyddade spårningstabellerna.
• paketet azure-monitor-query Python (behövs bara om du samlar in spårnings-ID manuellt).

pip install "azure-ai-projects>=2.2.0" azure-monitor-query

Ange följande miljövariabler:

• APPINSIGHTS_RESOURCE_ID – Application Insights-resurs-ID (till exempel /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
• AGENT_ID — Agentidentifieraren som genereras av spårningsintegreringen (gen_ai.agent.id attributet), som används för att filtrera spårningar. Format: agent-name:version.
• TRACE_LOOKBACK_HOURS — (Valfritt) Antal timmar att se tillbaka vid spårningsförfrågningar. Standardinställningen är 1.

Alternativ A: Utvärdera efter agentfilter

Den enklaste metoden är att låta tjänsten automatiskt identifiera och utvärdera de senaste spårningarna för en specifik agent. Du behöver inte samla in spårnings-ID manuellt.

import os

agent_id = os.environ["AGENT_ID"]  # e.g., "my-weather-agent:1"
trace_lookback_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = openai_client.evals.create(
    name="Agent Trace Evaluation (by agent)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run — the service queries App Insights for matching traces
data_source = {
    "type": "azure_ai_traces",
    "agent_id": agent_id,
    "max_traces": 50,           # Maximum number of traces to evaluate
    "lookback_hours": trace_lookback_hours,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    data_source=data_source,
)

print(f"Evaluation run started: {eval_run.id}")

Tjänsten filtrerar invoke_agent sträckor med gen_ai.agent.id attributet, analyserar upp till max_traces unika spårnings-ID:n och utvärderar alla sträckor från dessa spårningar.

Alternativ B: Utvärdera med spårnings-ID:n

Om du vill ha mer kontroll samlar du in specifika spårnings-ID:t från Application Insights och utvärderar dem. Den här metoden är användbar när du vill utvärdera en kuraterad uppsättning interaktioner, till exempel spårningar som flaggats av aviseringar eller samplats för kvalitetsgranskning.

Samla in spårnings-ID:t från Application Insights

Fråga Application Insights efter operation_Id värden från agentens spårningar. Varje operation_Id representerar en fullständig agentinteraktion.

import os
from datetime import datetime, timedelta, timezone
from azure.identity import DefaultAzureCredential
from azure.monitor.query import LogsQueryClient, LogsQueryStatus

appinsights_resource_id = os.environ["APPINSIGHTS_RESOURCE_ID"]
agent_id = os.environ["AGENT_ID"]
trace_query_hours = int(os.environ.get("TRACE_LOOKBACK_HOURS", "1"))

end_time = datetime.now(timezone.utc)
start_time = end_time - timedelta(hours=trace_query_hours)

query = f"""dependencies
| where timestamp between (datetime({start_time.isoformat()}) .. datetime({end_time.isoformat()}))
| extend agent_id = tostring(customDimensions["gen_ai.agent.id"])
| where agent_id == "{agent_id}"
| distinct operation_Id"""

credential = DefaultAzureCredential()
logs_client = LogsQueryClient(credential)
response = logs_client.query_resource(
    appinsights_resource_id,
    query=query,
    timespan=None,  # Time range is specified in the query itself
)

trace_ids = []
if response.status == LogsQueryStatus.SUCCESS:
    for table in response.tables:
        for row in table.rows:
            trace_ids.append(row[0])

print(f"Found {len(trace_ids)} trace IDs")

Skapa utvärdering och köra med spårnings-ID:t

# Create the evaluation
data_source_config = {
    "type": "azure_ai_source",
    "scenario": "traces",
}

eval_object = openai_client.evals.create(
    name="Agent Trace Evaluation (by trace IDs)",
    data_source_config=data_source_config,
    testing_criteria=testing_criteria,  # See "Set up evaluators" below
)

# Create a run using the collected trace IDs
data_source = {
    "type": "azure_ai_traces",
    "trace_ids": trace_ids,
    "lookback_hours": trace_query_hours,
}

eval_run = openai_client.evals.runs.create(
    eval_id=eval_object.id,
    name="agent-trace-eval-run",
    metadata={
        "agent_id": agent_id,
        "start_time": start_time.isoformat(),
        "end_time": end_time.isoformat(),
    },
    data_source=data_source,
)

print(f"Evaluation run started: {eval_run.id}")

Konfigurera utvärderare och datamappningar

När du utvärderar spårningar extraherar tjänsten automatiskt konversationsdata från attributen OpenTelemetry span. Använd dessa fältnamn direkt i data_mapping (utan de item. prefix eller sample. prefix som används i andra scenarier):

from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

testing_criteria = [
    # Quality evaluators — require query and response from trace data
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="intent_resolution",
        evaluator_name="builtin.intent_resolution",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        initialization_parameters={"model": model_deployment_name},
    ),
    # Tool evaluators — assess tool usage quality
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="tool_call_accuracy",
        evaluator_name="builtin.tool_call_accuracy",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_calls": "{{item.tool_calls}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
        initialization_parameters={"model": model_deployment_name},
    ),
    # Safety evaluators — work even with partial trace data
    TestingCriterionAzureAIEvaluator(
        type="azure_ai_evaluator",
        name="violence",
        evaluator_name="builtin.violence",
        data_mapping={
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
        initialization_parameters={"threshold": 4},
    ),
]

Nästa steg

• Om du vill kontrollera om processen är slutförd och tolka resultaten, se Hämta resultat för molnutvärdering.
• Ett fullständigt körbart exempel finns i sample_evaluations_builtin_with_traces.py på GitHub.