Avaliação de agentes de IA: como montar evals honestos

Todo mundo diz que o agente "tá bom". Aí você pergunta: bom medido como? E vem o silêncio. Ou pior: "rodei aqui uns três exemplos e funcionou". Isso não é avaliação de agentes de IA. Isso é torcida com syntax highlight.

O problema é que "funciona nos meus testes" esconde tudo o que importa. Você testou os três casos que já sabia que passavam. Não testou o caso ambíguo, o input malformado, a pergunta que exige duas ferramentas em ordem. E quando o agente vai pra produção, é exatamente esse caso que aparece.

Neste tutorial você vai montar um processo de avaliação honesto pra um agente: um golden set de verdade, métricas separadas por etapa (recuperação, decisão de tool, resposta) e LLM como juiz usado com a cautela que ele exige. No fim, um checklist replicável que você cola no seu projeto.

TL;DR

• O que é: um método pra medir se o seu agente funciona de verdade, sem se enganar com poucos exemplos.
• Stack/Modelos: agnóstico — serve pra agente em Python, PHP/Laravel, qualquer LLM. Exemplos conceituais com golden set em JSON e métricas por etapa.
• Custo/Acesso: o processo é grátis. LLM-as-judge custa chamadas de API extras — use com parcimônia.
• Link útil: Demystifying evals for AI agents (Anthropic).

Por que "funciona nos meus testes" não é avaliação de agentes de IA

Quando você roda três exemplos na mão e dá certo, seu cérebro faz uma conta errada. Ele transforma "passou nos casos que escolhi" em "o agente é bom". São coisas diferentes.

Avaliar agente é diferente de avaliar um modelo puro. Um agente decide, recupera contexto, chama ferramenta, às vezes em várias etapas. Ele pode acertar a resposta final por sorte, depois de chamar a ferramenta errada e recuperar o documento errado. Olhar só o output final é como aprovar um aluno pela resposta certa sem olhar a conta — uma hora ele chuta e você não percebe.

E tem o fator aleatoriedade. O mesmo input pode dar trajetórias diferentes em duas execuções. Um paper recente sobre aleatoriedade em evals agênticos recomenda estimar a taxa de acerto a partir de várias execuções independentes por tarefa, não de uma só. Rodou uma vez e passou? Você mediu ruído, não capacidade.

A régua é simples: se você não consegue dizer um número — "85% das 40 tarefas passam, a recuperação acerta em 90%, a escolha de tool em 78%" — você não avaliou. Você sentiu.

Passo 1 — Monte um golden set de falhas reais

Golden set é o seu conjunto de tarefas com resultado esperado. É a fonte da verdade. E a melhor matéria-prima pra ele não é caso sintético bonitinho — são as falhas reais.

A recomendação da Anthropic é direta: "20 a 50 tarefas simples tiradas de falhas reais já são um ótimo começo" (Anthropic). Não precisa de mil casos no dia um. Precisa dos casos que importam. Pegue o log de produção, os tickets onde o agente se enrolou, as conversas onde o usuário teve que reformular três vezes. Cada falha vira um caso de teste.

Cada item do golden set precisa de input, resultado esperado e — quando dá — a trajetória esperada (quais ferramentas, em que ordem):

{
  "id": "caso-042",
  "origem": "ticket #1981 - usuario reformulou 3x",
  "input": "qual foi minha ultima fatura e ela ja foi paga?",
  "resposta_esperada": "fatura de maio, R$ 240, paga em 03/05",
  "trajetoria_esperada": ["buscar_faturas", "checar_pagamento"],
  "tags": ["multi-tool", "consulta-financeira"]
}

Uma vantagem que ninguém comenta: definir o caso de teste é o melhor jeito de descobrir que o requisito tá vago. Se você não consegue escrever a resposta_esperada, o problema não é o eval — é que ninguém definiu direito o que o agente deveria fazer. O eval te força a ser honesto sobre o requisito antes de escrever uma linha de agente.

E versione esse arquivo. Golden set é código. Entra no git, cresce com o tempo, roda em CI/CD a cada mudança de prompt e a cada upgrade de modelo — exatamente como a Anthropic recomenda rodar evals "a cada mudança no agente e a cada troca de modelo".

Passo 2 — Meça por etapa, não só o resultado final

Aqui mora o pulo do gato. Se você só mede a resposta final, não sabe onde o agente erra. Quebre a avaliação nas três etapas que todo agente tem.

Recuperação (retrieval). O agente trouxe o contexto certo? Duas métricas que a LangChain separa bem: context precision (os documentos recuperados eram relevantes?) e faithfulness (a resposta bate com o que foi recuperado, ou o modelo inventou?). Recuperação ruim envenena tudo que vem depois. Se o contexto está errado, a resposta certa é coincidência.

Decisão de tool (trajetória). O agente chamou a ferramenta certa, com os argumentos certos, na ordem certa? A trajetória é "a sequência exata de mensagens, incluindo as chamadas de ferramenta" (LangChain). Você compara a trajetória real com a esperada. E não precisa ser sempre estrito — dá pra escolher o rigor:

strict     → mesmas ferramentas, mesma ordem, idênticas
unordered  → mesmas ferramentas, ordem livre
superset   → chamou as necessárias + extras tolerados
subset     → só as necessárias, penaliza chamada desnecessária

Use subset quando custo importa (cada tool call desnecessária é dinheiro e latência). Use unordered quando a ordem não muda o resultado. Comparar trajetória assim é determinístico, rápido e barato — não precisa de LLM nenhum pra rodar.

