Evaluaciones

Acerca de las evaluaciones

Cuando diseñas un agente, el objetivo es que sea fiable: algo en lo que puedas confiar para que te dé el resultado correcto de forma consistente. Las evaluaciones te ayudan a determinar si tu agente está haciendo un buen trabajo o si necesita mejoras.

Terminología

Una evaluación es un par entre una entrada y una aserción (o evaluador) realizada en la salida. El evaluador es una condición o regla definida que se utiliza para evaluar si la salida del agente cumple con el resultado o la trayectoria esperados.

Los conjuntos de evaluación son agrupaciones lógicas de evaluaciones y evaluadores.

Los resultados de evaluación son seguimientos de ejecuciones de evaluación completadas que evalúan el rendimiento de un agente. Durante estas ejecuciones se miden la precisión, la eficiencia y la capacidad de toma de decisiones del agente y se puntúan en función del rendimiento del agente.

La puntuación de evaluación determina el rendimiento del agente en función de las aserciones en una evaluación específica. La puntuación es en una escala de 0 a 100. Si has fallado las ejecuciones de evaluación, debes diagnosticar la causa, depurar y volver a ejecutarlas.

Crear evaluaciones

Antes de crear evaluaciones a escala, puedes probar primero tu agente en escenarios desactivados para ver si el agente puede realizar su tarea y si la salida es correcta o no. Si tu agente genera la salida correcta, puedes crear evaluaciones a partir de las ejecuciones correctas. Si tu agente no genera la salida correcta, puedes corregir la salida y crear una evaluación con la salida esperada, puedes crear evaluaciones desde cero.

Crear evaluaciones a partir de ejecuciones de pruebas

1. Después de diseñar tu agente, selecciona Configuración de depuración.
2. En la ventana Configuración de depuración, confirma los recursos utilizados en la solución y:
   1. Proporciona la entrada para la ejecución de la prueba:
      • Proporciona entradas manualmente escribiendo el contenido, o
      • Simula entradas: utiliza un LLM para generar entradas para los argumentos de tu agente. Puedes dejar que el LLM genere automáticamente entradas o proporcione instrucciones para dirigirlo hacia ejemplos específicos.
   2. Configura si quieres probar con herramientas reales o simular una, más o todas tus herramientas.
      • Simular herramientas: utiliza un LLM para simular una o más herramientas de agente. Describe cómo debe responder cada herramienta y simula los conjuntos de herramientas parciales o completos en los que se basa tu agente.
3. Selecciona Guardar y depurar. Los resultados se muestran en el panel inferior Seguimiento de ejecución. Hay indicadores disponibles que mostrar cuando el agente se ejecuta con datos reales o simulados.
4. Si la salida es correcta, selecciona el botón Añadir al conjunto de evaluación. Si la salida no es correcta, puedes:
   • Refinar la solicitud: ajusta la solicitud y prueba el agente hasta que la salida sea correcta.
   • Crear evaluaciones a partir de salidas incorrectas: genera evaluaciones basadas en las salidas incorrectas y edítalas manualmente para que se alineen con el resultado esperado.
5. Las ejecuciones de prueba se muestran en la ventana Añadir a conjunto de evaluación. Selecciona Añadir a conjunto predeterminado para cualquier ejecución que quieras añadir a una evaluación. Si ya has creado un conjunto de evaluación, puedes seleccionarlo en la lista desplegable disponible.
6. A continuación, ve al panel Conjuntos de evaluación. Hay tres opciones disponibles:
   1. Utiliza el conjunto de evaluación prediseñado para organizar tus evaluaciones.
   2. Genera un nuevo conjunto con entradas y herramientas simuladas.
   3. Añade evaluaciones en conjuntos existentes con datos reales y simulados.
7. Selecciona Evaluar conjunto para ejecutar las evaluaciones. También puedes seleccionar evaluaciones específicas a partir del conjunto que deseas evaluar.
8. Ve a la pestaña Resultados para ver la puntuación y los detalles de la evaluación.

