Evaluación de agentes de IA: cómo construir evals y medir la fiabilidad, no la sensación

Para qué evaluar un agente de IA si ya se ve que funciona

Precisamente, se ve mal. ¿El agente no se ha atascado ni una vez en la última semana tras cambiar el prompt? ¿Es una reparación o simplemente una semana de tareas fáciles? Un ingeniero está seguro de que la nueva plantilla lo cambió todo, y otro, mirando el mismo registro, no ve diferencia. Ambos tienen razón solo en la medida en que no han contado nada.

La evaluación de agentes de IA (evals) sustituye la sensación por un número. Se toma un conjunto fijo de tareas, se ejecuta el agente, se comprueba el resultado automáticamente y se comparan las métricas antes y después del cambio. Así la discusión «¿ha mejorado?» se resuelve con una tabla y no con la autoridad de alguien.

Sin evals, cualquier cambio en el harness (el prompt, AGENTS.md, el conjunto de herramientas, el modelo) es una apuesta a ciegas. Con evals, es un experimento con un resultado medible.

Por qué la «sensación» engaña

La impresión sobre el trabajo de un agente tiene tres errores sistemáticos, y todos empujan hacia una falsa seguridad.

• Sesgo del superviviente. Las ejecuciones exitosas se recuerdan y se enseñan a los compañeros; las fallidas se relanzan y se olvidan. La fiabilidad calculada solo con las ejecuciones exitosas no dice nada sobre dónde se rompe realmente el agente.
• Muestra pequeña. Tres tareas exitosas seguidas son un suceso normal incluso para un agente que acierta la mitad de las veces. Esa probabilidad es 0,5³ = 12,5%, es decir, aproximadamente una de cada ocho series.
• Tono seguro. El agente escribe «listo, todas las pruebas pasan» con la misma seguridad tanto si es cierto como si no. La confianza del modelo no está calibrada: el tono de la respuesta no es una señal de corrección.

De ahí la regla: todo lo que no está registrado y recalculado se considera no medido.

pass@k y pass^k: dos métricas que se confunden

El agente no es determinista: la misma tarea puede pasar en un intento y fallar en otro. Por eso una tarea se ejecuta varias veces y se calcula una de dos métricas.

pass@k: al menos un intento de k tiene éxito

La métrica procede de la evaluación de generación de código. Responde a la pregunta «¿es capaz el sistema, en principio, de resolver la tarea si se le dan varios intentos?». Es una métrica honesta para un escenario en el que una persona elige la mejor de varias opciones o en el que hay una comprobación automática fiable que descarta las fallidas.

pass^k: los k intentos tienen éxito

Esta métrica responde a otra pregunta: «¿con qué estabilidad resuelve el agente la tarea?». Describe el trabajo sin supervisión, cuando el agente se lanza muchas veces y cada fallo cuesta dinero o tiempo.

La diferencia entre ambas es enorme. Supongamos que el agente resuelve una tarea con probabilidad del 70% en un intento y que los intentos son independientes:

Según pass@5, el agente parece casi perfecto; según pass^5, no es fiable. Ambas cifras son correctas, simplemente describen cosas distintas. Si piensa dejar que el agente trabaje de forma autónoma, mire pass^k: se parece más a lo que verá en el trabajo real.

Cómo calcularlo en la práctica

Ejecute cada tarea n veces (por ejemplo, 5) y anote el número de éxitos c. Para una tarea, pass^k es aproximadamente la proporción de ejecuciones en las que los k intentos salen bien seguidos; de forma más simple, estime la probabilidad de éxito p = c / n y elévela a la potencia k. Para un conjunto de tareas, promedie entre ellas.

import json
from statistics import mean

# results.jsonl: {"task": "add-pagination", "runs": [true, true, false, true, true]}
rows = [json.loads(line) for line in open("results.jsonl")]

def pass_at_k(runs, k):
    p = sum(runs) / len(runs)
    return 1 - (1 - p) ** k

def pass_pow_k(runs, k):
    p = sum(runs) / len(runs)
    return p ** k

for k in (1, 3, 5):
    print(k,
          round(mean(pass_at_k(r["runs"], k) for r in rows), 3),
          round(mean(pass_pow_k(r["runs"], k) for r in rows), 3))

