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

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

Evaluar conversaciones por ID a partir de trazas

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 trazas de OpenTelemetry — El conversation_id también puede derivarse de la cabecera traceparent si su agente usa la propagación estándar del contexto de trazas.

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).
end_time No Fin de la ventana de búsqueda (formato ISO 8601). El valor predeterminado es la hora actual. 
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="conversation_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"},
    )

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.
  • El periodo retrospectivo máximo es de 7 días (168 horas). Para acceder a seguimientos más antiguos, use start_time y end_time dentro de los límites de retención de App Insights.

Para ver un ejemplo completo y ejecutable, consulte sample_multiturn_trace_evaluation_by_id.py 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 Sí Fin del período de tiempo (segundos de época de Unix, UTC). Rellene +600 segundos para evitar retrasos en la ingesta.
max_traces No Número máximo de conversaciones que se van a muestrear. El valor predeterminado es de 1.000.
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="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}}"},
        ),
    ]

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

Note

El intervalo de tiempo de consulta de App Insights está limitado actualmente a un máximo de 7 días (168 horas). No puedes acceder a trazas de hace más de 7 días sin proporcionar explícitamente start_time y end_time, siempre que estén dentro del período de retención de App Insights.

Pasos siguientes

  • Last updated on