Habilidade Agent Eval
Uma ferramenta CLI leve para comparar agentes de codificação lado a lado em tarefas reproduzíveis. Toda comparação 'qual agente de codificação é melhor?' é baseada em intuições — esta ferramenta a sistematiza.
Quando Ativar
- Comparando agentes de codificação (Claude Code, Aider, Codex, etc.) em seu próprio código
- Medindo desempenho de agentes antes de adotar uma nova ferramenta ou modelo
- Executando verificações de regressão quando um agente atualiza seu modelo ou ferramentas
- Produzindo decisões de seleção de agentes baseadas em dados para uma equipe
Instalação
Nota: Instale o agent-eval a partir de seu repositório após revisar o código-fonte.
Conceitos Principais
Definições de Tarefas em YAML
Defina tarefas declarativamente. Cada tarefa especifica o que fazer, quais arquivos modificar e como julgar o sucesso:
name: adicionar-logica-retry
description: Adicionar retry com backoff exponencial ao cliente HTTP
repo: ./meu-projeto
files:
- src/http_client.py
prompt: |
Adicione lógica de retry com backoff exponencial a todas as requisições HTTP.
Máximo de 3 retries. Delay inicial 1s, delay 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" # fixa commit específico para reprodutibilidade
Isolamento com Git Worktree
Cada execução de agente recebe seu próprio git worktree — sem necessidade de Docker. Isso fornece isolamento de reprodutibilidade para que agentes não interfiram entre si nem corrompam o repositório base.
Métricas Coletadas
| Métrica | O que Mede |
|---|---|
| Taxa de aprovação | O agente produziu código que passa no juiz? |
| Custo | Gasto de API por tarefa (quando disponível) |
| Tempo | Segundos de relógio até a conclusão |
| Consistência | Taxa de aprovação em execuções repetidas (ex.: 3/3 = 100%) |
Fluxo de Trabalho
1. Definir Tarefas
Crie um diretório tasks/ com arquivos YAML, um por tarefa:
mkdir tasks
# Escreva as definições das tarefas (veja modelo acima)
2. Executar Agentes
Execute agentes contra suas tarefas:
agent-eval run --task tasks/adicionar-logica-retry.yaml --agent claude-code --agent aider --runs 3
Cada execução:
- Cria um novo git worktree a partir do commit especificado
- Entrega o prompt ao agente
- Executa os critérios do juiz
- Registra aprovação/falha, custo e tempo
3. Comparar Resultados
Gere um relatório de comparação:
agent-eval report --format table
Tarefa: adicionar-logica-retry (3 execuções cada)
┌──────────────┬───────────┬────────┬────────┬─────────────┐
│ Agent │ Pass Rate │ Cost │ Time │ Consistency │
├──────────────┼───────────┼────────┼────────┼─────────────┤
│ claude-code │ 3/3 │ $0.12 │ 45s │ 100% │
│ aider │ 2/3 │ $0.08 │ 38s │ 67% │
└──────────────┴───────────┴────────┴────────┴─────────────┘
Tipos de Juiz
Baseado em Código (determinístico)
judge:
- type: pytest
command: pytest tests/ -v
- type: command
command: npm run build
Baseado em Padrões
judge:
- type: grep
pattern: "class.*Retry"
files: src/**/*.py
Baseado em Modelo (LLM como juiz)
judge:
- type: llm
prompt: |
Esta implementação lida corretamente com backoff exponencial?
Verifique: máximo de retries, delays crescentes, jitter.
Melhores Práticas
- Comece com 3-5 tarefas que representem sua carga de trabalho real, não exemplos de brinquedo
- Execute pelo menos 3 tentativas por agente para capturar variabilidade — agentes são não-determinísticos
- Fixe o commit em seu YAML de tarefa para que os resultados sejam reproduzíveis entre dias/semanas
- Inclua pelo menos um juiz determinístico (testes, build) por tarefa — juízes LLM adicionam ruído
- Acompanhe o custo junto com a taxa de aprovação — um agente com 95% de aprovação a 10x o custo pode não ser a escolha certa
- Versionar as definições de tarefa — elas são fixtures de teste, trate-as como código
Links
- Repositório: github.com/joaquinhuigomez/agent-eval