Evaluación de conversaciones de agente y modelo implementadas con Microsoft SDK de Foundry (versión preliminar)

Evalúe las conversaciones completas de producción capturadas en Application Insights para investigar interacciones específicas o examinar una muestra del tráfico de agentes implementados.

Prerequisites

Complete los requisitos previos de evaluación en la nube y la configuración del cliente.
Para el flujo de trabajo de evaluación de seguimiento de versión preliminar, utilice la versión 2.7.0 del SDK de Python (pip install "azure-ai-projects==2.7.0") o la versión 2.7.0 del SDK de JavaScript (npm install "@azure/ai-projects@2.7.0").
Conversaciones de producción rastreadas en Application Insights.
Evaluadores en el nivel de conversación que admitan el nivel de evaluación seleccionado.

En los ejemplos se usa el cliente del SDK configurado en Configuración del cliente del SDK.

Evaluar conversaciones por ID a partir de seguimientos

Evalúe conversaciones específicas de Application Insights proporcionando sus identificadores de conversación. Use esta opción para solucionar problemas de causa principal o comprobar correcciones en interacciones específicas. Por ejemplo, puede investigar una conversación marcada por una alerta o comprobar una corrección de un problema conocido.

Dónde encontrar identificadores de conversación

Busque identificadores de conversación en:

Interfaz de usuario de registros de seguimiento de Application Insights: vaya a seguimientos de interés y busque el campo conversation_id en los detalles del seguimiento.
Salida de registro de la aplicación : si establece conversation_id explícitamente al crear respuestas del agente, recuperela de los registros.
Contexto de seguimiento de OpenTelemetry: El conversation_id también puede obtenerse del encabezado traceparent si el agente usa la propagación estándar del contexto de seguimiento.

Note

Las definiciones de herramientas se recuperan automáticamente de los seguimientos o se consultan desde el registro del agente. No es necesario proporcionarlos en la solicitud.

Parámetros para la búsqueda de ID de conversación

Parámetro	Obligatorio	Descripción
`conversation_ids`	Sí	Lista de identificadores de conversaciones para evaluar.
`lookback_hours`	No	Horas para volver a buscar desde `end_time`. El valor predeterminado es siete días (168 horas).
`start_time`	No	Inicio de una ventana de búsqueda explícita (formato ISO 8601). En el caso de la búsqueda basada en identificadores, proporcione tanto `start_time` como `end_time` para usar una ventana explícita en lugar de `lookback_hours`.
`end_time`	No	Fin de la ventana de búsqueda (formato ISO 8601). El valor predeterminado es la hora actual. Proporciónelo con `start_time` para usar una ventana 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"},
    )

Usa los valores dataSourceConfig y testingCriteria de Define el esquema de datos y los evaluadores.

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

Referencia: 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

La ingestión de datos de Application Insights puede provocar un retraso entre el momento en que se generan las trazas y aquel en que están disponibles para evaluarlas. Si la consulta no encuentra trazas, espere unos minutos y vuelva a intentarlo.
Las consultas de seguimiento tienen como valor predeterminado los últimos 7 días (168 horas) cuando no se proporciona un período de tiempo explícito. Para consultar un intervalo más antiguo o personalizado, proporcione start_time y end_time, sujeto a la retención de Application Insights.

Para obtener un ejemplo completo de ejecución, consulte sample_multiturn_trace_evaluation_by_id.py del SDK de Python versión 2.7.0 en GitHub.

Evaluación de conversaciones muestreadas por filtro de agente

Evalúe un conjunto muestreado de conversaciones de Application Insights filtrando por el nombre del agente. Use esta opción para evaluar la calidad general del agente en el tráfico de producción. Por ejemplo, ejecute evaluaciones de calidad normales o supervise la degradación de la calidad en producción.

El agente que especifique para el filtrado puede formar parte de una conversación multiagente. El filtro coincide con cualquier conversación en la que participó ese agente.

Note

Las definiciones de herramientas se recuperan automáticamente de los seguimientos o se consultan desde el registro del agente. No es necesario proporcionarlos en la solicitud.

Campos de identidad del agente

Especifique el agente que se va a filtrar mediante uno de estos formatos:

Formato	Example	Descripción
`agent_name` + `agent_version`	`"agent_name": "my-agent", "agent_version": "1"`	Dos campos independientes. Si `agent_version` se omite, use la versión más reciente.
`agent_id`	`"agent_id": "my-agent:1"`	Una sola cadena en formato `"name:version"`.

Estrategias de filtro

Strategy	Descripción
`random_sampling`	(Valor predeterminado) Muestra aleatoria uniforme de hasta `max_traces` conversaciones.
`smart_filtering`	Heurística gestionada por el servicio que prioriza las trazas "interesantes": conversaciones con posibles problemas, casos extremos o anomalías.

Parameters

Parámetro	Obligatorio	Descripción
`agent_name`	Sí	Nombre del agente por el que se van a filtrar los seguimientos.
`agent_version`	No	La versión del agente. Si se omite, usa la versión más reciente.
`agent_id`	No	Alternativa a `agent_name` + `agent_version`. Cadena única con formato `"name:version"`.
`start_time`	Sí	Inicio del período de tiempo (segundos de época de Unix, UTC).
`end_time`	No	Fin del período de tiempo (segundos de época de Unix, UTC). El valor predeterminado es la hora UTC actual. Rellene con +600 segundos para evitar el retraso de ingesta en el borde de la ventana.
`max_traces`	No	Número máximo de conversaciones que se van a muestrear. Su valor predeterminado es 1000.
`filter_strategy`	No	`"random_sampling"` (predeterminado) o `"smart_filtering"` (heurística gestionada por el servicio que da prioridad a las trazas interesantes).

Importante

El período de tiempo (end_time - start_time) debe ser de al menos 15 minutos (900 segundos). Este requisito existe porque las consultas a nivel de conversación aplican un margen de inactividad de 5 minutos en cada extremo para evitar conversaciones parciales.

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

Usa el valor testingCriteria de Definir el esquema de datos y evaluadores. Establezca FOUNDRY_AGENT_NAME. Para evaluar una versión específica del agente, establezca también FOUNDRY_AGENT_VERSION; de lo contrario, se usa la versión más reciente.

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

Referencia: 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

Las consultas de seguimiento tienen como valor predeterminado los últimos 7 días (168 horas) cuando no se proporciona un período de tiempo explícito. Las consultas de filtro de agente respetan start_time exactamente. Si omite end_time, el servicio usa la hora UTC actual. Puede consultar intervalos más antiguos o personalizados dentro de los límites de retención de Application Insights.

Pasos siguientes

Para sondear la finalización e interpretar los resultados, consulte Obtención de resultados de evaluación en la nube.
Para obtener un ejemplo completo de ejecución, consulte sample_multiturn_trace_evaluation_agent_filter.py del SDK de Python versión 2.7.0 en GitHub.
Para evaluar las conversaciones almacenadas, consulte Evaluación de conjuntos de datos de conversación.
Para generar conversaciones sintéticas, consulte Simulate agent conversations (Simular conversaciones de agente).

Comentarios

¿Le ha resultado útil esta página?

Se actualizó por última vez el 2026-10-08

Evaluación de conversaciones de agente y modelo implementadas con Microsoft SDK de Foundry (versión preliminar)

Prerequisites

Evaluar conversaciones por ID a partir de seguimientos

Dónde encontrar identificadores de conversación

Parámetros para la búsqueda de ID de conversación

Evaluación de conversaciones muestreadas por filtro de agente

Campos de identidad del agente

Estrategias de filtro

Parameters

Pasos siguientes

Comentarios

Recursos adicionales