Avaliação de agentes de IA: como montar evals e medir confiabilidade, não impressão

Para que avaliar o agente, se já dá para ver que ele funciona

É justamente aí que a percepção falha. Em uma semana o agente não travou nenhuma vez depois de uma mudança no prompt: foi um conserto ou só uma semana de tarefas fáceis? Um engenheiro está convencido de que o novo template mudou tudo; outro leu o mesmo log e não notou diferença. Ambos têm razão exatamente na medida em que não mediram nada.

A avaliação de agentes de IA (evals) troca a sensação por um número. Você escolhe um conjunto fixo de tarefas, executa o agente, verifica o resultado automaticamente e compara as métricas antes e depois de uma mudança. Assim, a discussão sobre "ficou melhor?" se resolve com uma tabela, e não com autoridade.

Sem evals, qualquer mudança no harness — prompt, AGENTS.md, conjunto de ferramentas, modelo — é uma aposta às cegas. Com eles, é um experimento com resultado mensurável.

Por que a impressão engana

A impressão sobre o trabalho do agente tem três erros sistemáticos, e todos levam a uma confiança falsa.

• Viés do sobrevivente. As execuções bem-sucedidas são lembradas e mostradas aos colegas; as malsucedidas são refeitas e esquecidas. A confiabilidade calculada apenas com as execuções bem-sucedidas não diz nada sobre onde o agente de fato quebra.
• Amostra pequena. Três tarefas bem-sucedidas seguidas são um evento normal até para um agente que acerta na metade das vezes. A probabilidade disso é 0,5³ = 12,5%, ou seja, cerca de uma em cada oito séries.
• Tom confiante. O agente escreve "pronto, todos os testes passam" com a mesma segurança quando isso é verdade e quando não é. A confiança do modelo não é calibrada: o tom da resposta não é sinal de correção.

Daí a regra: tudo o que não foi registrado e recalculado é considerado não medido.

pass@k e pass^k: duas métricas que se confundem

O agente é não determinístico: a mesma tarefa, repetida, pode passar ou falhar. Por isso uma tarefa é executada várias vezes e calcula-se uma de duas métricas.

pass@k — pelo menos uma tentativa de k tem êxito

A métrica vem da avaliação de geração de código. Ela responde à pergunta "o sistema é capaz, em princípio, de resolver a tarefa se tiver várias tentativas?". É uma métrica honesta para um cenário em que uma pessoa escolhe a melhor entre várias saídas ou em que há uma verificação automática confiável que descarta as malsucedidas.

pass^k — todas as k tentativas têm êxito

Essa métrica responde a outra pergunta: "com que estabilidade o agente resolve a tarefa?". Ela descreve o trabalho sem supervisão — quando o agente roda muitas vezes e cada falha custa dinheiro ou tempo.

A diferença entre elas é enorme. Suponha que o agente resolva a tarefa com probabilidade de 70% em uma tentativa e que as tentativas sejam independentes:

Pelo pass@5 o agente parece quase perfeito; pelo pass^5, ele não é confiável. Os dois números são verdadeiros, só descrevem coisas diferentes. Se você pretende deixar o agente trabalhar de forma autônoma, olhe para o pass^k: ele se aproxima mais do que você verá no trabalho real.

Como calcular na prática

Execute cada tarefa n vezes (por exemplo, 5) e anote o número de sucessos c. Para pass^k, a estimativa é a proporção de execuções em que todas as k deram certo; de forma mais simples, estime a probabilidade de sucesso p = c / n e eleve à potência k. Para um conjunto de tarefas, tire a média entre elas.

import json
from statistics import mean

# results.jsonl: {"task": "add-pagination", "runs": [true, true, false, true, true]}
rows = [json.loads(line) for line in open("results.jsonl")]

def pass_at_k(runs, k):
    p = sum(runs) / len(runs)
    return 1 - (1 - p) ** k

def pass_pow_k(runs, k):
    p = sum(runs) / len(runs)
    return p ** k

for k in (1, 3, 5):
    print(k,
          round(mean(pass_at_k(r["runs"], k) for r in rows), 3),
          round(mean(pass_pow_k(r["runs"], k) for r in rows), 3))

A estimativa por p elevado a k é grosseira com n pequeno, mas para comparar versões do harness entre si ela costuma bastar. O mais importante é que n e o conjunto de tarefas não mudem entre as comparações.

