Avaliar conversas de modelos e agentes implementados com o Microsoft Foundry SDK (pré-visualização)

Avaliar conversas completas de produção captadas no Application Insights para investigar interações específicas ou amostrar o tráfego de agentes implementados.

Pré-requisitos

Complete os pré-requisitos de avaliação cloud e a configuração do cliente.
Para o fluxo de trabalho de avaliação de traces de pré-visualização, use a versão 2.7.0 do SDK Python (pip install "azure-ai-projects==2.7.0") ou a versão 2.7.0 do SDK do JavaScript (npm install "@azure/ai-projects@2.7.0").
Rastreei conversas de produção no Application Insights.
Avaliadores ao nível da conversa que apoiam o nível de avaliação selecionado.

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

Avaliar conversas pelo ID com base em rastos

Avalie conversas específicas do Application Insights fornecendo os seus IDs de conversa. Utilize esta opção para identificar a causa raiz dos problemas ou validar correções em interações específicas. Por exemplo, pode investigar uma conversa sinalizada por um alerta ou verificar uma correção para um problema conhecido.

Onde encontrar IDs de conversa

Encontre IDs de conversa em:

IU dos registos de rastreio do Application Insights — Vá para rastreios interessantes e localize o campo conversation_id nos detalhes do rastreio.
Saída de registo da sua aplicação — Se definir conversation_id explicitamente ao criar respostas de agentes, recupere-a dos seus registos.
Contexto de rastreio OpenTelemetry — O conversation_id também pode ser derivado do cabeçalho traceparent se o seu agente usar a propagação padrão de contexto de rastreio.

Note

As definições das ferramentas são automaticamente obtidas a partir dos rastreios ou através de consulta ao registo do agente. Não precisas de os fornecer no pedido.

Parâmetros para a procura do ID da conversa

Parâmetro	Obrigatório	Descrição
`conversation_ids`	Sim	Matriz de IDs de conversa para avaliar.
`lookback_hours`	No	Horas para procurar de volta a partir de `end_time`. O valor predefinido é de sete dias (168 horas).
`start_time`	No	Início de uma janela de pesquisa explícita (formato ISO 8601). Para pesquisa baseada em ID, forneça ambos `start_time` e `end_time` para usar uma janela explícita em vez de `lookback_hours`.
`end_time`	No	Fim da janela de pesquisa (formato ISO 8601). Predefinido para a hora atual. Forneça-lhe `start_time` para usar uma janela específica.

import os
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]

# Provide conversation IDs or trace IDs from App Insights
conversation_ids = ["conversation_1234", "conversation_5678"]

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="output_quality",
            evaluator_name="builtin.output_quality",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="tool_use_quality",
            evaluator_name="builtin.tool_use_quality",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="deflection_rate",
            evaluator_name="builtin.deflection_rate",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

    # Create evaluation with traces scenario
    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (by ID)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # Run evaluation on specific conversation IDs
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-trace-by-id-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": {
                "type": "conversation_id_source",
                "conversation_ids": conversation_ids,
            },
        },
        extra_body={"evaluation_level": "conversation"},
    )

Utilize os valores dataSourceConfig e testingCriteria de Defina o esquema de dados e os avaliadores.

    string[] conversationIds = ["conversation_1234", "conversation_5678"];
    BinaryData evaluationData = BinaryData.FromObjectAsJson(new
    {
      name = "Multi-turn Trace Evaluation (by ID)",
      data_source_config = new
      {
        type = "azure_ai_source",
        scenario = "traces"
      },
      testing_criteria = testingCriteria
    });
    using BinaryContent evaluationContent = BinaryContent.Create(evaluationData);
    ClientResult evaluation = await evaluationClient.CreateEvaluationAsync(
      evaluationContent);
    string evaluationId = GetString(evaluation, "id");

    BinaryData runData = BinaryData.FromObjectAsJson(new
    {
      name = "multiturn-trace-by-id-run",
      evaluation_level = "conversation",
      data_source = new
      {
        type = "azure_ai_trace_data_source_preview",
        trace_source = new
        {
          type = "conversation_id_source",
          conversation_ids = conversationIds,
          lookback_hours = 24
        }
      }
    });
    using BinaryContent runContent = BinaryContent.Create(runData);
    ClientResult evaluationRun = await evaluationClient.CreateEvaluationRunAsync(
      evaluationId: evaluationId,
      content: runContent);
    Console.WriteLine($"Evaluation run created: {GetString(evaluationRun, "id")}");

Referência: EvaluationClient métodos de protocolo

import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const projectEndpoint =
  process.env.AZURE_AI_PROJECT_ENDPOINT ?? "<project endpoint>";
const modelDeploymentName =
  process.env.AZURE_AI_MODEL_DEPLOYMENT_NAME ?? "<model deployment name>";
