Avaliar interações de agente e modelo implantados

Avalie respostas armazenadas ou rastreamentos OpenTelemetry de agentes e modelos implantados sem reproduzir as solicitações originais.

Pré-requisitos

• Conclua os pré-requisitos de avaliação de nuvem e a configuração do cliente.
• IDs de respostas armazenadas para avaliação de respostas ou um recurso do Application Insights conectado ao seu projeto Foundry para avaliação de rastreamento.
• O OpenTelemetry abrange os requisitos de dados de rastreamento quando você avalia rastreamentos.

Os exemplos usam o cliente SDK configurado em Configurar o cliente SDK.

Avaliar interações por ID de resposta

Recupere e avalie as respostas de agentes do Foundry pelos IDs de respostas usando o tipo de fonte de dados azure_ai_responses. Use esse cenário para avaliar interações específicas do agente depois que elas ocorrerem.

Uma ID de resposta é um identificador único retornado sempre que um agente Foundry gera uma resposta. Você pode coletar IDs de resposta de interações com agentes usando a API de Respostas ou dos logs de rastreamento do seu aplicativo. Forneça as IDs diretamente no conteúdo do arquivo.

Coletar IDs de resposta

Cada chamada à API de Respostas retorna um objeto de resposta com um campo exclusivo id . Colete essas IDs das interações do aplicativo ou gere-as diretamente:

# 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

Você também pode coletar IDs de resposta de interações do agente nos logs de rastreamento do aplicativo ou no fluxo de monitoramento. Cada ID de resposta identifica exclusivamente uma resposta armazenada que o serviço de avaliação pode recuperar.

Criar avaliação e executar

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"}}
          ]
        }
      }
    }
  }'

Para obter um exemplo executável completo, consulte sample_agent_response_evaluation.py no GitHub. Para sondar a conclusão e interpretar os resultados, consulte Obter resultados de avaliação de nuvem.

Avaliar rastros (versão prévia)

Avalie as interações do agente que o Application Insights já capturou. Use o tipo de azure_ai_traces fonte de dados. Esse cenário é útil para a avaliação pós-implantação do tráfego de produção real. Você seleciona rastreamentos do seu pipeline de monitoramento e executa avaliadores neles sem reexecutar nenhuma solicitação.

A avaliação de rastreamento dá suporte a dois modos:

• Por IDs de rastreamento – avalie interações específicas do agente fornecendo seus operation_Id valores do Application Insights.
• Por filtro de agente – descubra e avalie automaticamente os rastreamentos recentes de um determinado agente, sem coletar manualmente as IDs de rastreamento.

Amostragem inteligente

A avaliação de traces oferece suporte à amostragem inteligente, que seleciona um subconjunto representativo de traces a serem avaliados, em vez de avaliar cada trace capturado. Ative a opção Amostragem inteligente no portal do Foundry ao configurar uma execução de avaliação de rastreio. A amostragem inteligente reduz o custo da avaliação, ao mesmo tempo que preserva a diversidade dos rastros — garantindo que casos de borda, caminhos de erro e diferentes padrões de conversa sejam incluídos no conjunto avaliado.

Como funciona a amostragem inteligente

O algoritmo de amostragem usa uma abordagem de diversidade do tipo MinHash “farthest-first”, executada em vários estágios:

1. Eliminação exata de duplicação – remove rastreamentos duplicados do pool.
2. Filtros rígidos – remove sessões interrompidas, rastreamentos truncados e chamadas de ferramentas malformadas que não são adequadas para avaliação.
3. Agregação – Combina sinais de nível de rastreamento em uma representação unificada.
4. Seleção mais distante do MinHash – calcula hashes sensíveis à localidade (assinaturas MinHash) do texto do usuário para estimar a similaridade entre rastreamentos e, em seguida, seleciona iterativamente o rastreamento mais diferente do pool restante. Cada nova seleção maximiza a distância em relação a todos os rastreamentos selecionados anteriormente.

Essa abordagem produz uma diversidade léxica significativamente maior e uma cobertura de vocabulário mais ampla em comparação com a amostragem aleatória, o que significa que o conjunto avaliado representa melhor toda a gama de interações do agente - incluindo casos raros, difíceis e novos que a amostragem aleatória tende a perder.