Como montar o conjunto de tarefas para evals

O conjunto de tarefas é o principal ativo. Uma métrica boa sobre tarefas ruins mede a coisa errada.

Pegue tarefas da sua realidade

Benchmarks públicos, como o SWE-bench, são úteis para comparar modelos, mas as tarefas deles são selecionadas: descrição clara, testes prontos. No seu repositório os requisitos são vagos e há lugares sem testes, então o número do benchmark quase sempre fica acima do que o agente mostra no seu projeto. As melhores fontes de tarefas são os tickets fechados e as falhas reais do agente registradas no diário.

Composição do conjunto

• 20–50 tarefas para começar. Menos do que isso, o ruído engole a diferença entre as versões. Mais, e a execução fica cara a ponto de deixarem de rodá-la.
• Tipos diferentes: nova funcionalidade, correção de bug, refatoração, tarefa em módulo alheio, tarefa com armadilha (em que a resposta certa é "isso não deve ser feito assim" ou "é preciso esclarecer").
• Cada tarefa que falhou no trabalho vira um teste. Assim o conjunto cresce junto com a compreensão de onde o agente é fraco, e as regressões não voltam despercebidas.
• Estado inicial fixo: um commit específico, dependências travadas, ambiente idêntico. Caso contrário, você mede a deriva do ambiente, e não o agente.

Formato da tarefa

Cada tarefa é uma descrição, um estado inicial e um critério de sucesso que pode ser verificado sem uma pessoa.

id: add-pagination
repo_ref: 3f2c1ab
prompt: |
  Adicione paginação em GET /payments: parâmetros limit (padrão 20, máximo 100)
  e cursor. A resposta contém next_cursor.
check:
  - pytest tests/test_payments_pagination.py
  - mypy app/
limits:
  max_changed_files: 6

Repare que o critério de sucesso é a Definition of Done escrita em comandos. Se você não consegue escrever o critério de uma tarefa, isso é sinal de que ela também foi dada ao agente de forma ambígua.

Verificações automáticas ou juiz LLM

O resultado pode ser verificado por código ou por outro modelo. Cada abordagem tem seu território.

Regra: primeiro o código, o juiz por cima

Tudo o que pode ser verificado de forma determinística deve ser verificado de forma determinística. Adicione o juiz LLM apenas para propriedades que o código não consegue expressar, e nunca no lugar dos testes.

Como tornar o juiz LLM útil

• Contexto diferente do gerador. O juiz não deve ver o raciocínio do agente, apenas a tarefa, os critérios e o diff final. Caso contrário, ele repete os mesmos erros: é a ideia da N-versão, dois olhares independentes em vez de um só.
• Rubrica em vez de "avalie de 1 a 10". Perguntas concretas com resposta sim/não: "há validação de limit > 100?", "foram alterados arquivos fora de app/payments?".
• Calibração com marcação manual. Marque à mão de 20 a 30 resultados e compare com os veredictos do juiz. Se a concordância for baixa, mude a rubrica, e não passe a confiar mais no juiz.
• Assimetria de erros. Um falso "pronto" custa mais caro do que um falso "não pronto": o primeiro vai para produção, o segundo custa uma nova execução. Configure o juiz para rejeitar em caso de dúvida.

Quais métricas medir além da taxa de acerto

A taxa de tarefas resolvidas é só a ponta do iceberg. Para entender exatamente onde consertar, são necessárias as métricas de confiabilidade da engenharia clássica.

• MTBF — quantos passos ou tarefas o agente cumpre até travar. Mostra com que raridade ele quebra.
• MTTR — quanto tempo leva para voltar a um estado de trabalho depois de uma falha. Reduzir esse tempo quase sempre custa menos do que aumentar o MTBF: um bom arquivo de progresso e um ambiente reproduzível diminuem a recuperação em muitas vezes.
• Raio de dano — quanto código um passo malsucedido estraga. É limitado por um teto de diff e pelo isolamento da cópia de trabalho.
• Taxa de falsos "pronto" — tarefas em que o agente declarou sucesso, mas a verificação falhou. É a métrica mais perigosa: ela mostra se é possível confiar no relatório do agente.
• Custo e tempo — tokens e minutos por tarefa. Um harness que elevou o sucesso em 5%, mas dobrou o custo, nem sempre vale a pena.