Crear evaluaciones desde cero

1. Después de diseñar tu agente, ve a la pestaña Conjuntos de evaluación y selecciona Crear nuevo. También puedes seleccionar Importar para utilizar los datos JSON existentes de evaluaciones de otros agentes.
2. Añade un nombre relevante para el conjunto de evaluación.
3. Selecciona Añadir al conjunto para crear nuevas evaluaciones. Para cada nueva evaluación del conjunto:
   1. Añade un nombre.
   2. Añade valores para los campos de Entrada (heredados de los argumentos de entrada definidos) y la Salida esperada.
   3. Selecciona Guardar.
4. A continuación, selecciona Establecer evaluadores para asignar evaluadores al conjunto de evaluación. Puedes asignar uno o varios evaluadores a un conjunto.
5. Selecciona Guardar cambios.
6. En la página principal de Conjuntos de evaluación, selecciona Ejecutar conjunto de evaluación para cada conjunto que deseas ejecutar.
7. Ve a la pestaña Resultados para ver la puntuación y los detalles de la evaluación.

Crear evaluaciones a partir de seguimientos de runtime

Puedes crear evaluaciones de agentes directamente a partir de los seguimientos de runtime, lo que te permite convertir los comentarios de producción en casos de prueba accionables para mejoras en tiempo de diseño.

1. Primero, ejecuta tu agente.
2. En Orchestrator, ve a Automatizaciones > Trabajos y abre los seguimientos de trabajo para la ejecución del agente. Como alternativa, ve a la página Gestión de instancias de agente para ver los seguimientos de las ejecuciones de agente.
3. Proporciona comentarios para las ejecuciones del agente:
   • Para cada seguimiento, selecciona el icono de pulgares arriba o abajo.
   • Añade un comentario para hacer que la evaluación sea procesable.
4. Obtener seguimientos de runtime en la definición del agente:
   • Vuelve a tu agente en Studio Web y ve a Evaluaciones > Conjuntos de evaluación.
   • En el botón Crear, selecciona Obtener seguimientos de runtime para extraer seguimientos que hayan recibido comentarios.
5. Añadir seguimientos a un conjunto de evaluación:
   • De los seguimientos recuperados, selecciona Añadir al conjunto de evaluación.
   • Edita la entrada y la salida esperada si es necesario.
   • Guarda el seguimiento en el conjunto de evaluación elegido.
6. Guarda el seguimiento en el conjunto de evaluación elegido.

Una vez añadidos, los seguimientos de runtime están claramente etiquetados como ejecuciones de runtime dentro del conjunto de evaluación, lo que facilita la distinción de las ejecuciones de prueba sin conexión. Estos seguimientos también actualizan la puntuación de evaluación general del agente automáticamente, lo que te brinda visibilidad inmediata de cómo los comentarios del mundo real mejoran el rendimiento del agente.

Generar evaluaciones

También puedes crear conjuntos de evaluación con simulaciones. Genera nuevos conjuntos de evaluación (o añádelos a los ya existentes) utilizando entradas y herramientas simuladas.

1. Selecciona Crear.
2. Selecciona Generar nuevo conjunto de evaluación. Puedes dejar que el LLM genere automáticamente el conjunto de evaluación en función de tu agente existente, sus ejecuciones de diseño o argumentos o proporcionar solicitudes para dirigirlo hacia ejemplos específicos. Para obtener más detalles, consulta Configurar simulaciones en evaluaciones.

Evaluadores

Los evaluadores definen cómo se puntúan las salidas del agente en comparación con el comportamiento o los resultados esperados. Al añadir un evaluador a un conjunto de evaluación, selecciona el tipo de evaluador que mejor coincida con el tipo de validación que quieres realizar.

Al añadir o editar un evaluador, las opciones de configuración que ves dependen de la categoría del evaluador y el tipo de evaluador que selecciones.

Categorías de evaluador

