getedgehq/agent-evals

Evaluaciones de agente

Una evaluación responde una pregunta: ¿el agente realizó el trabajo correctamente? Todo lo que sigue es una forma de hacer esa pregunta de manera más confiable, más barata y con mayor frecuencia.

Construido a partir de la masterclass sobre evaluaciones de Alex Lieberman con Viv (LangChain), 2026: youtube.com/watch?v=zLeG-XJtbIE. La estructura (fácil, difícil, modo dios) es de ellos. Los errores en esta skill son nuestros.

Comienza preguntando al usuario tres cosas

1. ¿Qué trabajo real hace el agente? Nombra el sistema al que accede (CRM, bandeja de entrada, repositorio, base de datos).
2. ¿Quién en la empresa es el mejor en ese trabajo hoy? Su criterio es la verdad fundamental.
3. ¿El agente ya se ejecuta en producción? Si es así, ¿se almacenan trazas en algún lugar?

Elige el modo a partir de las respuestas. No saltes al modo dios sin tareas y verificadores.

Modo fácil: tareas y verificadores

Una tarea es una pieza pequeña y verificable del trabajo real. Un verificador determina si esa tarea se realizó correctamente.

1. Escribe de 10 a 30 tareas que imiten lo que hacen los colegas reales. Ejemplos para un agente de ventas:
   • agregar una nota a un registro de CRM después de una llamada
   • encontrar un prospecto que no está en la tabla obvia
   • redactar un correo de respuesta sin enviarlo
2. Para cada tarea, escribe el verificador. Prefiere, en orden:
   • Verificación de estado (un script): el campo estaba vacío antes y contiene el valor correcto después; la etiqueta email_sent existe.
   • Lista de verificación (un modelo o un humano): para cualquier cosa que no sea directamente verificable, divide "bueno" en preguntas de sí/no. "¿Tiene tres párrafos o menos?" "¿Usa las reglas de tono de la marca?"
3. Mantén cada juicio binario. Los modelos a los que se pide una puntuación del 1 al 10 se agrupan alrededor de 7 y se andan con rodeos. Sí/no no puede andarse con rodeos.
4. Obtén la lista de verificación de la mejor persona en el trabajo, por escrito. Ejecuta el agente, revisa una muestra manualmente. Si un resultado pasa la lista de verificación pero aún se siente incorrecto, la lista está incompleta. Agrega la pregunta faltante.

Resultado del modo fácil: una carpeta de tareas, cada una con una instrucción y un verificador, y una tasa de aprobación.

Modo difícil: entornos

Un entorno es donde el agente realiza el trabajo: sus archivos, herramientas, datos y permisos. Nunca evalúes contra datos de producción. Un agente que falla la evaluación también modifica el CRM real.

1. Construye una copia que parezca real para el agente: mismas tablas, mismas herramientas, registros falsos. Empaquétalo para que se reinicie al mismo estado en cada ejecución (un contenedor es la elección habitual).
2. Una tarea = instrucción + entorno + verificador. Almacénalos juntos.
3. No crees tu propio ejecutor si puedes evitarlo. Harbor (github.com/harbor-framework/harbor) tiene formatos compartidos para tareas, entornos y verificadores, y muchas tareas publicadas que puedes adaptar.
4. Prueba el entorno en sí mismo. Tu primer entorno estará mal. Ejecuta varios agentes o modelos diferentes a través de él y busca patrones extraños:
   • un modelo fuerte falla donde uno débil pasa
   • un agente encuentra la respuesta en un lugar donde no debería estar (una fila de marcador de posición, un archivo filtrado). Los agentes tomarán cualquier atajo para aprobar. Elimina la filtración.
5. Etiqueta cada tarea por familia (codificación, ventas, revisión de código). Cuando llegue un nuevo modelo, ejecuta solo las familias en las que podría ser bueno.
6. Elige modelos con una tabla, no con una sensación. Ejecuta cada candidato en las mismas tareas etiquetadas. Registra la tasa de aprobación, el costo y la velocidad uno al lado del otro. Luego un humano decide: ¿vale la pena 5 puntos de precisión por 3 veces el costo para esta familia? Las tareas orientadas al usuario generalmente justifican el mejor modelo; las internas a menudo no.

Resultado del modo difícil: un conjunto de evaluación que puedes volver a ejecutar en cualquier modelo con un solo comando, con una tabla de resultados por familia de tareas.

Modo dios: el bucle de mejora

El bucle: el agente se ejecuta, produce trazas, los fallos se convierten en nuevas tareas, el agente se corrige, repetir.

1. Activa el rastreo. Una traza es el registro de cada acción: cada llamada a herramienta, cada mensaje, cada resultado. Nadie puede predecir lo que hará un agente. Todos pueden juzgar lo que hizo.
2. Almacena las trazas en un solo lugar. Para un solo desarrollador, los registros del propio agente en el disco son suficientes. Para un equipo, usa un producto de rastreo con permisos.
3. Apunta un segundo agente a las trazas. Su único trabajo es encontrar patrones. Dale un breve resumen del comportamiento bueno y malo. Pídele:
   • llamadas a herramientas fallidas o repetidas
   • instrucciones que ignoró o siguió a medias
   • un camino incorrecto recurrente (siempre buscando en la tabla equivocada, haciendo una empresa cuando se le pidieron tres)
4. Convierte cada fallo confirmado en una tarea en el conjunto de evaluación, para que nunca pueda regresar silenciosamente.
5. Corrige el agente, comenzando por la palanca más barata:
   • arnés: prompt, descripciones de herramientas, conjunto de herramientas, elección de modelo
   • ajuste fino de un modelo abierto pequeño en la tarea específica, una vez que el conjunto demuestre que coincide con el modelo grande
6. Mantén a un humano en la definición de lo que es "bueno". Los agentes pueden proponer correcciones y redactar tareas. Un humano aún decide qué tareas son importantes para el negocio y revisa las nuevas. Escribir eso es la parte de mayor apalancamiento del bucle.

Reglas

• Sin evaluación sin un trabajo real nombrado. Los benchmarks genéricos no te dicen si tu agente funciona.
• Solo verificadores binarios. Divide cualquier puntuación en preguntas de sí/no.
• Nunca permitas que una evaluación toque datos de producción.
• Un conjunto que todo lo aprueba es un conjunto roto. Verifica si hay filtraciones.
• Informa las tasas de aprobación con el número de tareas al lado ("21 de 30"), nunca un porcentaje simple.