const conversationIds = ["conversation_1234", "conversation_5678"];

const projectClient = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
);
const openAIClient = projectClient.getOpenAIClient();

const evaluator = (name: string, includeToolDefinitions = false) => ({
  type: "azure_ai_evaluator",
  name,
  evaluator_name: `builtin.${name}`,
  initialization_parameters: { model: modelDeploymentName },
  data_mapping: includeToolDefinitions
    ? {
        messages: "{{item.messages}}",
        tool_definitions: "{{item.tool_definitions}}",
      }
    : { messages: "{{item.messages}}" },
});

const testingCriteria = [
  evaluator("output_quality", true),
  evaluator("tool_use_quality", true),
  evaluator("deflection_rate", true),
  evaluator("customer_satisfaction"),
  evaluator("task_completion"),
  evaluator("coherence"),
  evaluator("groundedness"),
];

const evaluation = await openAIClient.evals.create({
  name: "Multi-turn Trace Evaluation (by ID)",
  data_source_config: {
    type: "azure_ai_source",
    scenario: "traces",
  } as any,
  testing_criteria: testingCriteria as any,
});

const evaluationRun = await openAIClient.evals.runs.create(evaluation.id, {
  name: "multiturn-trace-by-id-run",
  data_source: {
    type: "azure_ai_trace_data_source_preview",
    trace_source: {
      type: "conversation_id_source",
      conversation_ids: conversationIds,
      lookback_hours: 24,
    },
  },
  evaluation_level: "conversation",
} as any);

console.log(`Evaluation run created: ${evaluationRun.id}`);

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals/${EVAL_ID}/runs?api-version=2025-11-15-preview" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "conversation-trace-eval",
    "evaluation_level": "conversation",
    "data_source": {
      "type": "azure_ai_trace_data_source_preview",
      "trace_source": {
        "type": "conversation_id_source",
        "conversation_ids": ["conversation_1234", "conversation_5678"],
        "lookback_hours": 24,
        "end_time": "2026-05-21T00:00:00Z"
      }
    }
  }'

Note

A ingestão de dados do Application Insights pode causar um atraso entre o momento em que os traços são gerados e o momento em que estão disponíveis para avaliação. Se a consulta não encontrar rastos, espere alguns minutos e tente novamente.
As consultas de rastreamento correspondem por defeito aos últimos 7 dias (168 horas) quando não se fornece uma janela de tempo explícita. Para consultar um intervalo mais antigo ou personalizado, fornecer start_time e end_time, sujeito à retenção do Application Insights.

Para um exemplo completo executável, veja sample_multiturn_trace_evaluation_by_id.py do SDK Python versão 2.7.0 em GitHub.

Avalie conversas amostradas por filtro de agente

Avalie um conjunto amostrado de conversas do Application Insights filtrando pelo nome do agente. Use esta opção para avaliar a qualidade global do agente em todo o tráfego de produção. Por exemplo, realizar avaliações regulares de qualidade ou monitorizar a degradação da qualidade na produção.

O agente que especificar para a filtragem pode fazer parte de uma conversa entre vários agentes. O filtro corresponde a qualquer conversa em que esse agente tenha participado.

Note

As definições das ferramentas são automaticamente obtidas a partir dos rastreios ou através de consulta ao registo do agente. Não precisas de os fornecer no pedido.

Campos de identidade do agente

Especifique o agente a filtrar usando um destes formatos:

Format	Example	Descrição
`agent_name` + `agent_version`	`"agent_name": "my-agent", "agent_version": "1"`	São dois campos separados. Se `agent_version` for omitido, use a versão mais recente.
`agent_id`	`"agent_id": "my-agent:1"`	Cadeia única no formato `"name:version"`.

Estratégias de filtro

Strategy	Descrição
`random_sampling`	(Padrão) Amostra aleatória uniforme até `max_traces` conversas.
`smart_filtering`	Heurística gerida pelo serviço que privilegia rastreios "interessantes" — conversas com potenciais problemas, casos extremos ou anomalias.

Parameters

Parâmetro	Obrigatório	Descrição
`agent_name`	Sim	O nome do agente pelo qual filtrar os rastreios.
`agent_version`	No	A versão do agente. Se omitido, usa a versão mais recente.
`agent_id`	No	Alternativa a `agent_name` + `agent_version`. Uma única cadeia de caracteres no formato `"name:version"`.
`start_time`	Sim	Início da janela temporal (segundos da época Unix, UTC).
`end_time`	No	Fim da janela temporal (segundos da época Unix, UTC). Por defeito, assume a hora UTC atual. Adicione +600 segundos para evitar atraso na ingestão na borda da janela.
`max_traces`	No	Número máximo de conversas a amostrar. Por predefinição, é 1 000.
`filter_strategy`	No	`"random_sampling"` (predefinido) ou `"smart_filtering"` (heurística gerida pelo serviço que dá prioridade a rastreios interessantes).