La estimación mediante p elevado a k es grosera con n pequeño, pero para comparar versiones del harness entre sí suele bastar. Lo importante es que n y el conjunto de tareas no cambien entre comparaciones.

Cómo reunir un conjunto de tareas para evals

El conjunto de tareas es el activo principal. Una métrica excelente sobre malas tareas mide otra cosa.

Tome tareas de su propia realidad

Los benchmarks públicos, como SWE-bench, son útiles para comparar modelos, pero sus tareas están seleccionadas: descripción clara y pruebas listas. En su repositorio los requisitos son vagos y a veces faltan las pruebas, así que la cifra del benchmark casi siempre es mayor de lo que el agente mostrará en su caso. La mejor fuente de tareas son los tickets cerrados y los fallos reales del agente registrados en el diario.

Composición del conjunto

• Entre 20 y 50 tareas para empezar. Menos, y el ruido se come la diferencia entre versiones. Más, y la ejecución se encarece y dejará de lanzarse.
• Tipos variados: funcionalidad nueva, corrección de error, refactorización, tarea en un módulo ajeno, tarea con trampa (donde la respuesta correcta es «así no se debe hacer» o «hace falta aclarar algo»).
• Cada tarea que el agente falló en el trabajo se convierte en prueba. Así el conjunto crece con la comprensión de dónde es débil el agente, y las regresiones no pasan desapercibidas.
• Estado inicial fijo: un commit concreto, dependencias bloqueadas, el mismo entorno. Si no, se mide la deriva del entorno y no al agente.

Formato de la tarea

Cada tarea es una descripción, un estado inicial y un criterio de éxito comprobable sin persona.

id: add-pagination
repo_ref: 3f2c1ab
prompt: |
  Añade paginación a GET /payments: parámetros limit (por defecto 20, máximo 100)
  y cursor. La respuesta contiene next_cursor.
check:
  - pytest tests/test_payments_pagination.py
  - mypy app/
limits:
  max_changed_files: 6

Observe que el criterio de éxito es la Definition of Done escrita en forma de comandos. Si no puede escribir un criterio para una tarea, es señal de que también al agente se le asignó de forma ambigua.

Comprobaciones automáticas o juez LLM

El resultado se puede verificar con código o con otro modelo. Cada método tiene su ámbito.

Regla: primero código, el juez encima

Todo lo que se puede comprobar de forma determinista, compruébelo de forma determinista. Añada el juez LLM solo para propiedades que el código no puede expresar, y nunca en lugar de las pruebas.

Cómo hacer útil al juez LLM

• Contexto distinto del generador. El juez no debe ver el razonamiento del agente, solo la tarea, los criterios y el diff final. Si no, repetirá los mismos errores: esto es N-versionado, dos miradas independientes en lugar de una.
• Rúbrica en lugar de «valora del 1 al 10». Preguntas concretas con respuesta sí/no: «¿hay validación de limit > 100?», «¿se han modificado archivos fuera de app/payments?».
• Calibración con etiquetado manual. Etiquete a mano entre 20 y 30 resultados y compárelos con los veredictos del juez. Si la coincidencia es baja, hay que cambiar la rúbrica, no confiar más en el juez.
• Asimetría de errores. Un «listo» falso es más caro que un «no listo» falso: el primero llega a producción, el segundo cuesta un reinicio. Configure el juez para rechazar en caso de duda.

Qué métricas calcular además de la tasa de éxito

La proporción de tareas resueltas es solo la punta del iceberg. Para entender dónde hay que arreglar, hacen falta métricas de fiabilidad de la ingeniería clásica.

• MTBF — cuántos pasos o tareas recorre el agente antes de atascarse. Muestra con qué poca frecuencia se rompe.
• MTTR — cuánto tiempo se tarda en volver a un estado de trabajo tras un fallo. Reducirlo suele ser más barato que aumentar el MTBF: un buen archivo de progreso y un entorno reproducible acortan la recuperación varias veces.
• Radio de daño — cuánto código estropea un paso fallido. Se limita con un tope en el diff y con el aislamiento de la copia de trabajo.
• Proporción de «listo» falsos — tareas en las que el agente declaró éxito y la comprobación falló. Es la métrica más peligrosa: muestra si se puede confiar en el informe del agente.
• Coste y tiempo — tokens y minutos por tarea. Un harness que sube el éxito un 5% pero duplica el coste no siempre gana.