A amostragem inteligente é particularmente eficaz para:

• Avaliação e parâmetros de comparação – maximiza a cobertura da distribuição de entrada para que as pontuações de avaliação reflitam a diversidade do mundo real.
• Geração de rubricas - produz rubricas mais focadas e acionáveis, expondo diversos padrões de conversa.
• Configuração do conjunto de dados do Finetuning – seleciona rastreamentos que ajudam os modelos a aprender com mais eficiência.

O algoritmo é executado inteiramente na computação local sem chamadas de API extras, portanto, ele não incorre em custos extras de inferência de modelo além da própria avaliação.

Exemplo de amostragem inteligente

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

Requisitos de dados de rastreamento

A avaliação de rastreamento exige que seu agente emita intervalos que seguem as convenções semânticas OpenTelemetry para IA generativa. Especificamente, o serviço de avaliação lê invoke_agent trechos do Application Insights e extrai dados de conversação de seus atributos.

Os seguintes atributos de intervalo são usados:

Para os agentes Python criados com o SDK do Servidor de Agente de IA do Azure, adicione o [tracing] extra para habilitar a emissão automática de intervalos:

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

Pré-requisitos para avaliação de rastreamento

Além dos pré-requisitos gerais, a avaliação de traço requer:

• Um recurso do Application Insights conectado ao projeto do Foundry. Consulte Configurar o rastreamento no Microsoft Foundry.
• A identidade gerenciada do projeto deve possuir a função Log Analytics Reader tanto no recurso do Application Insights quanto no workspace do Log Analytics vinculado. Se as tabelas que armazenam seus rastreamentos estiverem protegidas (o nível de proteção deles está definido como Protegido), atribua também a função Leitor de Dados de Monitoramento Privilegiado nos mesmos escopos para que o serviço possa ler as tabelas de rastreamento protegidas.
• O pacote azure-monitor-query Python (necessário somente se você coletar IDs de rastreamento manualmente).

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

Defina estas variáveis de ambiente:

• APPINSIGHTS_RESOURCE_ID — A ID do recurso do Application Insights (por exemplo, /subscriptions/<subscription_id>/resourceGroups/<rg_name>/providers/Microsoft.Insights/components/<resource_name>).
• AGENT_ID — O identificador do agente emitido pela integração de rastreamento (gen_ai.agent.id atributo), usado para filtrar rastreamentos. Formato: agent-name:version.
• TRACE_LOOKBACK_HOURS — (Opcional) Número de horas para retroceder ao consultar rastros. Usa 1 como padrão.

Opção A: Avaliar por filtro de agente

A abordagem mais simples é permitir que o serviço descubra e avalie automaticamente rastreamentos recentes para um agente específico. Você não precisa coletar manualmente IDs de rastreamento.

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

O serviço filtra invoke_agent spans pelo atributo gen_ai.agent.id, amostra até max_traces IDs de rastreamento exclusivas e avalia todos os spans desses rastreios.

Opção B: Avaliar por IDs de rastreamento

Para obter mais controle, colete IDs de rastreamento específicas do Application Insights e avalie-as. Esse método é útil quando você deseja avaliar um conjunto selecionado de interações, como rastros sinalizados por alertas ou amostrados para revisão de qualidade.

Coletar IDs de rastreamento do Application Insights

Consulte o Application Insights em busca de valores operation_Id nos rastreamentos do agente. Cada operation_Id representa uma interação completa do agente:

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

Crie uma avaliação e rode com IDs de rastreamento

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

Configurar avaliadores e mapeamentos de dados

Quando você avalia rastreamentos, o serviço extrai automaticamente os dados da conversa dos atributos de span do OpenTelemetry. Use estes nomes de campo diretamente no data_mapping (sem os prefixos item. ou sample. usados em outros cenários):

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

Próximas Etapas 

• Para sondar a conclusão e interpretar os resultados, consulte Obter resultados de avaliação de nuvem.
• Para obter um exemplo executável completo, consulte sample_evaluations_builtin_with_traces.py no GitHub.