Categoría de evaluador	Tipo de evaluador	Descripción
Determinista	Coincidencia exacta	Comprueba si la salida del agente coincide exactamente con la salida esperada, sin variaciones en la redacción o el formato.
Determinista	Similitud de JSON	Compara la similitud estructural de los objetos o valores JSON en lugar de requerir una coincidencia exacta.
Determinista	Coincidencia exacta de columna CSV	Compara valores exactos en las columnas del CSV especificadas con los valores esperados.
LLM como juez	Similitud semántica	Utiliza un modelo de lenguaje para puntuar cómo de bien coincide la salida del agente con la salida esperada en significado e intención.
LLM como juez	Precisión del contexto	Puntua la relevancia del contexto recuperado o anclado para la consulta del usuario.
LLM como juez	Fidelidad	Puntua si las afirmaciones en la salida del agente se basan en el contexto proporcionado.
Trayectoria	Trayectoria	Utiliza un modelo de lenguaje para juzgar el comportamiento general del agente en función de su historial de ejecución y el comportamiento esperado.

• Los evaluadores deterministas utilizan coincidencia predefinida basada en reglas y siempre producen resultados coherentes para las mismas entradas. No dependen de ningún modelo de lenguaje.
• Los evaluadores de tipo LLM como juez utilizan un modelo de lenguaje para evaluar el significado, la contextualización o la relevancia y pueden tolerar una variación razonable en el lenguaje.
• Los evaluadores de trayectoria utilizan un modelo de lenguaje para evaluar el comportamiento del agente a lo largo de toda la ejecución, incluidos los pasos intermedios y el uso de herramientas.

Los evaluadores deterministas no incluyen ningún campo de selección de Modelo porque no hacen uso de LLM. LLM como juez y los evaluadores de Trayectoria te permiten elegir el modelo que se utilizará para la evaluación.

Elegir el tipo de evaluador

Si no estás seguro de qué tipo de evaluador se adapta mejor a tu caso de uso, utiliza la siguiente guía para seleccionar la opción más adecuada en función del tipo de salida que estás validando y el nivel de flexibilidad que necesitas.

• LLM-como-juez (similitud semántica, fidelidad, precisión de contexto):
  • Recomendado como enfoque predeterminado cuando se orienta a la salida raíz.
  • Proporciona evaluación flexible de salidas complejas.
  • Puede evaluar la calidad y la corrección más allá de la coincidencia exacta.
  • Se recomienda usarlo al evaluar el razonamiento, las respuestas de lenguaje natural o los resultados estructurados complejos.
• Determinista (coincidencia exacta, similitud de JSON, coincidencia exacta de columna CSV):
  • Recomendado cuando se esperan coincidencias exactas.
  • Más eficaz cuando los requisitos de salida están definidos de forma estricta.
  • Funciona con objetos complejos, pero es mejor usarlo con:
    • Respuestas booleanas (verdadero/falso)
    • Valores numéricos específicos
    • Coincidencias exactas de las cadenas
    • Matrices de primitivas.
• Trayectoria:
  • Recomendado cuando necesitas evaluar el comportamiento general del agente en lugar de solo su salida final.

Definir evaluadores

Utiliza el panel Evaluadores para crear y gestionar tus evaluadores. De forma predeterminada, cada agente tiene un Evaluador predeterminado basado en LLM.

Para crear tus propios evaluadores:

1. Desde tu proyecto de agente, selecciona Evaluadores.
2. Selecciona Crear nuevo:
3. Elige tu tipo de evaluador preferido y selecciona Continuar.
4. Configura el evaluador:
   1. Proporciona un nombre y una descripción relevantes.
   2. (solo evaluadores basados en LLM y de trayectoria) Selecciona el Modelo que utilizarás para la evaluación.
   3. Selecciona los Campos de salida de destino:
      • Segmentación en el nivel de raíz (Todos): evalúa toda la salida.
      • Segmentación específica de campo: evalúa los campos de salida específicos de primer nivel. Los campos disponibles se heredan de los argumentos de salida definidos en la solicitud del sistema. c. Añade una solicitud (obligatoria para los evaluadores basados en LLM y de trayectoria) que defina cómo debe puntuar el evaluador la salida.