Importante

A janela temporal (end_time - start_time) deve ser de pelo menos 15 minutos (900 segundos). Este requisito existe porque as consultas ao nível da conversa aplicam um buffer de inatividade de 5 minutos em cada extremidade para evitar conversas parciais.

import os
import time
from azure.identity import DefaultAzureCredential
from azure.ai.projects import AIProjectClient
from azure.ai.projects.models import TestingCriterionAzureAIEvaluator

endpoint = os.environ["AZURE_AI_PROJECT_ENDPOINT"]
model_deployment_name = os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"]
agent_name = os.environ["FOUNDRY_AGENT_NAME"]
agent_version = os.environ.get("FOUNDRY_AGENT_VERSION", "")

with (
    DefaultAzureCredential() as credential,
    AIProjectClient(endpoint=endpoint, credential=credential) as project_client,
    project_client.get_openai_client() as openai_client,
):
    # Eval group for trace-based evaluations
    data_source_config = {
        "type": "azure_ai_source",
        "scenario": "traces",
    }

    testing_criteria = [
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="output_quality",
            evaluator_name="builtin.output_quality",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="tool_use_quality",
            evaluator_name="builtin.tool_use_quality",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="deflection_rate",
            evaluator_name="builtin.deflection_rate",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={
                "messages": "{{item.messages}}",
                "tool_definitions": "{{item.tool_definitions}}",
            },
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="customer_satisfaction",
            evaluator_name="builtin.customer_satisfaction",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="task_completion",
            evaluator_name="builtin.task_completion",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="coherence",
            evaluator_name="builtin.coherence",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
        TestingCriterionAzureAIEvaluator(
            type="azure_ai_evaluator",
            name="groundedness",
            evaluator_name="builtin.groundedness",
            initialization_parameters={"model": model_deployment_name},
            data_mapping={"messages": "{{item.messages}}"},
        ),
    ]

    eval_object = openai_client.evals.create(
        name="Multi-turn Trace Evaluation (Agent Filter)",
        data_source_config=data_source_config,
        testing_criteria=testing_criteria,
    )

    # 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 - (24 * 3600)  # 24 hours lookback

    # Build trace_source with agent filter
    trace_source = {
        "type": "agent_filter",
        "agent_name": agent_name,
        "start_time": start_time,
        "end_time": end_time,
        "max_traces": 5,
    }
    if agent_version:
        trace_source["agent_version"] = agent_version

    # Run evaluation on sampled agent conversations
    eval_run = openai_client.evals.runs.create(
        eval_id=eval_object.id,
        name="multiturn-agent-filter-run",
        data_source={
            "type": "azure_ai_trace_data_source_preview",
            "trace_source": trace_source,
        },
        extra_body={"evaluation_level": "conversation"},
    )

Utilize o valor testingCriteria de Defina o esquema de dados e os avaliadores. Defina FOUNDRY_AGENT_NAME. Para avaliar uma versão específica do agente, também define FOUNDRY_AGENT_VERSION; caso contrário, é usada a versão mais recente.

var agentName = Environment.GetEnvironmentVariable("FOUNDRY_AGENT_NAME")
  ?? throw new InvalidOperationException("FOUNDRY_AGENT_NAME isn't set.");
var agentVersion = Environment.GetEnvironmentVariable(
  "FOUNDRY_AGENT_VERSION");
long now = DateTimeOffset.UtcNow.ToUnixTimeSeconds();
var traceSource = new Dictionary<string, object>
{
  ["type"] = "agent_filter",
  ["agent_name"] = agentName,
  ["start_time"] = now - (24 * 3600),
  ["end_time"] = now + 600,
  ["max_traces"] = 5,
  ["filter_strategy"] = "random_sampling"
};
if (!string.IsNullOrWhiteSpace(agentVersion))
{
  traceSource["agent_version"] = agentVersion;
}

BinaryData evaluationData = BinaryData.FromObjectAsJson(new
{
  name = "Multi-turn Trace Evaluation (Agent Filter)",
  data_source_config = new
  {
    type = "azure_ai_source",
    scenario = "traces"
  },
  testing_criteria = testingCriteria
});
using BinaryContent evaluationContent = BinaryContent.Create(evaluationData);
ClientResult evaluation = await evaluationClient.CreateEvaluationAsync(
  evaluationContent);
string evaluationId = GetString(evaluation, "id");

