Evals para coding agents: cómo saber si tu agente mejora o sólo tuvo suerte

El agente resolvió el ticket, los tests quedaron verdes y la demo salió bien. ¿Mejoró?

Todavía no lo sabes.

Una ejecución exitosa puede ser capacidad real, una semilla afortunada, contexto filtrado desde un intento anterior o un grader que acepta una solución incompleta. Con agentes de código, “funcionó una vez” es una anécdota; una evaluación reproducible es evidencia.

La distinción importa porque un coding agent no sólo responde texto. Lee un repositorio, decide qué archivos tocar, llama herramientas, modifica estado, interpreta errores y vuelve a intentar. Evaluarlo como si fuera una función prompt → respuesta deja fuera casi todo lo que puede fallar.

Anthropic formalizó este problema en Demystifying evals for AI agents. OpenAI añadió una advertencia incómoda en Separating signal from noise in coding evaluations: hasta el benchmark puede estar roto. Esta guía traduce ambas investigaciones a un sistema pequeño que un equipo de software pueda ejecutar desde hoy.

Test y eval no son sinónimos

Un test convencional pregunta si un artefacto se comporta como esperamos:

código + entrada → salida verificable

Una eval de un agente pregunta si el sistema completo puede producir ese artefacto bajo condiciones controladas:

modelo + instrucciones + herramientas + repositorio + tiempo
  → trayectoria de decisiones
  → estado final
  → evidencia

Los tests siguen siendo esenciales. De hecho, suelen ser el grader determinista más valioso. Pero una suite de tests no mide por sí sola si el agente entendió el alcance, introdujo deuda innecesaria, expuso un secreto, consumió diez veces más tokens o acierta de forma consistente.

Pregunta	Test de software	Eval de coding agent
¿Qué observa?	El comportamiento del código	La conducta del agente y el resultado
¿Qué se ejecuta?	Una implementación	Modelo, scaffold, herramientas y entorno
¿Cuántas veces?	Normalmente una por cambio	Varios intentos independientes
¿Qué produce?	Pass/fail	Distribución, calidad, costo y trayectoria
¿Qué protege?	El producto	El producto y el sistema que lo modifica

La anatomía mínima de una eval útil

Antes de elegir plataforma o dashboard, conviene fijar el vocabulario:

• Task o caso: entrada, contexto y criterios de éxito de un trabajo.
• Trial o intento: una ejecución independiente de ese caso.
• Transcript, trace o trajectory: registro de mensajes, herramientas, decisiones y resultados intermedios.
• Outcome: estado final verificable del sistema.
• Grader: lógica que asigna una puntuación a una dimensión.
• Eval harness: infraestructura que prepara el entorno, ejecuta, registra, califica y agrega.
• Agent harness o scaffold: modelo más el software que le permite actuar.
• Suite: colección versionada de casos que mide una capacidad o una regresión.

El outcome merece especial atención. Si el agente dice “la migración quedó aplicada”, el grader no debe puntuar la frase: debe consultar la base de datos. Si asegura que corrigió la vulnerabilidad, hay que ejecutar los casos adversariales. Mide el estado, no la autodescripción del agente.

También conviene medir el resultado antes que imponer un camino exacto. Bloquear una secuencia rígida de tool calls puede penalizar soluciones válidas que el diseñador no imaginó. La trayectoria es excelente para diagnosticar y detectar conductas prohibidas; el outcome suele ser mejor para decidir si el trabajo quedó hecho.

Un acierto no mide confiabilidad

Los agentes son no deterministas. El mismo caso puede pasar hoy y fallar dentro de un minuto sin que cambie el código. Por eso cada tarea necesita varios trials aislados.

Dos métricas responden preguntas distintas:

• pass@k: probabilidad de obtener al menos una solución correcta en k intentos. Sirve cuando podemos generar varias opciones y elegir una.
• pass^k: probabilidad de que los k intentos sean correctos. Sirve cuando cada usuario espera un resultado fiable.

Con una probabilidad de éxito por intento de 0.75, tres ejecuciones tienen aproximadamente un 98.4% de probabilidad de incluir al menos un acierto, pero sólo un 42.2% de que las tres salgan bien.

pass@3 = 1 - (1 - 0.75)³ = 98.4%
pass^3 = 0.75³           = 42.2%