Configurar simulaciones en evaluaciones

Nota:

Esta característica está disponible en vista previa.

Las simulaciones mejoran las evaluaciones de agentes al permitir pruebas seguras, rápidas y rentables a través de herramientas y comportamientos de escalada simulados en lugar de puntos finales reales. Ofrecen un control granular en el nivel de evaluación, lo que permite a los equipos definir qué componentes simular y combinar ejecuciones reales y simuladas dentro del mismo conjunto de evaluación. Esta flexibilidad admite entradas fijas o generadas y tanto la salida literal como la clasificación basada en el comportamiento, mejorando la cobertura de la prueba, la reproducibilidad y la capacidad de evaluar si los agentes se comportan como se espera.

Para obtener más información, consulta Configurar simulaciones para herramientas de agente.

Cómo configurar simulaciones de evaluación

Para configurar nuevos conjuntos de evaluación utilizando simulaciones, sigue estos pasos:

1. En la pestaña Conjuntos de evaluación, selecciona Crear y luego Generar nuevo conjunto de evaluación.
2. Introduce una descripción de los casos de evaluación que quieres generar. Puedes proporcionar contexto de alto nivel, escenarios específicos o pegar contenido relevante para guiar la generación. Si dejas este campo en blanco, los casos de evaluación se siguen generando automáticamente para ti.
3. Selecciona Generar evaluaciones. Autopilot genera varias evaluaciones. Para cada evaluación, puedes ver y editar las instrucciones de simulación, las instrucciones de generación de entradas y las notas de comportamiento esperado.
4. Selecciona qué evaluaciones quieres utilizar y luego Añadir conjunto.

Para configurar simulaciones para evaluaciones existentes, sigue estos pasos:

1. Abre cualquier conjunto de evaluación y selecciona Editar en cualquier evaluación. Se muestra el panel Editar evaluación.
2. En la sección Organizar, define o genera datos de entrada utilizando valores manuales o instrucciones de generación de runtime. Si defines los datos de entrada manualmente, puedes establecer el campo Pruebas en Verdadero para indicar que forma parte de un escenario de prueba.
3. En la sección Acto, elige si cada herramienta debe simular comportamiento o ejecutar llamadas reales y añade instrucciones de simulación. La ejecución de herramientas es la configuración predeterminada.
4. En la sección Afirmar, especifica si la evaluación se basa en la coincidencia de salida o en la trayectoria del agente, y describe el comportamiento y el resultado esperados.
5. Selecciona Guardar para aplicar tu configuración.

Figura 1. Configurar simulaciones de herramientas en evaluaciones

Optimizing your agent through evaluations

Use the Optimize feature to improve the reliability and performance of your agents by automatically analyzing your evaluation sets and proposing targeted updates to your agent definition.

Optimize:

• Interprets your agent definition (for example, system prompt and behavioral instructions) together with evaluation results.
• Runs multiple evaluation passes to identify areas for improvement.
• Generates recommended prompt-level modifications aimed at improving evaluator scores.
• Shows you a projected score comparison before you apply any changes.
• Surfaces recommended modifications you can apply immediately to strengthen agent behavior.
• Provides full visibility into how recommendations were produced through an optimization trace.

Before using Optimize:

• Your agent must have at least one completed evaluation run.
• The evaluation set must show results (scores) for one or more evaluators.

Start an optimization run

1. Run evaluations for your agent.

2. Go to Evaluations → Evaluation sets.

3. Select a set with completed results, and select Optimize.

4. In the Optimize window, set the number of passes. Passes controls how many times the Optimize service reviews your agent and evaluation results. Each pass reruns the analysis, refining the recommendations. Choosing a higher number (up to 10) can yield more precise improvements, but it also increases processing time.

