Evaluadores de agentes

Los agentes de inteligencia artificial son asistentes de productividad eficaces que pueden crear flujos de trabajo para las necesidades empresariales. Sin embargo, la observabilidad puede ser un desafío debido a sus patrones de interacción complejos. Los evaluadores de agentes proporcionan observabilidad sistemática en flujos de trabajo agente mediante la medición de la calidad, la seguridad y el rendimiento.

Normalmente, un flujo de trabajo de agente implica razonamiento a través de intenciones de usuario, llamadas a herramientas pertinentes y uso de resultados de herramientas para completar tareas como actualizar una base de datos o redactar un informe. Para compilar aplicaciones agenticas listas para producción, debe evaluar no solo la salida final, sino también la calidad y eficacia de cada paso del flujo de trabajo.

Foundry proporciona evaluadores de agentes integrados que funcionan como pruebas unitarias para sistemas agente: toman mensajes de agente como puntuaciones binarias de paso/error de entrada y salida (o puntuaciones escaladas convertidas en puntuaciones binarias basadas en umbrales). Estos evaluadores admiten dos procedimientos recomendados para la evaluación del agente:

• Evaluación del sistema: para examinar los resultados de un extremo a otro del sistema agente.
• Evaluación del proceso: para comprobar la ejecución paso a paso para lograr los resultados.

Evaluación del sistema

La evaluación del sistema examina la calidad del resultado final del flujo de trabajo agente. Estos evaluadores son aplicables a agentes únicos y, en sistemas multiagente, al orquestador principal o al agente final responsable de la finalización de tareas:

• Finalización de la tarea: ¿el agente completó completamente la tarea solicitada?
• Satisfacción del cliente: ¿Qué satisfacción tendría un usuario con el rendimiento del agente?
• Cumplimiento de tareas: ¿el agente ha seguido las reglas y restricciones en sus instrucciones?
• Eficiencia de navegación de tareas: ¿el agente realizó los pasos esperados de forma eficaz?
• Resolución de intenciones: ¿el agente identificó y direccionó correctamente las intenciones del usuario?

En concreto, para las salidas textuales de los agentes, también puede aplicar evaluadores de calidad rag, como Relevance y Groundedness que toman entradas agenticas para evaluar la calidad final de la respuesta.

Ejemplos:

• ejemplo de finalización de Task (versión preliminar)
• muestra de adhesión de Task
• ejemplo de eficiencia de navegación de Task
• ejemplo de resolución Intent

Evaluación de procesos

La evaluación de procesos examina la calidad y la eficacia de cada paso del flujo de trabajo agente. Estos evaluadores se centran en las llamadas de herramienta ejecutadas en un sistema para completar tareas:

• Precisión de llamada de la herramienta: ¿realizó el agente las llamadas a la herramienta adecuadas con parámetros correctos sin redundancia?
• Selección de herramientas: ¿ha seleccionado el agente las herramientas correctas y necesarias?
• Precisión de entrada de la herramienta: ¿el agente proporcionó parámetros correctos para las llamadas a herramientas?
• Uso de salida de la herramienta: ¿el agente ha usado correctamente la llamada a la herramienta como resultado de su razonamiento y respuesta final?
• Llamada correcta de la herramienta: ¿las llamadas a la herramienta se realizaron correctamente sin errores técnicos?

Ejemplos:

• ejemplo de precisión de llamadas Tool
• ejemplo de selección Tool
• ejemplo de precisión de entrada Tool
• ejemplo de uso de salida de Tool
• Ejemplo de éxito de llamada deTool

Evaluación de calidad (en desuso)

Quality Grader evaluó la calidad general de la respuesta de un asistente de IA en el nivel de turno. Ha examinado varias dimensiones de la calidad de respuesta:

• Relevancia : ¿Es relevante la respuesta a la consulta del usuario?
• Abstención : ¿El agente se abstiene adecuadamente cuando no puede o no debe responder?
• Integridad de la respuesta: ¿la respuesta aborda por completo la pregunta del usuario?

Cuando se proporcionó el contexto, el calificador de calidad también evaluó:

• Base: ¿se basa la respuesta en el contexto proporcionado?
• Cobertura de contexto : ¿la respuesta hace uso de la información pertinente en el contexto?

Evaluadores compuestos (versión preliminar)

Los evaluadores compuestos miden varias dimensiones de calidad en una llamada de juez LLM. Úselos para reducir el costo y la latencia de ejecutar los evaluadores integrados correspondientes por separado, a la vez que conserva una puntuación y un motivo para cada dimensión de calidad.

Calidad de salida

El evaluador de calidad de salida (builtin.output_quality) evalúa la calidad de la respuesta de un agente y su éxito al abordar la tarea del usuario. Agrupa por lotes los siguientes evaluadores en una llamada de juez LLM:

Calidad de uso de herramientas

El evaluador de calidad de uso de herramientas (builtin.tool_use_quality) evalúa el proceso de uso de herramientas de un agente a partir de la selección de herramientas mediante el uso del resultado devuelto. Agrupa por lotes los siguientes evaluadores en una llamada de juez LLM:

Resultados compuestos

El resultado o tool_use_quality principal output_quality solo pasa cuando se pasa cada componente aplicable. Se omite un componente que no es aplicable y no hace que se produzca un error en el resultado principal. Si se omiten todos los componentes, el resultado principal es not_applicable.

Cada evaluador compuesto devuelve un resultado binario principal y los resultados de sus evaluadores de componentes. Use el resultado principal para una puerta de calidad estricta y use los resultados del componente para identificar la dimensión de calidad que provocó un error.

Por ejemplo, se produce un error en un resultado de calidad de salida cuando se produce un error de fluidez, coherencia, resolución de intenciones, cumplimiento de tareas y finalización de tareas, pero se produce un error en la base. output_quality_reason identifica Groundedness como componente con errores y groundedness_reason explica su puntuación.

Configuración de evaluadores compuestos

Ambos evaluadores compuestos admiten la evaluación de nivel de conversación y de nivel de conversación. La forma de entrada determina el nivel de evaluación de forma predeterminada:

• Asignar query y response para la evaluación de nivel de turno.
• Asignar messages la evaluación de nivel de conversación.

Establezca el evaluation_level parámetro turn de inicialización en o conversation para invalidar este comportamiento.

La siguiente configuración ejecuta ambos evaluadores compuestos en el nivel de turno. La respuesta contiene mensajes de agente con llamadas de herramienta y resultados de herramientas, y las definiciones de herramientas describen las herramientas disponibles para el agente.

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "output_quality",
        "evaluator_name": "builtin.output_quality",
        "initialization_parameters": {
            "deployment_name": model_deployment,
            "evaluation_level": "turn",
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
    },
    {
        "type": "azure_ai_evaluator",
        "name": "tool_use_quality",
        "evaluator_name": "builtin.tool_use_quality",
        "initialization_parameters": {
            "deployment_name": model_deployment,
            "evaluation_level": "turn",
        },
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
            "tool_definitions": "{{item.tool_definitions}}",
        },
    },
]

Referencia: Ejecución de evaluaciones desde el SDK

Para evaluar una conversación completa, asigne la conversación completa a messages y omita o establézcala evaluation_levelconversationen :

"initialization_parameters": {
    "deployment_name": model_deployment,
    "evaluation_level": "conversation",
},
"data_mapping": {
    "messages": "{{item.messages}}",
    "tool_definitions": "{{item.tool_definitions}}",
},

Referencia: Mensajes con llamadas a herramientas

Compatibilidad con modelos y herramientas

En el caso de los evaluadores asistidos por IA, puede usar Azure OpenAI o OpenAI modelos de areasoning y modelos de no razonamiento para el juez LLM.

Herramientas compatibles

Los evaluadores de agentes admiten las siguientes herramientas:

• Búsqueda de archivos
• Function Tool (herramientas definidas por el usuario)
• MCP
• MCP basado en conocimiento

Actualmente, las siguientes herramientas tienen compatibilidad limitada. Evite usar tool_call_accuracyevaluadores de tool input accuracy, tool_output_utilization, , tool_call_successo groundedness si la conversación del agente incluye llamadas a estas herramientas:

• Búsqueda de Azure AI
• Fundamentos de Bing
• Bing Custom Search
• Fundamentos de SharePoint
• Intérprete de código
• agente de datos de Fabric
• Web Search

Uso de evaluadores de agentes

Los evaluadores de agentes evalúan el rendimiento de las tareas de los agentes de IA, siguen las instrucciones y usan herramientas de forma eficaz. Cada evaluador requiere asignaciones de datos y parámetros específicos:

La evaluación de nivel de turno puntúa una respuesta de agente individual; la evaluación de nivel de conversación puntúa la interacción completa. Use evaluation_level para seleccionar el nivel cuando el evaluador admita ambos. Para obtener la estructura de mensajes, consulte Mensajes con llamadas a herramientas.

Entrada de ejemplo

El conjunto de datos de prueba debe contener los campos a los que se hace referencia en las asignaciones de datos. Ejemplos del formato siguiente:

{"query": "What's the weather in Seattle?", "response": "The weather in Seattle is rainy, 14°C."}
{"query": "Book a flight to Paris for next Monday", "response": "I've booked your flight to Paris departing next Monday at 9:00 AM."}
{"messages": [{"role": "user", "content": "Book a flight to Paris."}, {"role": "assistant", "content": "I booked your flight to Paris."}]}

Para interacciones de agentes más complejas con llamadas de herramienta, use matrices de mensajes para query y response. Estas matrices usan la misma estructura de mensajes de OpenAI que el esquema preferido messages . Consulte Formato de consulta y respuesta independientes. El mensaje del sistema es opcional pero útil para evaluadores que evalúan el comportamiento del agente con instrucciones, como task_adherence, task_completion, tool_call_accuracy, tool_selection, tool_input_accuracy, tool_output_utilizationy groundedness:

{
    "query": [
        {"role": "system", "content": "You are a travel booking agent."},
        {"role": "user", "content": "Book a flight to Paris for next Monday"}
    ],
    "response": [
        {"role": "assistant", "content": [{"type": "tool_call", "tool_call_id": "call_123", "name": "search_flights", "arguments": {"destination": "Paris", "date": "next Monday"}}]},
        {"role": "tool", "tool_call_id": "call_123", "content": [{"type": "tool_result", "tool_result": {"flight": "AF123", "time": "9:00 AM"}}]},
        {"role": "assistant", "content": "I've booked flight AF123 to Paris departing next Monday at 9:00 AM."}
    ]
}

Formato de definiciones de herramientas

En el campo se tool_definitions describen las herramientas disponibles para el agente. Contiene una lista de objetos de herramienta con un nameobjeto de esquema parameters JSON , descriptiony :

[
  {
    "name": "search_flights",
    "description": "Search for available flights to a destination on a given date.",
    "parameters": {
      "type": "object",
      "properties": {
        "destination": { "type": "string", "description": "The destination city." },
        "date": { "type": "string", "description": "The travel date in YYYY-MM-DD format." }
      },
      "required": ["destination", "date"]
    }
  }
]

Incluya esta lista como el tool_definitions campo del conjunto de datos de prueba junto con query y response.

Ejemplo de configuración

Sintaxis de asignación de datos:

• {{item.field_name}} hace referencia a campos del conjunto de datos de prueba (por ejemplo, {{item.query}}).
• {{sample.output_items}} hace referencia a la salida estructurada del agente, incluidas las llamadas a herramientas y los resultados. Úselo para evaluadores que necesitan contexto de interacción completo (task_adherence, tool_call_accuracy, tool_selection, tool_input_accuracy, tool_output_utilization).
• {{sample.output_text}} hace referencia a la respuesta de texto sin formato del agente. Úselo para evaluadores que esperan una respuesta de cadena (por ejemplo, coherence, violence).

Esta es una configuración de ejemplo para el cumplimiento de tareas:

testing_criteria = [
    {
        "type": "azure_ai_evaluator",
        "name": "task_adherence",
        "evaluator_name": "builtin.task_adherence",
        "initialization_parameters": {"deployment_name": model_deployment},
        "data_mapping": {
            "query": "{{item.query}}",
            "response": "{{item.response}}",
        },
    },
]

Consulte Ejecución de evaluaciones desde el SDK para obtener más información sobre la ejecución de evaluaciones y la configuración de orígenes de datos.

Salida de ejemplo

Los evaluadores del agente devuelven resultados de paso/error con razonamiento. Campos de salida de clave:

{
    "type": "azure_ai_evaluator",
    "name": "Task Adherence",
    "metric": "task_adherence",
    "label": "pass",
    "reason": "Agent followed system instructions correctly",
    "threshold": 3,
    "passed": true
}

Para los evaluadores que usan una escala de 1 a 5 antes del umbral (como intent_resolution y tool_call_accuracy), la salida incluye un campo numérico score junto con el resultado de paso o error:

{
    "type": "azure_ai_evaluator",
    "name": "Intent Resolution",
    "metric": "intent_resolution",
    "label": "pass",
    "score": 4,
    "reason": "Agent correctly identified the user's intent to book a flight to Paris",
    "threshold": 3,
    "passed": true
}

Eficiencia de navegación de tareas

La eficiencia de navegación de tareas mide si el agente tomó una secuencia óptima de acciones comparando con una secuencia esperada (verdad en el terreno). Use este evaluador para las pruebas de optimización y regresión del flujo de trabajo.

{
    "type": "azure_ai_evaluator",
    "name": "task_navigation_efficiency",
    "evaluator_name": "builtin.task_navigation_efficiency",
    "initialization_parameters": {
        "matching_mode": "exact_match"  # Options: "exact_match", "in_order_match", "any_order_match"
    },
    "data_mapping": {
        "actions": "{{item.actions}}",
        "expected_actions": "{{item.expected_actions}}"
    },
}

Modos de coincidencia:

Formato de acciones:

Asigne o actionsmessages con expected_actions. El actions campo acepta una cadena o una lista de objetos de mensaje. El messages campo acepta la interacción completa como una matriz de objetos de mensaje. Cada mensaje de acción representa un paso que tomó el agente durante la conversación:

actions = [
    {
        "role": "assistant",
        "content": [
            {"type": "function_call", "name": "call_tool_A", "arguments": "{\"param\": \"value\"}"}
        ]
    },
    {
        "role": "assistant",
        "content": [
            {"type": "function_call", "name": "call_tool_B", "arguments": "{}"}
        ]
    },
]

Para proporcionar la interacción del agente como mensajes en lugar de actions, asigne messages y expected_actions:

"data_mapping": {
    "messages": "{{item.messages}}",
    "expected_actions": "{{item.expected_actions}}",
}

Formato de acciones esperadas:

expected_actions Puede ser una lista sencilla de los pasos esperados:

expected_actions = ["identify_tools_to_call", "call_tool_A", "call_tool_B", "response_synthesis"]

O una tupla con nombres y parámetros de herramientas para una validación más detallada:

expected_actions = (
    ["func_name1", "func_name2"],
    {
        "func_name1": {"param_key": "param_value"},
        "func_name2": {"param_key": "param_value"},
    }
)

Output:

Devuelve un resultado de paso o error binario más precisión, recuperación y puntuaciones F1:

{
    "type": "azure_ai_evaluator",
    "name": "task_navigation_efficiency",
    "passed": true,
    "details": {
        "precision_score": 0.85,
        "recall_score": 1.0,
        "f1_score": 0.92
    }
}

Esquema de mensajes del agente

Los evaluadores de agentes usan matrices de mensajes cuando necesitan instrucciones, llamadas a herramientas y resultados de herramientas. Para obtener la estructura de mensajes canónica, las definiciones de roles y los datos de ejemplo, consulte Mensajes con llamadas a herramientas y formato de consulta y respuesta independientes.

Contenido relacionado

• Más ejemplos del evaluador de calidad del agente
• Evaluación de los agentes de IA
• Ejecución de la evaluación por lotes
• Optimización de RAG agente