Skill 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 impressões — esta ferramenta a sistematiza.
Quando Ativar
- Comparar agentes de codificação (Claude Code, Aider, Codex, etc.) no seu próprio código-fonte
- Medir o desempenho do agente antes de adotar uma nova ferramenta ou modelo
- Executar verificações de regressão quando um agente atualiza seu modelo ou ferramentas
- Produzir 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 de forma declarativa. 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 retentativas. Atraso inicial de 1s, atraso máximo de 30s.
judge:
- type: pytest
command: pytest tests/test_http_client.py -v
- type: grep
pattern: "backoff_exponencial|retry"
files: src/http_client.py
commit: "abc1234" # fixar commit específico para reprodutibilidade
Isolamento com Git Worktree
Cada execução do agente recebe seu próprio git worktree — sem necessidade de Docker. Isso fornece isolamento de reprodutibilidade para que os agentes não interfiram entre si ou 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 com API por tarefa (quando disponível) |
| Tempo | Segundos de parede até a conclusão |
| Consistência | Taxa de aprovação em execuções repetidas (ex: 3/3 = 100%) |
Fluxo de Trabalho
1. Defina Tarefas
Crie um diretório tasks/ com arquivos YAML, um por tarefa:
mkdir tasks
# Escreva definições de tarefa (veja modelo acima)
2. Execute 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/reprovação, custo e tempo
3. Compare Resultados
Gere um relatório de comparação:
agent-eval report --format table
Tarefa: adicionar-logica-retry (3 execuções cada)
┌──────────────┬───────────┬────────┬────────┬─────────────┐
│ Agente │ Taxa Aprov│ Custo │ Tempo │ Consistência│
├──────────────┼───────────┼────────┼────────┼─────────────┤
│ 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ão
judge:
- type: grep
pattern: "class.*Retry"
files: src/**/*.py
Baseado em Modelo (LLM como juiz)
judge:
- type: llm
prompt: |
Esta implementação trata corretamente o backoff exponencial?
Verifique: máximo de retentativas, atrasos 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 variância — agentes são não determinísticos
- Fixe o commit em seu YAML de tarefa para que os resultados sejam reproduzíveis ao longo de 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
- Versionize suas definições de tarefa — elas são fixtures de teste, trate-as como código
Links
- Repositório: github.com/joaquinhuigomez/agent-eval