La primera cifra vende una demo estupenda. La segunda describe mejor un agente que modifica producción sin supervisión.

No publiques sólo un promedio. Por caso y por versión del agente registra al menos:

• tasa de éxito y número de trials;
• score por cada grader;
• latencia, tokens, costo y turnos;
• errores de infraestructura separados de errores del agente;
• modelo, configuración, commit y versión de la suite;
• enlace al transcript y al diff producido.

Sin denominador, intervalo y configuración, “subimos de 74 a 79” es decoración.

Capacidad y regresión necesitan reglas distintas

Una suite de capacidad pregunta: “¿qué puede hacer ahora?”. Debe incluir problemas difíciles y espacio para mejorar. Si todos pasan, dejó de medir progreso.

Una suite de regresión pregunta: “¿sigue haciendo de forma confiable lo que ya sabía?”. Sus casos deberían acercarse al 100% y pueden bloquear un despliegue.

Suite	Pass rate saludable	Función	Acción ante fallo
Capacidad	Bajo o medio al inicio	Encontrar la siguiente frontera	Investigar y experimentar
Regresión	Cercano a 100%	Evitar retrocesos conocidos	Bloquear o escalar

Cuando un caso de capacidad se vuelve estable, se gradúa a regresión. Cuando producción revela un fallo importante, éste se convierte en un nuevo caso de regresión. Así la suite crece desde experiencia real y no desde escenarios inventados para hacer lucir bien al modelo.

Construye graders en capas

No necesitas empezar con un LLM juzgando a otro LLM. La jerarquía más sana es:

1. Deterministas siempre que sea posible

• tests que pasan y tests existentes que no regresan;
• type checking, lint y build;
• contratos de API y schemas;
• estado de base de datos o filesystem;
• análisis estático, secretos y dependencias;
• límites de archivos, permisos y comandos;
• métricas del transcript: turnos, herramientas, tokens.

Son rápidos, baratos, reproducibles y fáciles de depurar. Su debilidad es la rigidez: un assert demasiado específico puede rechazar una solución correcta.

2. Graders de modelo donde exista semántica

Úsalos para criterios como:

• ¿el cambio cumple la intención completa?
• ¿la explicación es honesta sobre sus límites?
• ¿el diseño encaja con las convenciones del repositorio?
• ¿el agente hizo sobreingeniería?

Cada dimensión debe tener una rúbrica separada, evidencia disponible y salida estructurada. Incluye la opción unknown cuando falte información. Después calibra ese juez contra especialistas humanos; no asumas que “LLM-as-judge” equivale a verdad.

3. Personas para calibrar y decidir riesgo

La revisión humana sigue siendo la referencia para seguridad, arquitectura, cumplimiento y calidad subjetiva. No necesita puntuar cada trial. Puede:

• revisar una muestra semanal de transcripts;
• resolver desacuerdos entre graders;
• auditar falsos positivos y negativos;
• recalibrar rúbricas;
• aprobar cambios en tareas críticas.

La combinación es más fuerte que cualquiera de las capas por separado.

El caso debe ser justo antes de ser difícil

Una eval mala produce precisión falsa. Un caso confiable cumple estas condiciones:

1. Dos expertos llegarían al mismo veredicto.
2. Todo lo que el grader exige aparece en la tarea o en el repositorio.
3. Existe una solución de referencia que pasa.
4. El entorno puede reconstruirse de forma limpia.
5. Las pruebas validan comportamiento, no una implementación accidental.
6. Hay casos positivos y negativos.
7. El agente no puede aprobar alterando el grader.

OpenAI auditó SWE-Bench Pro en julio de 2026 y estimó que cerca del 30% de sus tareas estaban rotas. Encontró prompts ambiguos o contradictorios, tests demasiado estrictos y cobertura insuficiente. La organización terminó retirando su recomendación anterior de usar ese benchmark.

La lección no es “ignora los benchmarks”. Es más exigente: la calidad del dataset y del grader forma parte del producto que estás evaluando.

Cuando un modelo fuerte obtiene 0% después de muchos intentos, revisa primero si el caso es resoluble. Cuando el score salta de forma sorprendente, comprueba que el agente no descubrió un atajo. Cuando una tarea falla, lee la trayectoria antes de tocar el prompt.

