Avaliar as interações entre agentes e modelos implementadas

Avalie respostas armazenadas ou rastreios OpenTelemetry de agentes e modelos implementados sem repetir os pedidos originais.

Pré-requisitos

• Complete os pré-requisitos de avaliação cloud e a configuração do cliente.
• IDs de resposta armazenados para avaliação de respostas, ou um recurso Application Insights ligado ao seu projeto Foundry para avaliação de traços.
• Intervalos do OpenTelemetry que cumprem os requisitos dos dados de rastreamento ao avaliar rastreamentos.

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

Avaliar as interações pelo ID da resposta

Recuperar e avaliar as respostas dos agentes Foundry por IDs de resposta usando o azure_ai_responses tipo de fonte de dados. Use este cenário para avaliar interações específicas com agentes depois de ocorrerem.

Um ID de resposta é um identificador único devolvido cada vez que um agente da Foundry gera uma resposta. Pode recolher IDs de resposta das interações com agentes usando a API de Respostas ou a partir dos registos de rastreamento da sua aplicação. Forneça os IDs em linha como conteúdo do ficheiro.

Recolha identificadores de resposta

Cada chamada à API de Respostas devolve um objeto de resposta com um campo único id . Recolha estes IDs das interações da sua aplicação, ou gere-os 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

Também pode recolher IDs de resposta das interações com agentes nos registos de rastreio ou no fluxo de monitorização da sua aplicação. Cada ID de resposta identifica de forma única 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 um exemplo completo executável, veja sample_agent_response_evaluation.py em GitHub. Para verificar periodicamente a conclusão e interpretar os resultados, consulte Obter os resultados da avaliação na nuvem.

Avaliar traços (pré-visualização)

Avalie as interações com agentes que o Application Insights já tenha captado. Use o tipo de fonte de dados azure_ai_traces. Este cenário é útil para a avaliação pós-implementação do tráfego real de produção. Pode selecionar traços do seu pipeline de monitorização e executar avaliadores sobre os mesmos sem reexecutar quaisquer pedidos.

A avaliação de traços suporta dois modos:

• Por IDs de rastreamento - Avaliar interações específicas entre agentes fornecendo os seus operation_Id valores a partir do Application Insights.
• Por filtro de agente - Descobre e avalia automaticamente os traços recentes de um agente específico, sem ter de recolher manualmente os identificadores dos traços.

Amostragem inteligente

A avaliação de traços permite a amostragem inteligente, que seleciona um subconjunto representativo de traços para serem avaliados, em vez de avaliar todos os traços capturados. Ativa a opção de amostragem inteligente no portal da Foundry quando configurares uma execução de avaliação de traços. A amostragem inteligente reduz os custos de avaliação enquanto preserva a diversidade de traços – garantindo que casos limite, caminhos de erro e padrões variados de conversa sejam incluídos no conjunto avaliado.

Como funciona a amostragem inteligente

O algoritmo de amostragem utiliza uma abordagem de diversidade MinHash farthest-first que corre em múltiplas fases:

1. Deduplicação exata - Remove rastreios duplicados do conjunto.
2. Filtros rígidos - Remove sessões falhadas, trilhas truncadas e chamadas de ferramentas mal formadas que não são adequadas para avaliação.
3. Agregação - Combina sinais a nível de traço numa representação unificada.
4. Seleção do mais distante primeiro com MinHash - Calcula hashes sensíveis à proximidade (assinaturas MinHash) do texto do utilizador para estimar a similaridade entre registos e, em seguida, seleciona iterativamente o registo mais dissimilar do conjunto restante. Cada seleção sucessiva maximiza a distância em relação a todos os traços previamente selecionados.

Esta abordagem produz uma diversidade lexical 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 entre agentes – incluindo casos raros, difíceis e novos que a amostragem aleatória tende a ignorar.

A amostragem inteligente é particularmente eficaz para:

• Avaliação e referências - Maximiza a cobertura da distribuição dos dados de entrada para que as pontuações obtidas na avaliação reflitam a diversidade do mundo real.
• Geração de Rubricas - Produz rubricas mais focadas e acionáveis ao expor padrões de conversa diversos.
• Ajuste fino da curadoria de conjuntos de dados - Seleciona traços que ajudam os modelos a aprender de forma mais eficiente.

O algoritmo funciona inteiramente com computação local, sem chamadas adicionais de API, pelo que não incorre em custos adicionais de inferência do modelo para 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 rastreio

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

São utilizados os seguintes atributos de amplitude:

Para agentes Python construídos com o SDK do Azure AI Agent Server, adicione a extensão [tracing] para permitir a emissão automática de spans:

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

Pré-requisitos para a avaliação de traços

Para além dos pré-requisitos gerais, a avaliação de traços exige:

• Um recurso de Application Insights ligado ao seu projeto Foundry. Veja Configurar Rastreio em Microsoft Foundry.
• A identidade gerida do projeto deve ter o papel Log Analytics Reader tanto no recurso Application Insights como no seu espaço de trabalho Log Analytics associado. Se as tabelas que armazenam os seus traços estiverem protegidas (o seu nível de proteção está definido para Protegido), atribua também o papel de Leitor de Dados de Monitorização Privilegiada nos mesmos escopos para que o serviço possa ler as tabelas de rastreios protegidas.
• O pacote azure-monitor-query Python (só necessário se recolheres IDs de rastreio manualmente).

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

Defina estas variáveis de ambiente:

• APPINSIGHTS_RESOURCE_ID — O ID do recurso 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 traços. Formato: agent-name:version.
• TRACE_LOOKBACK_HOURS — (Opcional) Número de horas retroativas ao consultar rastreamentos. O valor padrão é 1.

Opção A: Avaliar por filtro de agente

A abordagem mais simples é permitir que o serviço descubra e avalie automaticamente vestígios recentes de um agente específico. Não precisas de recolher manualmente os identificadores 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 os intervalos pelo atributo invoke_agent, amostra até gen_ai.agent.id IDs de rastreamento únicos e avalia todos os intervalos desses rastreamentos.

Opção B: Avaliar por IDs de rastreamento

Para maior controlo, recolha IDs de rastreio específicos do Application Insights e avalie-os. Este método é útil quando se pretende avaliar um conjunto selecionado de interações, como traços assinalados por alertas ou amostrados para revisão de qualidade.

Recolha IDs de rastreio a partir do Application Insights

Consulte o Application Insights para operation_Id obter valores dos vestígios do seu agente. Cada um 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")

Criar avaliação e executar 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 avalia os traços, o serviço extrai automaticamente dados de conversa dos atributos do OpenTelemetry span. Use estes nomes de campo diretamente em data_mapping (sem os prefixos item. ou sample. usados noutros 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},
    ),
]

Passos seguintes

• Para verificar periodicamente a conclusão e interpretar os resultados, consulte Obter os resultados da avaliação na nuvem.
• Para um exemplo completo executável, veja sample_evaluations_builtin_with_traces.py em GitHub.