5. Select Start Optimize. The optimization runs asynchronously. You can close the dialog and return later while the process continues.

   

Track optimization progress

While Optimize is running, you can open the Optimization trace to monitor progress. The optimization trace shows:

• Each optimization pass and evaluation step.
• Individual LLM calls used during analysis.
• Token usage, execution time, and status for each step.
• The agent output and evaluator assertions used to derive recommendations.

This trace is useful for understanding how Optimize reached its conclusions and for debugging unexpected results.

Review suggested changes

When Optimize completes, return to the evaluation set and select Review suggestions. In the Review suggestions view:

• You see a before and after comparison of your agent’s system prompt.
• Changes are highlighted inline so you can easily identify what was added, removed, or refined.
• A projected evaluator score improvement is shown at the top, indicating the expected impact if the changes are applied.
• A unified diff toggle lets you switch between inline and diff-style views.

For each suggestion, you can:

• Accept to apply the proposed changes directly to your agent definition.
• Reject to discard the suggestion and keep your current prompt.

Limitaciones conocidas

The Optimize feature:

• Is available only for autonomous agents
• Is less effective when simulated tool calls are used
• Runs asynchronously and may take some time to complete

Probar la configuración del modelo dentro de evaluaciones

Puedes utilizar conjuntos de evaluación para comparar diferentes configuraciones de modelos y comprender cómo afectan al comportamiento de tu agente. Las evaluaciones te permiten probar varias combinaciones de modelo/temperatura una al lado de otra, con los mismos escenarios y salidas esperadas. Esto te ayuda a identificar la configuración que ofrece el equilibrio adecuado entre precisión, velocidad y coste.

1. Desde el panel Explorador de Agent Builder, selecciona Conjuntos de evaluación.

2. Selecciona un conjunto de evaluación.

3. Selecciona el icono del engranaje para abrir Configuración de evaluación.

4. En el panel Propiedades del conjunto de evaluación, añade varias combinaciones de temperatura y modelo. Por ejemplo:

   • Temperatura 0,2, modelo A
   • Temperatura 0,5, modelo A
   • Temperatura 0,7, modelo A
   • Temperatura 0,5, modelo B

   Cada configuración crea una ejecución de evaluación independiente.

   

5. Selecciona Evaluar conjuntos para ejecutar todas las configuraciones. Después de que se completen las ejecuciones, abre la pestaña Resultados para compararlas.

   

Para obtener más detalles, consulta Elegir el mejor modelo para tu agente.

Definir evaluaciones con entradas de archivo

Las evaluaciones de agente admiten entradas basadas en archivos. Si tu agente espera un argumento file, la IU de evaluación renderiza un selector de archivo dedicado, lo que te permite cargar o reutilizar archivos para realizar pruebas.

Para utilizar archivos en evaluaciones:

1. Abre el agente y ve a Conjuntos de evaluación.
2. Crea una nueva evaluación o edita una existente.
3. En el panel Configuración de entrada, localiza el campo entrada de archivo.
4. Carga un nuevo archivo o selecciona uno de los archivos de evaluación disponibles.
5. Guarda la evaluación y ejecuta el conjunto de evaluación.

El archivo seleccionado se pasa al agente de la misma manera que una entrada de archivo de runtime, lo que garantiza un comportamiento consistente entre las evaluaciones y las ejecuciones de producción.

Trabajar con evaluaciones

Dónde trabajar con las evaluaciones

Puedes trabajar con evaluaciones en dos lugares, dependiendo de tu flujo de trabajo:

• Panel inferior en el lienzo de diseño: proporciona acceso rápido a las evaluaciones mientras creas o pruebas activamente tu agente. El panel incluye:

  • Pestaña Historial para ver ejecuciones anteriores con seguimientos completos y añadirlas directamente a los conjuntos de evaluación.
  • Pestaña Evaluaciones para ver tus conjuntos de evaluación, revisar las puntuaciones recientes, profundizar en los detalles o volver a ejecutar pruebas individualmente o como un conjunto completo. También puedes comparar las salidas reales con las esperadas y actualizar las evaluaciones con la salida real cuando sea correcta.
  • Pestaña Seguimiento de ejecución para consultar los detalles de seguimiento de la ejecución actual en tiempo real. Para los agentes conversacionales, esta pestaña está disponible como Chat y ofrece una ventana de chat interactiva para probar el agente a la vez que muestra la ruta de ejecución para cada intercambio conversacional.