Aislamiento: evita que los intentos se contaminen

Cada trial debe comenzar desde el mismo estado:

• checkout o contenedor nuevo;
• dependencias y fixtures versionados;
• reloj, red y servicios externos controlados;
• secretos falsos y permisos mínimos;
• caché, memoria e historial limpios;
• límites constantes de tiempo y presupuesto.

El estado compartido puede deprimir el resultado por agotamiento de recursos o inflarlo porque el siguiente agente lee artefactos del intento anterior. Si los trials no son independientes, las matemáticas de confiabilidad dejan de describir lo que crees.

Del bug real al caso evaluable

Un ticket no se convierte en eval copiando su título. Haz esta transformación:

id: auth-empty-password
type: regression
risk: critical
setup:
  repo: app@known-commit
  fixture: vulnerable-auth
task: >
  Corrige el bypass que acepta password vacío.
  Conserva el contrato público y no cambies el algoritmo de hashing.
success:
  - empty_password_test == pass
  - null_password_test == pass
  - existing_auth_suite == pass
  - security_scan.high == 0
  - public_api_diff == empty
trials: 3

Después añade:

• una solución de referencia;
• el conjunto de graders y sus pesos;
• criterios obligatorios que no admiten compensación;
• presupuesto de tiempo y costo;
• datos que deben persistirse para depuración.

Da crédito parcial cuando la tarea tenga componentes independientes, pero no permitas que un buen estilo compense una vulnerabilidad abierta. En tareas críticas hay condiciones obligatorias.

Starter Kit ejecutable

Publicamos un Starter Kit de evals para coding agents con:

• contrato de suite y tareas;
• resultados de trials de ejemplo;
• scorer en Node.js sin dependencias.

Descarga los tres archivos en una carpeta y ejecuta:

node score.mjs cases.json trials.example.json

El script calcula score ponderado, tasa de éxito, pass@k, pass^k, costo medio y latencia p95. Las tareas de capacidad se reportan sin bloquear; una regresión por debajo del umbral termina con código 1, por lo que puede usarse como gate de CI.

El kit empieza en la capa correcta: agrega evidencia ya producida por tu runner. No finge que ejecutar un agente de forma aislada es universal; cada producto tiene herramientas, sandboxes y credenciales diferentes.

Una implementación gradual que sí cabe en un sprint

Día 1: define la línea base

Elige 10–20 tareas manuales frecuentes y fallos recientes. Sepáralos por capacidad y regresión. Para un agente más maduro, crece hacia los 20–50 casos iniciales recomendados por Anthropic.

Día 2: automatiza outcomes

Convierte acceptance criteria en tests, consultas de estado, build, análisis estático y checks de alcance. Prueba cada grader contra una solución de referencia y una solución deliberadamente mala.

Día 3: captura trials aislados

Ejecuta al menos tres intentos por caso con configuración idéntica. Guarda transcript, diff y métricas. Clasifica errores del entorno aparte.

Día 4: calibra

Dos personas revisan una muestra sin ver el score. Compara sus veredictos con los graders. Ajusta casos ambiguos y rúbricas que no coincidan.

Día 5: conecta el bucle

Fija baseline. Ejecuta la suite al cambiar modelo, prompt, tools, skills o harness. Bloquea sólo regresiones confiables; usa capacidad para orientar experimentos.

Qué debe correr en CI y qué no

Una pirámide práctica:

• Por pull request: regresiones críticas, casos baratos y graders deterministas.
• Por cambio del agente: suite completa con varios trials.
• Programado: capacidad difícil, graders de modelo y análisis de costo.
• Semanal: muestra humana de transcripts, falsos positivos y falsos negativos.
• Después de incidentes: convertir el fallo en caso antes de corregir el harness.

No ejecutes cien trials costosos en cada commit si diez regresiones rápidas ya detectan el problema. Tampoco uses un smoke test barato para aprobar un cambio de modelo completo. La frecuencia debe seguir el riesgo y el costo.

Anti-patrones que hacen mentir a la métrica

