Habilidad de Evaluación de Agentes
Una herramienta CLI ligera para comparar agentes de codificación uno a uno en tareas reproducibles. Cada comparación de "cuál agente de codificación es mejor" se basa en impresiones — esta herramienta la sistematiza.
Cuándo Activarla
- Comparar agentes de codificación (Claude Code, Aider, Codex, etc.) en tu propio código base
- Medir el rendimiento de agentes antes de adoptar una nueva herramienta o modelo
- Ejecutar comprobaciones de regresión cuando un agente actualiza su modelo o herramientas
- Producir decisiones de selección de agentes respaldadas por datos para un equipo
Instalación
Nota: Instala agent-eval desde su repositorio después de revisar el código fuente.
Conceptos Clave
Definiciones de Tareas en YAML
Define tareas de forma declarativa. Cada tarea especifica qué hacer, qué archivos tocar y cómo juzgar el éxito:
name: agregar-logica-reintento
description: Agregar reintento con backoff exponencial al cliente HTTP
repo: ./mi-proyecto
files:
- src/http_client.py
prompt: |
Agrega lógica de reintento con backoff exponencial a todas las solicitudes HTTP.
Máximo 3 reintentos. Retardo inicial 1s, retardo máximo 30s.
judge:
- type: pytest
command: pytest tests/test_http_client.py -v
- type: grep
pattern: "exponential_backoff|retry"
files: src/http_client.py
commit: "abc1234" # fijar a un commit específico para reproducibilidad
Aislamiento con Git Worktree
Cada ejecución de agente obtiene su propio worktree de Git — no se requiere Docker. Esto proporciona aislamiento de reproducibilidad para que los agentes no interfieran entre sí ni corrompan el repositorio base.
Métricas Recopiladas
| Métrica | Qué Mide |
|---|---|
| Tasa de aprobación | ¿El agente produjo código que pasa el juez? |
| Costo | Gasto de API por tarea (cuando está disponible) |
| Tiempo | Segundos de pared hasta la finalización |
| Consistencia | Tasa de aprobación en ejecuciones repetidas (ej., 3/3 = 100%) |
Flujo de Trabajo
1. Definir Tareas
Crea un directorio tasks/ con archivos YAML, uno por tarea:
mkdir tasks
# Escribe las definiciones de tareas (ver plantilla arriba)
2. Ejecutar Agentes
Ejecuta agentes contra tus tareas:
agent-eval run --task tasks/agregar-logica-reintento.yaml --agent claude-code --agent aider --runs 3
Cada ejecución:
- Crea un nuevo worktree de Git a partir del commit especificado
- Entrega el prompt al agente
- Ejecuta los criterios del juez
- Registra aprobación/fallo, costo y tiempo
3. Comparar Resultados
Genera un informe de comparación:
agent-eval report --format table
Tarea: agregar-logica-reintento (3 ejecuciones cada uno)
┌──────────────┬───────────┬────────┬────────┬─────────────┐
│ Agente │ Tasa Aprob│ Costo │ Tiempo │ Consistencia│
├──────────────┼───────────┼────────┼────────┼─────────────┤
│ claude-code │ 3/3 │ $0.12 │ 45s │ 100% │
│ aider │ 2/3 │ $0.08 │ 38s │ 67% │
└──────────────┴───────────┴────────┴────────┴─────────────┘
Tipos de Jueces
Basados en Código (deterministas)
judge:
- type: pytest
command: pytest tests/ -v
- type: command
command: npm run build
Basados en Patrones
judge:
- type: grep
pattern: "class.*Retry"
files: src/**/*.py
Basados en Modelos (LLM como juez)
judge:
- type: llm
prompt: |
¿Esta implementación maneja correctamente el backoff exponencial?
Verificar: máximo de reintentos, retrasos crecientes, jitter.
Mejores Prácticas
- Comienza con 3-5 tareas que representen tu carga de trabajo real, no ejemplos de juguete
- Ejecuta al menos 3 ensayos por agente para capturar la varianza — los agentes no son deterministas
- Fija el commit en tu YAML de tarea para que los resultados sean reproducibles a lo largo de días/semanas
- Incluye al menos un juez determinista (pruebas, compilación) por tarea — los jueces LLM añaden ruido
- Monitorea el costo junto con la tasa de aprobación — un agente con 95% de aprobación a 10x el costo puede no ser la elección correcta
- Versiona tus definiciones de tareas — son accesorios de prueba, trátalos como código
Enlaces
- Repositorio: github.com/joaquinhuigomez/agent-eval