• Pestaña Evaluaciones en la definición del agente: proporciona el espacio de trabajo de evaluación completo. Desde aquí puedes crear y organizar conjuntos de evaluación, asignar evaluadores, configurar entradas y salidas esperadas, y ejecutar evaluaciones a escala. Este es el mejor lugar para configurar escenarios de evaluación estructurados y gestionar los activos de evaluación a lo largo del tiempo.

El uso del panel inferior ayuda durante la iteración y la depuración diarias, mientras que la pestaña Evaluaciones dedicada es más adecuada para la gestión y configuración completo del conjunto de evaluación.

Estructurar tu solicitud de evaluación

Una salida bien estructurada hace que las evaluaciones sean más fiables. Por eso es bueno tener salidas estructuradas: garantiza la coherencia y facilita las comparaciones.

Este es un ejemplo de una solicitud predefinida que evalúa toda la salida:

Ejemplo de solicitud

Como evaluador experto, analiza la similitud semántica de estos contenidos JSON para determinar una puntuación de 0 a 100. Céntrate en comparar el significado y la equivalencia contextual de los campos correspondientes, teniendo en cuenta expresiones válidas alternativas, sinónimos y variaciones razonables en el lenguaje para mantener altos estándares de precisión e integridad.Justifica tu puntuación, explicando de forma breve y concisa por qué has otorgado esa puntuación.

Expected Output: {{ExpectedOutput}}

ActualOutput: {{ActualOutput}}

Número de evaluaciones

La Puntuación de agente tiene en cuenta más de 30 evaluaciones como un buen punto de referencia.

Para agentes simples, procura realizar aproximadamente 30 evaluaciones en entre 1 y 3 conjuntos de evaluación.Para agentes más complejos, te recomendamos que cuentes al menos con el doble de esa cantidad o más.

El número de evaluaciones depende de:

• Complejidad del agente
  • Número de parámetros de entrada
  • Complejidad de la estructura de salida
  • Patrones de uso de herramientas
  • Ramas de decisión.
• Entrada
  • Rango de posibles entradas: tipos de datos, rangos de valores, campos opcionales
  • Casos límite
• Patrones de uso
  • Casos de uso comunes
  • Distintas personalidades
  • Escenarios de error

Conjuntos de evaluación

Agrupar evaluaciones en conjuntos ayuda a organizarlas mejor. Por ejemplo, puedes tener:

• Un conjunto para una evaluación completa de salida.
• Otro para casos límite
• Otro para manejar errores ortográficos.

Principios de cobertura

• Cobertura lógica: asigna combinaciones de entrada, casos límite y condiciones de límite.
• Gestión de redundancias: procura realizar entre 3 y 5 evaluaciones diferentes por caso lógicamente equivalente.
• Calidad sobre cantidad: más evaluaciones no siempre significan mejores resultados. Concéntrate en pruebas significativas.

Cuándo crear evaluaciones

Crea evaluaciones una vez que los argumentos sean estables o completos. Eso también significa que tu caso de uso se ha establecido y la solicitud, las herramientas y los contextos están finalizados. Si modificas los argumentos, debes ajustar tus evaluaciones en consecuencia. Para minimizar el trabajo adicional, es mejor empezar con agentes estables que tengan casos de uso bien definidos. Puedes exportar e importar conjuntos de evaluación entre agentes dentro de la misma organización o entre diferentes organizaciones.Mientras el diseño de tu agente esté completo, puedes mover las evaluaciones según sea necesario sin tener que volver a crearlas desde cero.