Avaliar conversas de modelo e agente implantados com o SDK do Microsoft Foundry (versão prévia)

Avalie as conversas completas de produção capturadas no Application Insights para investigar interações específicas ou analisar amostras de tráfego de agentes implantados.

Pré-requisitos

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

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

Avaliar conversas pelo ID a partir de rastreamentos

Avalie conversas específicas do Application Insights fornecendo suas IDs de conversa. Use esta opção para identificar a causa raiz de problemas ou verificar as correções em interações específicas. Por exemplo, você 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 de logs de rastreamento do Application Insights – Navegue para rastreamentos interessantes e localize o campo conversation_id nos detalhes do rastreamento.
Saída de log do aplicativo – se você definir conversation_id explicitamente ao criar respostas do agente, recupere-a de seus logs.
Contexto de rastreamento OpenTelemetry – O conversation_id também pode ser derivado do cabeçalho traceparent se o agente usar a propagação padrão do contexto de rastreamento.

Note

As definições de ferramenta são recuperadas automaticamente dos rastreamentos ou consultadas do registro do agente. Você não precisa fornecê-los na solicitação.

Parâmetros para pesquisa de ID de conversa

Parâmetro	Obrigatório	Descrição
`conversation_ids`	Yes	Matriz de IDs de conversa a serem avaliadas.
`lookback_hours`	Não	Horas para pesquisar retroativamente a partir de `end_time`. O valor padrão é sete dias (168 horas).
`start_time`	Não	Início de uma janela de pesquisa explícita (formato ISO 8601). Para pesquisa baseada em ID, forneça `start_time` e `end_time` para usar uma janela explícita em vez de `lookback_hours`.
`end_time`	Não	Fim da janela de pesquisa (formato ISO 8601). Usa como padrão a hora atual. Forneça `start_time` para usar uma janela explícita.

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

Use os valores testingCriteria e dataSourceConfig de Definir 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 quando os rastreamentos são gerados e quando eles estão disponíveis para avaliação. Se a consulta não encontrar rastreamentos, aguarde alguns minutos e tente novamente.
As consultas de rastreamento usam por padrão os últimos 7 dias (168 horas) quando você não fornece uma janela de tempo explícita. Para consultar um intervalo mais antigo ou personalizado, forneça start_time e end_time, sujeito à retenção do Application Insights.

Para obter um exemplo executável completo, consulte sample_multiturn_trace_evaluation_by_id.py do SDK Python versão 2.7.0 no GitHub.

Avaliar conversas amostradas por filtro de agente

Avalie um conjunto de conversas de exemplo do Application Insights filtrando o nome do agente. Use essa opção para avaliar a qualidade geral do agente em todo o tráfego de produção. Por exemplo, execute avaliações regulares de qualidade ou monitore a degradação da qualidade na produção.

O agente especificado para filtragem pode fazer parte de uma conversa com vários agentes. O filtro corresponde a qualquer conversa em que o agente participou.

Note

As definições de ferramenta são recuperadas automaticamente dos rastreamentos ou consultadas do registro do agente. Você não precisa fornecê-los na solicitação.

Campos de identidade do agente

Especifique o agente a ser filtrado usando um destes formatos:

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

Estratégias de filtro

Strategy	Descrição
`random_sampling`	(Padrão) Amostra aleatória uniforme de até conversas `max_traces`.
`smart_filtering`	Heurística gerenciada pelo serviço que prioriza rastros "interessantes": conversas com possíveis problemas, casos de borda ou anomalias.

Parameters

Parâmetro	Obrigatório	Descrição
`agent_name`	Yes	O nome do agente pelo qual filtrar rastreamentos.
`agent_version`	Não	A versão do agente. Se não for especificado, usa a versão mais recente.
`agent_id`	Não	Alternativa a `agent_name` + `agent_version`. Cadeia de caracteres única no formato `"name:version"`.
`start_time`	Yes	Início da janela de tempo (segundos de época do Unix, UTC).
`end_time`	Não	Fim da janela de tempo (segundos de época unix, UTC). Usa o horário UTC atual por padrão. Adicione +600 segundos para evitar atraso na ingestão na borda da janela.
`max_traces`	Não	Número máximo de conversas a serem selecionadas como amostra. O valor padrão é 1,000.
`filter_strategy`	Não	`"random_sampling"` (padrão) ou `"smart_filtering"` (heurística gerenciada pelo serviço que favorece rastreamentos interessantes).

Importante

A janela de tempo (end_time - start_time) deve ser de pelo menos 15 minutos (900 segundos). Esse requisito existe porque as consultas em nível de 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"},
    )

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

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 usam por padrão os últimos 7 dias (168 horas) quando você não fornece uma janela de tempo explícita. Consultas de filtro de agente respeitam start_time exatamente. Se você omitir end_time, o serviço usará a hora UTC atual. Você pode consultar intervalos mais antigos ou personalizados dentro dos limites de retenção do Application Insights.

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

Comentários

Esta página foi útil?

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

Avaliar conversas de modelo e agente implantados com o SDK do Microsoft Foundry (versão prévia)

Pré-requisitos

Avaliar conversas pelo ID a partir de rastreamentos

Onde encontrar IDs de conversa

Parâmetros para pesquisa de ID de conversa

Avaliar conversas amostradas por filtro de agente

Campos de identidade do agente

Estratégias de filtro

Parameters

Próximas Etapas

Comentários

Recursos adicionais