Diario de fallos: evals del trabajo cotidiano

No todos los equipos están listos para construir de golpe un ejecutor de pruebas. La versión mínima de la evaluación es un diario de fallos de tres columnas.

| Tarea                   | Resultado                          | Capa          |
|-------------------------|------------------------------------|---------------|
| paginación /payments    | «listo», 2 pruebas en rojo         | verificación  |
| arreglar timeout webhook| 30 min en pip install              | entorno       |
| refactorizar refunds    | sintaxis antigua del ORM           | contexto      |

La capa es uno de los cinco lugares donde se rompe el agente: especificación de la tarea, contexto, entorno de ejecución, retroalimentación de la verificación y gestión del estado. Tras veinte entradas se ve el verdadero cuello de botella, y casi nunca está donde se pensaba. Cada línea del diario es un candidato al conjunto de tareas de evals.

Por qué un modelo potente no lo arregla todo

La primera reacción ante los fallos del agente es contratar un modelo más caro. A veces ayuda, pero con más frecuencia la brecha entre el benchmark y la realidad la cierra no el modelo, sino el entorno que lo rodea.

Si el agente tarda media hora en levantar el entorno, es un problema de la capa de entorno, y el modelo más potente tardará esa misma media hora. Si el agente dice «listo» con pruebas en rojo, es un problema de la capa de verificación: no tiene un comando que le diga la verdad. Si escribe código con un estilo ajeno, es que no se le dieron las convenciones del proyecto. Ninguno de estos problemas tiene que ver con la inteligencia del modelo.

Las evals permiten comprobarlo con honestidad. Ejecute el conjunto con el modelo actual y con uno más caro; luego, con el modelo actual y con un AGENTS.md que incluya los comandos de verificación. Muchas veces el segundo cambio aporta más que el primero, y sin coste. Pero no lo crea solo por mi palabra: para estas comparaciones es para lo que sirve el conjunto.

Plan paso a paso: evaluar agentes de IA en una semana

1. Día 1. Abra un diario de fallos y anote cada error del agente indicando la capa.
2. Día 2. Seleccione 20 tareas de tickets cerrados y del diario. Para cada una, fije el commit y escriba el criterio de éxito en forma de comandos.
3. Día 3. Escriba un ejecutor: copia de trabajo limpia, lanzamiento del agente con el prompt de la tarea, ejecución de las comprobaciones, registro del resultado en JSONL.
4. Día 4. Ejecute cada tarea entre 3 y 5 veces. Calcule pass@1, pass^3, la proporción de «listo» falsos y el coste medio.
5. Día 5. Cambie una cosa del harness y vuelva a ejecutar. Compare solo con el mismo conjunto y el mismo número de repeticiones.

Cambie una variable cada vez. Si en un mismo experimento cambia el modelo, el prompt y las herramientas, no sabrá qué funcionó.

Errores habituales al evaluar agentes

• Una sola ejecución por tarea. El no determinismo del agente convierte ese resultado en una lotería. Como mínimo, tres repeticiones.
• El conjunto cambia entre comparaciones. Si añade tareas nuevas y al mismo tiempo cambia el prompt, las cifras no son comparables.
• El agente ve las pruebas de verificación. Si las pruebas están en el repositorio, el agente puede adaptar el código a ellas o simplemente modificarlas. Guarde las comprobaciones ocultas fuera de la copia de trabajo y verifique que el agente no ha tocado los archivos de prueba.
• Informe del agente en lugar de verificación. «Todas las pruebas pasaron» en la respuesta del modelo no es un resultado. El resultado es el código de retorno del comando ejecutado por el ejecutor.
• Solo pass@k. Una cifra bonita para una presentación y una mala predicción para el trabajo autónomo.

En resumen

Evaluar agentes de IA es un conjunto fijo de tareas reales, comprobaciones automáticas y métricas que se recalculan tras cada cambio en el harness. pass@k muestra de qué es capaz el agente; pass^k, si se le puede confiar el trabajo sin supervisión. Las comprobaciones automáticas dan la verdad; el juez LLM, con una rúbrica y un contexto aparte, las complementa donde el código no alcanza. Y el diario de fallos por cinco capas muestra qué arreglar primero, que casi nunca es el modelo. Las métricas de fiabilidad y el bucle de diagnóstico se analizan en la práctica en el curso de harness engineering.