Resposta final. Só depois de validar recuperação e decisão é que a resposta final faz sentido medir. E meça também o custo da jornada, não só o acerto. A Anthropic sugere rastrear n_turns, n_toolcalls, n_total_tokens e latência. Um agente que acerta gastando 12 chamadas e 30 segundos não é "bom" — é caro.

Sobre o número de acerto, vale entender a família pass:

• pass@1 — acertou na primeira tentativa. É o que importa pra código e pra maioria dos fluxos.
• pass@k — acertou em pelo menos uma de k tentativas. Otimista demais pra produção.
• pass^k — acertou em todas as k tentativas. Esse é o número que importa quando o agente fala com cliente: mede consistência, não sorte (Anthropic).

Passo 3 — LLM como juiz, com as duas mãos no freio

Tem resposta que não dá pra comparar com string. "O tom estava adequado?", "a explicação foi clara?" — aí entra o LLM como juiz: um modelo avaliando a saída de outro. É flexível e escala. E é cheio de armadilha.

Os vieses são documentados e teimosos: position bias (favorece a resposta que vem primeiro), verbosity bias (acha que resposta mais longa é melhor) e o clustering de notas — o juiz dá 6 e 7 pra quase tudo numa escala de 1 a 10, e quase nunca usa o 1 ou o 10 (survey de LLM-as-judge). Resultado: uma métrica que não distingue medíocre de excelente.

Pior ainda em agente: se você manda o juiz avaliar a cadeia de raciocínio (chain-of-thought), saiba que o CoT pode ser racionalização post-hoc — uma história que o modelo conta depois, que nem sempre reflete o raciocínio real (paper sobre gaming the judge). Julgar a "explicação" do agente pode te dar uma nota linda pra um raciocínio que não aconteceu.

Três travas que tornam o juiz utilizável:

1. Dê uma saída. Instrua o juiz a responder Unknown quando não tiver certeza, em vez de chutar uma nota. A Anthropic é explícita nisso: "dê ao LLM uma saída, como instruí-lo a retornar 'Unknown'".
2. Calibre com humano. O juiz precisa ser "fortemente calibrado com especialistas humanos". Você só sabe se o juiz funciona lendo as transcrições e as notas de muitas execuções, comparando com o que um humano diria.
3. Critério binário e específico. Em vez de "dê uma nota de 1 a 10", pergunte algo verificável.

Você é um avaliador rigoroso. Critério ÚNICO:
A resposta cita o valor correto da fatura (R$ 240)?

Responda apenas: SIM, NAO ou UNKNOWN.
Não justifique. Não considere tom, tamanho ou ordem.

Critério binário e específico mata position bias e verbosity bias de uma vez, porque não sobra espaço pro juiz "preferir" — ou citou o valor, ou não citou.

Limitações e onde você vai se queimar

Eval honesto não é eval perfeito. Saiba os limites antes de confiar demais no número.

• Golden set envelhece. O produto muda, o requisito muda, e casos antigos viram ruído. Revise o set periodicamente. Caso de teste obsoleto que "passa" te dá falsa confiança.
• Cobertura é uma ilusão confortável. 40 casos passando não cobrem o infinito de inputs reais. Trate o golden set como piso de qualidade, não teto. Toda falha nova de produção vira caso novo.
• LLM-as-judge não é grátis nem neutro. Cada julgamento é uma chamada de API com custo e com viés. Não use juiz onde uma comparação determinística resolve. Juiz é pra subjetivo, não pra "o valor está certo?".
• Métrica vira meta. No momento que a equipe começa a otimizar pro número do eval, o número descola da realidade. Mantenha o hábito de ler transcrições na mão. Nenhuma métrica substitui você lendo o que o agente realmente respondeu.

FAQ rápido

Quantos casos preciso pra começar? 20 a 50 tarefas de falhas reais, segundo a Anthropic. Comece pequeno e cresça com as falhas de produção. Esperar ter "o dataset perfeito" é como não começar.

Preciso de LangSmith, MLflow ou alguma plataforma? Não pra começar. Um arquivo JSON versionado, um script que roda o agente nos casos e compara trajetória + resposta já te dá um eval honesto. Plataforma ajuda a escalar e visualizar — é o que comparamos no guia de observabilidade de agentes de IA — mas não é pré-requisito.

LLM-as-judge ou comparação determinística? Determinística sempre que der — é barata, rápida e sem viés. Reserve o juiz pra critérios subjetivos (tom, clareza) e, mesmo aí, com saída "Unknown" e calibração humana.

Rodo o eval quando? Em CI/CD, a cada mudança de prompt e a cada upgrade de modelo. Trocar de versão de modelo sem rodar o golden set é apostar que "deve ter melhorado". Não aposte.

Conclusão

Avaliação de agentes de IA não é olhar três exemplos e sentir que tá bom. É golden set de falhas reais, métrica separada por etapa — recuperação, decisão de tool, resposta — e LLM como juiz usado com as duas mãos no freio. O número que você consegue dizer em voz alta é a diferença entre engenharia e torcida.

Comece hoje: pegue cinco falhas reais do seu log, transforme em casos com resposta esperada, e meça. Cinco já te mostram mais verdade que cem execuções felizes que você nunca conferiu.

E se você quer ver esse tipo de raciocínio aplicado na arquitetura inteira — não só o eval, mas como desenhar o agente, o contexto e a recuperação pra serem avaliáveis desde o começo — é exatamente o que a gente coloca na mesa no Workshop Arquitetando Soluções de IA, com código rodando e decisão de arquitetura na frente. O próximo passo do agente que funciona não é um prompt mais esperto. É um processo que prova que ele funciona.