BinaryData runData = BinaryData.FromObjectAsJson(new
{
  name = "multiturn-agent-filter-run",
  evaluation_level = "conversation",
  data_source = new
  {
    type = "azure_ai_trace_data_source_preview",
    trace_source = traceSource
  }
});
using BinaryContent runContent = BinaryContent.Create(runData);
ClientResult evaluationRun = await evaluationClient.CreateEvaluationRunAsync(
  evaluationId: evaluationId,
  content: runContent);
Console.WriteLine($"Evaluation run created: {GetString(evaluationRun, "id")}");

Referência: EvaluationClient métodos de protocolo

import { AIProjectClient } from "@azure/ai-projects";
import { DefaultAzureCredential } from "@azure/identity";

const projectEndpoint =
  process.env.AZURE_AI_PROJECT_ENDPOINT ?? "<project endpoint>";
const modelDeploymentName =
  process.env.AZURE_AI_MODEL_DEPLOYMENT_NAME ?? "<model deployment name>";
const agentName = process.env.FOUNDRY_AGENT_NAME ?? "<agent name>";
const agentVersion = process.env.FOUNDRY_AGENT_VERSION ?? "";

const projectClient = new AIProjectClient(
  projectEndpoint,
  new DefaultAzureCredential(),
);
const openAIClient = projectClient.getOpenAIClient();

const evaluator = (name: string, includeToolDefinitions = false) => ({
  type: "azure_ai_evaluator",
  name,
  evaluator_name: `builtin.${name}`,
  initialization_parameters: { model: modelDeploymentName },
  data_mapping: includeToolDefinitions
    ? {
        messages: "{{item.messages}}",
        tool_definitions: "{{item.tool_definitions}}",
      }
    : { messages: "{{item.messages}}" },
});

const testingCriteria = [
  evaluator("output_quality", true),
  evaluator("tool_use_quality", true),
  evaluator("deflection_rate", true),
  evaluator("customer_satisfaction"),
  evaluator("task_completion"),
  evaluator("coherence"),
  evaluator("groundedness"),
];

const evaluation = await openAIClient.evals.create({
  name: "Multi-turn Trace Evaluation (Agent Filter)",
  data_source_config: {
    type: "azure_ai_source",
    scenario: "traces",
  } as any,
  testing_criteria: testingCriteria as any,
});

const now = Math.floor(Date.now() / 1000);
const traceSource: Record<string, unknown> = {
  type: "agent_filter",
  agent_name: agentName,
  start_time: now - 24 * 60 * 60,
  end_time: now + 10 * 60,
  max_traces: 100,
  filter_strategy: "random_sampling",
  ...(agentVersion ? { agent_version: agentVersion } : {}),
};

const evaluationRun = await openAIClient.evals.runs.create(evaluation.id, {
  name: "multiturn-agent-filter-run",
  data_source: {
    type: "azure_ai_trace_data_source_preview",
    trace_source: traceSource,
  },
  evaluation_level: "conversation",
} as any);

console.log(`Evaluation run created: ${evaluationRun.id}`);

curl --request POST \
  --url "https://${ACCOUNT}.services.ai.azure.com/api/projects/${PROJECT}/openai/evals/${EVAL_ID}/runs?api-version=2025-11-15-preview" \
  --header "Authorization: Bearer ${TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{
    "name": "agent-quality-eval",
    "evaluation_level": "conversation",
    "data_source": {
      "type": "azure_ai_trace_data_source_preview",
      "trace_source": {
        "type": "agent_filter",
        "agent_name": "my-support-agent",
        "agent_version": "1",
        "start_time": 1743465600,
        "end_time": 1743552600,
        "max_traces": 100,
        "filter_strategy": "random_sampling"
      }
    }
  }'

Note

As consultas de rastreamento correspondem por defeito aos últimos 7 dias (168 horas) quando não se fornece uma janela de tempo explícita. As consultas de filtro de agente respeitam start_time exatamente. Se omitir end_time, o serviço usa a hora UTC atual. Pode consultar intervalos antigos ou personalizados dentro dos limites de retenção do Application Insights.

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_multiturn_trace_evaluation_agent_filter.py do SDK Python versão 2.7.0 na GitHub.
Para avaliar conversas armazenadas, consulte Avaliar conjuntos de dados de conversa.
Para gerar conversas sintéticas, veja Simular conversas com agentes.

Comentários

Esta página foi útil?

Última atualização a 2026-10-08

Avaliar conversas de modelos e agentes implementados com o Microsoft Foundry SDK (pré-visualização)

Pré-requisitos

Avaliar conversas pelo ID com base em rastos

Onde encontrar IDs de conversa

Parâmetros para a procura do ID da conversa

Avalie conversas amostradas por filtro de agente

Campos de identidade do agente

Estratégias de filtro

Parameters

Passos seguintes

Comentários

Recursos adicionais