Evals

Las evaluaciones (evals) te ayudan a realizar un seguimiento de cómo cambia el comportamiento de tu agente a lo largo del tiempo. Cuando guardas una conversación como una evaluación, puedes reproducirla más tarde para ver si el agente responde de manera diferente. Las evaluaciones miden la consistencia, no la corrección: te indican si el comportamiento cambió, no si es correcto o incorrecto.

¿Qué son las evaluaciones?

Una evaluación (eval) es una conversación guardada que puedes reproducir. Al ejecutar evaluaciones, Docker Agent reproduce los mensajes del usuario y compara las nuevas respuestas con la conversación guardada original. Puntuaciones altas significan que el agente se comportó de manera similar; puntuaciones bajas indican que el comportamiento cambió.

Lo que hagas con esa información dependerá de por qué guardaste la conversación. Puedes guardar conversaciones exitosas para detectar regresiones, o guardar casos de falla para documentar problemas conocidos y realizar un seguimiento de su mejora.

Flujos de trabajo comunes

La forma en que utilizas las evaluaciones depende de lo que intentes lograr:

Pruebas de regresión: Guarda conversaciones en las que tu agente funcione bien. Cuando realices cambios más adelante (actualizar modelos, actualizar prompts, refactorizar código), ejecuta las evaluaciones. Las puntuaciones altas significan que el comportamiento se mantuvo consistente, lo cual suele ser lo que deseas. Las puntuaciones bajas significan que algo cambió; examina el nuevo comportamiento para ver si sigue siendo correcto.

Seguimiento de mejoras: Guarda conversaciones donde tu agente tenga dificultades o falle. A medida que realices mejoras, ejecuta estas evaluaciones para ver cómo evoluciona el comportamiento. Las puntuaciones bajas indican que el agente ahora se comporta de manera diferente, lo que podría significar que has solucionado el problema. Deberás verificar manualmente si el nuevo comportamiento es realmente mejor.

Documentar casos límite (edge cases): Guarda conversaciones interesantes o inusuales independientemente de su calidad. Utilízalas para comprender cómo maneja tu agente los casos límite y si ese comportamiento cambia con el tiempo.

Las evaluaciones miden si el comportamiento cambió. Tú determinas si ese cambio es bueno o malo.

Crear una evaluación

Guarda una conversación de una sesión interactiva:

$ docker agent run ./agent.yaml

Mantén una conversación con tu agente y luego guárdala como una evaluación:

> /eval nombre-caso-prueba
Eval saved to evals/nombre-caso-prueba.json

La conversación se guarda en el directorio evals/ de tu directorio de trabajo actual. Puedes organizar los archivos de evaluación en subdirectorios si es necesario.

Ejecutar evaluaciones

Ejecuta todas las evaluaciones en el directorio por defecto:

$ docker agent eval ./agent.yaml

Usa un directorio de evaluación personalizado:

$ docker agent eval ./agent.yaml ./mis-evals

Ejecuta evaluaciones contra un agente de un registro:

$ docker agent eval agentcatalog/myagent

Ejemplo de salida:

$ docker agent eval ./agent.yaml
--- 0
First message: tell me something interesting about kil
Eval file: c7e556c5-dae5-4898-a38c-73cc8e0e6abe
Tool trajectory score: 1.000000
Rouge-1 score: 0.447368
Cost: 0.00
Output tokens: 177

Comprender los resultados

Para cada evaluación, Docker Agent muestra:

• First message (Primer mensaje): El mensaje inicial del usuario de la conversación guardada.
• Eval file (Archivo de evaluación): El UUID del archivo de evaluación que se está ejecutando.
• Tool trajectory score (Puntuación de trayectoria de herramientas): Qué tan similar fue el uso de herramientas por parte del agente (escala 0-1, cuanto mayor sea, mejor).
• ROUGE-1 score (Puntuación ROUGE-1): Similitud de texto entre las respuestas (escala 0-1, cuanto mayor sea, mejor).
• Cost (Costo): El costo de la ejecución de esta evaluación.
• Output tokens (Tokens de salida): Número de tokens generados.

Las puntuaciones más altas significan que el agente se comportó de manera más similar a la conversación original grabada. Una puntuación de 1.0 significa un comportamiento idéntico.

Qué significan las puntuaciones

La puntuación de trayectoria de herramientas (Tool trajectory score) mide si el agente llamó a las mismas herramientas en el mismo orden que en la conversación original. Las puntuaciones más bajas pueden indicar que el agente encontró un enfoque diferente para resolver el problema, lo cual no es necesariamente incorrecto pero vale la pena investigar.

La puntuación ROUGE-1 mide qué tan similar es el texto de respuesta al original. Esta es una medida heurística: una redacción diferente aún puede ser correcta, por lo que debes usar esto como una señal más que como una verdad absoluta.

Interpretar tus resultados

Las puntuaciones cercanas a 1.0 significan que tus cambios mantuvieron un comportamiento consistente: el agente está utilizando el mismo enfoque y produciendo respuestas similares. Esto generalmente es bueno; tus cambios no rompieron la funcionalidad existente.

Las puntuaciones más bajas significan que el comportamiento cambió en comparación con la conversación guardada. Esto podría ser una regresión donde el agente ahora funciona peor, o podría ser una mejora donde el agente encontró un enfoque mejor.

Cuando las puntuaciones bajen, examina el comportamiento real para determinar si es mejor o peor. Los archivos de evaluación se almacenan como JSON en tu directorio de evaluaciones: abre el archivo para ver la conversación original. Luego, prueba tu agente modificado con la misma entrada para comparar las respuestas. Si la nueva respuesta es mejor, guarda una nueva conversación para reemplazar la evaluación. Si es peor, habrás encontrado una regresión.

Las puntuaciones te guían hacia lo que cambió. Tu criterio determina si el cambio es bueno o malo.

Cuándo usar las evaluaciones

Las evaluaciones te ayudan a rastrear los cambios de comportamiento a lo largo del tiempo. Son útiles para detectar regresiones al actualizar modelos o dependencias, documentar casos de falla conocidos que deseas solucionar y comprender cómo evolucionan los casos límite a medida que iteras.

Las evaluaciones no son adecuadas para determinar qué configuración de agente funciona mejor; miden la similitud con una conversación guardada, no la corrección. Utiliza pruebas manuales para evaluar diferentes configuraciones y decidir cuál funciona mejor.

Guarda las conversaciones que valga la pena rastrear. Crea una colección de flujos de trabajo importantes, casos límite interesantes y problemas conocidos. Ejecuta tus evaluaciones al realizar cambios para ver qué ha variado.

¿Qué sigue?

• Consulta la referencia de CLI para conocer todas las opciones de docker agent eval
• Aprende las mejores prácticas para crear agentes eficaces
• Revisa las configuraciones de ejemplo para diferentes tipos de agentes