getedgehq/agent-evals

Avaliações de agente (evals)

Uma avaliação responde a uma pergunta: o agente fez o trabalho corretamente? Tudo abaixo é uma forma de fazer essa pergunta de maneira mais confiável, mais barata e mais frequente.

Construído a partir da masterclass de evals por Alex Lieberman com Viv (LangChain), 2026: youtube.com/watch?v=zLeG-XJtbIE. A estrutura (fácil, difícil, modo deus) é deles. Os erros neste skill são nossos.

Comece perguntando ao usuário três coisas

1. Que trabalho real o agente faz? Nomeie o sistema que ele toca (CRM, caixa de entrada, repositório, banco de dados).
2. Quem na empresa é o melhor nesse trabalho hoje? O julgamento dessa pessoa é a verdade absoluta.
3. O agente já está em produção? Se sim, os traces estão armazenados em algum lugar?

Escolha o modo com base nas respostas. Não pule para o modo deus sem tarefas e verificadores.

Modo fácil: tarefas e verificadores

Uma tarefa é uma pequena parte verificável do trabalho real. Um verificador diz se aquela tarefa foi feita corretamente.

1. Escreva de 10 a 30 tarefas que copiem o que colegas reais fazem. Exemplos para um agente de vendas:
   • adicionar uma nota a um registro do CRM após uma chamada
   • encontrar um prospect que não está na tabela óbvia
   • rascunhar um e-mail de resposta sem enviá-lo
2. Para cada tarefa, escreva o verificador. Prefira, nesta ordem:
   • Verificação de estado (um script): o campo estava vazio antes e contém o valor correto depois; a tag email_sent existe.
   • Checklist (um modelo ou um humano): para qualquer coisa não diretamente verificável, divida "bom" em perguntas sim/não. "Três parágrafos ou menos?" "Usa as regras de tom da marca?"
3. Mantenha todo julgamento binário. Modelos questionados a dar uma nota de 1 a 10 tendem a 7 e fazem rodeios. Sim/não não permite rodeios.
4. Obtenha o checklist da melhor pessoa no trabalho, por escrito. Execute o agente, revise uma amostra manualmente. Se uma saída passar no checklist mas ainda parecer errada, o checklist está incompleto. Adicione a pergunta faltante.

Saída do modo fácil: uma pasta de tarefas, cada uma com uma instrução e um verificador, e uma taxa de aprovação.

Modo difícil: ambientes

Um ambiente é onde o agente faz o trabalho: seus arquivos, ferramentas, dados e permissões. Nunca avalie com dados de produção. Um agente que falha na avaliação também edita o CRM real.

1. Construa uma cópia que pareça real para o agente: mesmas tabelas, mesmas ferramentas, registros falsos. Empacote-a de modo que seja redefinida para o mesmo estado a cada execução (um contêiner é a escolha usual).
2. Uma tarefa = instrução + ambiente + verificador. Armazene-os juntos.
3. Não crie seu próprio executor se puder evitar. Harbor (github.com/harbor-framework/harbor) tem formatos compartilhados para tarefas, ambientes e verificadores, e muitas tarefas publicadas que você pode adaptar.
4. Teste o próprio ambiente. O primeiro está errado. Execute vários agentes ou modelos diferentes através dele e procure por padrões estranhos:
   • um modelo forte falha onde um fraco passa
   • um agente encontra a resposta em algum lugar onde não deveria (uma linha de espaço reservado, um arquivo vazado). Agentes pegarão qualquer atalho para passar. Remova o vazamento.
5. Etiquete cada tarefa por família (codificação, vendas, revisão de código). Quando um novo modelo for lançado, execute apenas as famílias nas quais ele pode ser bom.
6. Escolha modelos com uma tabela, não com um palpite. Execute cada candidato nas mesmas tarefas etiquetadas. Registre taxa de aprovação, custo e velocidade lado a lado. Então um humano decide: 5 pontos de precisão valem 3x o custo para esta família? Tarefas voltadas ao usuário geralmente justificam o melhor modelo; as internas, muitas vezes não.

Saída do modo difícil: um conjunto de avaliações que pode ser reexecutado em qualquer modelo com um comando, com uma tabela de resultados por família de tarefas.

Modo deus: o ciclo de melhoria

O ciclo: o agente é executado, produz traces, falhas se tornam novas tarefas, o agente é corrigido, repete.

1. Ative o rastreamento (tracing). Um trace é o registro de cada ação: cada chamada de ferramenta, cada mensagem, cada resultado. Ninguém pode prever o que um agente fará. Todos podem julgar o que ele fez.
2. Armazene traces em um só lugar. Para um desenvolvedor individual, os próprios logs do agente no disco são suficientes. Para uma equipe, use um produto de rastreamento com permissões.
3. Aponte um segundo agente para os traces. Sua única função é encontrar padrões. Dê a ele um resumo curto de comportamento bom e ruim. Peça:
   • chamadas de ferramenta que falharam ou se repetiram
   • instruções que ele ignorou ou seguiu pela metade
   • um caminho errado recorrente (sempre pesquisando na tabela errada, fazendo uma empresa quando solicitado três)
4. Transforme cada falha confirmada em uma tarefa no conjunto de avaliações, para que ela nunca possa voltar silenciosamente.
5. Corrija o agente, começando pela alavanca mais barata:
   • configuração (harness): prompt, descrições de ferramentas, conjunto de ferramentas, escolha do modelo
   • ajuste fino de um pequeno modelo aberto na tarefa específica, uma vez que o conjunto prove que ele corresponde ao grande modelo
6. Mantenha um humano no que significa "bom". Agentes podem propor correções e rascunhar tarefas. Um humano ainda decide quais tarefas são importantes para o negócio e revisa as novas. Escrever isso é a parte de maior alavancagem do ciclo.

Regras

• Sem avaliação sem um trabalho real nomeado. Benchmarks genéricos não dizem se seu agente funciona.
• Apenas verificadores binários. Divida qualquer nota em perguntas sim/não.
• Nunca deixe uma avaliação tocar dados de produção.
• Um conjunto que tudo passa é um conjunto quebrado. Verifique vazamentos.
• Reporte taxas de aprovação com a contagem de tarefas ao lado ("21 de 30"), nunca uma porcentagem nua.