Diário de falhas: evals do dia a dia

Nem toda equipe está pronta para construir um executor de evals de imediato. A versão mínima da avaliação é um diário de falhas com três colunas.

| Tarefa                  | Resultado                          | Camada        |
|-------------------------|------------------------------------|---------------|
| paginação /payments     | "pronto", 2 testes vermelhos       | verificação   |
| conserto de timeout do webhook | 30 min no pip install       | ambiente      |
| refatoração de refunds  | sintaxe antiga do ORM              | contexto      |

A camada é um dos cinco lugares onde o agente costuma quebrar: especificação da tarefa, contexto, ambiente de execução, realimentação da verificação e gestão de estado. Depois de vinte registros, aparece o verdadeiro gargalo, e quase nunca ele está onde você imaginava. Cada linha do diário é candidata a entrar no conjunto de tarefas para evals.

Por que um modelo potente não salva

A primeira reação às falhas do agente é contratar um modelo mais caro. Às vezes isso ajuda, mas com mais frequência a distância entre o benchmark e a sua realidade é fechada não pelo modelo, e sim pelo ambiente ao redor dele.

Se o agente leva meia hora para subir o ambiente, o problema está na camada de ambiente, e um modelo de ponta levará os mesmos trinta minutos. Se o agente diz "pronto" com testes vermelhos, o problema está na camada de verificação: ele não tem um comando que diga a verdade. Se escreve código no estilo errado, não lhe foram dadas as convenções do projeto. Nenhum desses problemas é uma questão de inteligência do modelo.

Os evals permitem verificar isso com honestidade. Rode o conjunto com o modelo atual e com um modelo mais caro; depois, com o modelo atual e com um AGENTS.md que inclua os comandos de verificação. Muitas vezes a segunda mudança dá mais ganho do que a primeira, sem custo nenhum. Mas não acredite nisso na palavra: para essas comparações é que o conjunto existe.

Plano passo a passo: avaliação de agentes de IA em uma semana

1. Dia 1. Abra um diário de falhas e registre cada falha do agente indicando a camada.
2. Dia 2. Selecione 20 tarefas entre os tickets fechados e o diário. Para cada uma, fixe o commit e escreva o critério de sucesso em comandos.
3. Dia 3. Escreva o executor: cópia de trabalho limpa, execução do agente com o prompt da tarefa, execução das verificações, gravação do resultado em JSONL.
4. Dia 4. Rode cada tarefa de 3 a 5 vezes. Calcule pass@1, pass^3, a taxa de falsos "pronto" e o custo médio.
5. Dia 5. Mude uma coisa no harness e rode de novo. Compare apenas com o mesmo conjunto e o mesmo número de repetições.

Mude uma variável por vez. Se em um experimento você troca ao mesmo tempo o modelo, o prompt e as ferramentas, não saberá o que funcionou.

Erros típicos na avaliação de agentes

• Uma execução por tarefa. O não determinismo do agente transforma esse resultado em loteria. No mínimo, três repetições.
• O conjunto muda entre as comparações. Você acrescenta tarefas novas e, ao mesmo tempo, altera o prompt — os números deixam de ser comparáveis.
• O agente vê os testes de verificação. Se os testes estão no repositório, o agente pode ajustar o código a eles ou simplesmente alterá-los. Guarde as verificações ocultas fora da cópia de trabalho e confira se o agente não tocou nos arquivos de teste.
• Relatório do agente no lugar da verificação. "Todos os testes passaram" na resposta do modelo não é resultado. O resultado é o código de retorno do comando executado pelo executor.
• Só pass@k. Um número bonito para apresentação e uma má previsão para o trabalho autônomo.

Resumindo

A avaliação de agentes de IA é um conjunto fixo de tarefas reais, verificações automáticas e métricas recalculadas após cada mudança no harness. O pass@k mostra do que o agente é capaz; o pass^k, se dá para confiar nele sem supervisão. As verificações automáticas dizem a verdade, e um juiz LLM com rubrica e contexto separado as complementa onde o código não alcança. Já o diário de falhas por cinco camadas mostra o que consertar primeiro, e na maioria das vezes o gargalo não é o modelo. Métricas de confiabilidade e o ciclo de diagnóstico são explicados na prática no curso de harness engineering.