• Evaluar sólo el mensaje final. El agente puede afirmar que hizo algo que no existe.
• Compartir el workspace entre trials. Introduce filtración y fallos correlacionados.
• Probar sólo cuándo debe actuar. También mide cuándo debe abstenerse.
• Premiar una ruta exacta. Confunde obediencia coreográfica con corrección.
• Usar sólo tasks fáciles. Una suite saturada ya no mide capacidad.
• Modificar el prompt mirando siempre los mismos casos. Es overfitting al benchmark.
• Ocultar los transcripts. Impide distinguir fallo del agente y fallo del grader.
• Medir calidad sin costo. Una mejora de 2% que multiplica latencia por diez puede ser peor producto.
• Convertir todo en un score único. Seguridad, corrección y costo no siempre son intercambiables.

Mantén un pequeño holdout que no uses para afinar a diario. Versiona cada cambio de tarea o grader. Si cambias la regla, no compares el nuevo número con el histórico como si midieran exactamente lo mismo.

El tablero mínimo para tomar decisiones

Una fila por variante del agente:

Variante	Regresión pass^3	Capacidad pass@3	Costo/tarea	p95 latencia	Fallos de entorno
baseline	96%	58%	$0.72	118 s	1.2%
nuevo prompt	98%	61%	$0.74	121 s	1.0%
nuevo modelo	97%	72%	$1.16	94 s	1.1%

La decisión deja de ser “se siente más inteligente”. Ahora puedes discutir si once puntos de capacidad justifican el costo, si una pérdida de confiabilidad es aceptable y en qué tareas concretas ocurre.

Las evals no sustituyen producción

Un dataset estático nunca contiene toda la realidad. Combina:

• evals automatizadas antes de desplegar;
• observabilidad de errores y outcomes reales;
• A/B tests cuando haya tráfico suficiente;
• feedback de usuarios;
• lectura recurrente de transcripts;
• estudios humanos para decisiones subjetivas o de alto riesgo.

Este es el mismo principio de defensa en profundidad que aparece en el gauntlet para código generado con IA: ningún sensor captura todo.

Una eval útil no entrega certeza absoluta. Entrega una señal suficientemente limpia para comparar, aprender y decidir.

Checklist antes de confiar en el número

• Cada tarea tiene criterios explícitos y una referencia que pasa.
• Los trials comienzan desde entornos limpios e independientes.
• El grader observa el outcome real, no sólo la respuesta del agente.
• Los checks deterministas cubren corrección, regresión y seguridad.
• Los graders semánticos están separados por dimensión y calibrados.
• Hay casos donde el agente debe actuar y donde debe abstenerse.
• Capacidad y regresión usan umbrales diferentes.
• Se guardan configuración, commit, transcript, costo y latencia.
• Una persona lee muestras de éxitos y fallos.
• Los cambios de suite están versionados.
• Los incidentes de producción regresan como casos.
• Existe un holdout contra el overfitting.

Preguntas frecuentes

¿Cuántos casos necesito para empezar?

No cientos. Entre 20 y 50 casos simples extraídos de trabajo y fallos reales pueden dar una primera señal útil; un equipo pequeño puede comenzar con 10–20 y crecer. Si vas a afirmar diferencias pequeñas entre variantes, necesitarás más trials y análisis estadístico.

¿Tres trials son suficientes?

Sirven como detector inicial de inestabilidad, no como estimación precisa. Aumenta k en tareas críticas, resultados muy variables o decisiones costosas.

¿Debo usar un LLM como grader?

Sólo cuando la dimensión requiera semántica. Primero usa tests, estado, schemas y análisis estático. Después calibra el juez de modelo con humanos.

¿Puedo usar un benchmark público para elegir modelo?

Como señal complementaria. Para decidir sobre tu producto necesitas casos de tu distribución, tu repositorio, tus herramientas y tu definición de éxito. Audita además la calidad del benchmark.

¿Qué cambio debe disparar la suite?

Cualquier cambio en modelo, system prompt, AGENTS.md, skill, herramientas, permisos, estrategia de contexto, límites o harness. Estás evaluando el sistema completo, no un nombre de modelo.

Recursos originales

• Demystifying evals for AI agents — Anthropic
• Separating signal from noise in coding evaluations — OpenAI
• Working with evals — OpenAI API
• Agent evals — OpenAI API
• Harness design for long-running application development — Anthropic

La regla final es simple: si no puedes repetirlo, calificarlo y explicar por qué falló, todavía no sabes si el agente mejoró.