Cómo implementar evaluaciones automatizadas para agentes de IA

Testing Your AI Agent Skills: por qué importa y qué mide un eval

Una Skill no es un prompt bonito: es documentación ejecutable que un agente usa para actuar. Cambiar una instrucción, reordenar pasos o quitar una verificación puede romper el comportamiento sin avisos. Los LLMs son no deterministas; una ejecución exitosa no prueba nada. Los evals automatizados solucionan eso midiendo tres cosas:

• Capacidad (pass@k): ¿puede el agente resolver la tarea al menos una vez en k intentos?
• Fiabilidad (pass^k): ¿la resuelve todas las veces en k intentos?
• Correctitud (grader determinista): ¿el resultado cumple la condición objetiva (compila, lint pasa, tabla creada)?

Un ejemplo realista de comando que debes poder ejecutar en CI:

GEMINI_API_KEY=your-key npm run eval superlint -- --provider=docker --trials=5

Eso encapsula aislamiento (Docker), repetición estadística (trials) y la unidad de test (la skill superlint).

Repositorio de referencia: https://github.com/mgechev/skill-eval

Arquitectura mínima de un eval efectivo

Cada tarea debe ser autocontenida y reproducible. Estructura sugerida:

tasks/my_task/
├── task.toml           # timeouts, recursos, límites
├── instruction.md      # el prompt único para el agente
├── environment/Dockerfile
├── tests/test.sh       # grader determinista (shell)
├── prompts/quality.md  # grader de rúbrica (opcional)
├── solution/solve.sh   # referencia
└── skills/my_skill/
    └── SKILL.md

Principios clave:

• El agente recibe solo instruction.md como prompt primario. Las skills viven en rutas de descubrimiento estándar (.agents/skills/ o .claude/skills/).
• Los graders deterministas deben ser código: scripts que ejecutan eslint, npm test o consultas SQL y devuelven PASS/FAIL.
• Usa Docker para aislar cada trial y destruir el contenedor tras la verificación. Documentación Docker: https://www.docker.com/

Ejemplo práctico: verificador determinista para superlint

Si la tarea es “arreglar errores de lint”, el grader no puede ser subjetivo. Un ejemplo de tests/test.sh:

#!/usr/bin/env bash
set -e
# Ejecuta eslint en la ruta de trabajo
npx eslint main.js --max-warnings=0
if [ $? -eq 0 ]; then
  echo "PASS"
  exit 0
else
  echo "FAIL"
  exit 1
fi

No preguntes al LLM “¿lo hiciste bien?”. Ejecuta eslint (https://eslint.org) y deja que el exit code decida.

Repetición y métricas: por qué 5 trials no es arbitrario

Los LLMs introducen variabilidad. Ejecutar 5 trials te da una muestra mínima para estimar estabilidad. Interpretación práctica:

• pass@5 = 100% y pass^5 = 100% → listo para producción.
• pass@5 = 100% y pass^5 = 30% → el agente puede hacerlo, pero es flaky; no desplegar.
• pass@5 < 80% → la skill necesita rediseño (más contexto, scripts deterministas, aclaraciones en SKILL.md).

Para workflows críticos (migraciones, despliegues), fija umbral >= 90% pass^k.

Integración CI: Quality Gate para Skills

Añade un job que corra los evals en cada PR que toque skills/ o tasks/:

name: Skill Eval
on:
  pull_request:
    paths: ['skills/**', 'tasks/**']

jobs:
  eval:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
      - run: npm ci
      - run: GEMINI_API_KEY=${{ secrets.GEMINI_API_KEY }} npm run eval my_task -- --trials=5 --provider=docker

Si la tasa de éxito cae por debajo del umbral, el PR queda bloqueado con el output del eval (trials individuales, logs, grader output). Esa transparencia es crítica para debugging rápido.

Diagnóstico accionable cuando fallan trials

Un buen eval no solo marca FAIL; explica por qué. Ejemplo de salida útil:

Trial 1: FAIL - Agent ran 'eslist --lint' (typo)  
Trial 2: PASS  
Trial 3: FAIL - Agent modified src/utils.js instead of src/main.js  
Trial 4: PASS  
Trial 5: PASS

Con esa trazabilidad ajustas SKILL.md o scripts (p. ej., forzar paths absolutos, añadir checks previos, mejorar error handling en scripts).

Recomendaciones finales y checklist rápido

• Mantén SKILL.md corto y prescriptivo; externaliza lo frágil a scripts/.
• Usa Docker para todos los evals que toquen filesystem o red.
• Implementa graders deterministas como contrato (stdout JSON + exit codes).
• Ejecuta >=5 trials; optimiza para pass^k en producción.
• Integra evals en CI como Quality Gate.
• Mantén dataset de pruebas realistas (repos con edge-cases), no solo ejemplos sintéticos.

Testing Your AI Agent Skills no es opcional. Si confías en agentes para tocar código o infra, mide su comportamiento bajo condiciones reproductibles. Implementa evals hoy y transforma tus skills de “probablemente funcionan” a “sabemos que funcionan”.

Como continuación lógica a estos procesos y para explorar integraciones y experimentos prácticos con evaluaciones de skills y pipelines de CI, visite Dominicode Labs. Allí encontrará recursos y ejemplos orientados a equipos de ingeniería que automatizan agentes y workflows.

FAQ

• ¿Qué es un eval para una Skill?
• ¿Cuántos trials debo ejecutar?
• ¿Por qué usar Docker en cada trial?
• ¿Cómo debe devolver resultados un grader?
• ¿Qué hacer si pass@k es alto pero pass^k es bajo?
• ¿Qué umbral usar en producción?