O eval harness que uso para lançar agentes de IA sem medo

Atualizado em junho de 2026.

TL;DR: A razão pela qual consigo mudar um prompt ou trocar um modelo em um agente ao vivo sem prender a respiração é uma única coisa: um harness de avaliação. Um conjunto fixo de casos de teste avaliados, pontuados automaticamente — asserções rígidas onde consigo escrevê-las, um juiz LLM onde não consigo — executado antes de cada mudança. A pontuação se mantém, eu lanço. A pontuação cai, eu não lanço. O conjunto de testes não é sintético; é construído a partir de falhas reais de produção, então cada bug vira um teste de regressão permanente.

Leitura do operador: Ao longo de mais de 100 agentes, a diferença entre os que toco com confiança e os que me dão medo é se eles têm avaliações. Sem harness de avaliação, cada ajuste de prompt é uma aposta. Um harness de avaliação transforma “acho que isto está melhor” em “isto está mensuravelmente 4 pontos melhor e não quebrou nada”. É todo o destravamento.

Você não lançaria código sem testes. As pessoas lançam agentes sem avaliações o tempo todo e depois se perguntam por que um “minúsculo ajuste de prompt” quebrou a produção. Um harness de avaliação é a suíte de testes para software não determinístico. Aqui está o que eu realmente executo.

Índice

Comece com um conjunto de testes construído a partir de falhas reais

O harness só é tão bom quanto seus casos de teste, e os melhores casos de teste vêm da produção, não da sua imaginação. Toda vez que um agente falha no mundo real, capturo a entrada exata (registro cada execução com um trace ID — veja como depurar um agente em produção) e a transformo em um caso de avaliação:

interface EvalCase {
  id: string;
  input: AgentInput;        // a entrada exata de produção
  expected?: string;        // verdade de referência, quando há uma
  assertions: Assertion[];  // checagens rígidas que devem passar
  rubric?: string;          // para o juiz LLM, quando a saída é aberta
}

Duas práticas importam aqui. Puxe da produção, para que suas avaliações testem o que realmente quebra, não o que você imaginou que poderia. E cubra o leque — o caminho feliz, os casos extremos, as entradas adversariais e as entradas vazias/malformadas que causam falhas silenciosas. Um conjunto de testes de 30 a 50 casos bem escolhidos pega muito mais do que 500 preguiçosos. Prefiro ter 40 casos que representem cada um um modo de falha real do que mil que testem todos o mesmo caminho fácil.

Pontue primeiro com asserções, depois com um juiz LLM

Nem toda saída precisa de um modelo para avaliá-la. Recorro ao avaliador mais barato que funcione.

Asserções rígidas para tudo o que é estruturado. A saída faz parse como JSON válido? Contém o campo obrigatório? A data extraída está dentro do intervalo? Chamou a ferramenta certa com os argumentos certos? Essas são determinísticas, gratuitas e inequívocas — escreva quantas conseguir.

const assertions: Assertion[] = [
  (out) => isValidJSON(out),
  (out) => parse(out).category in ALLOWED_CATEGORIES,
  (out) => parse(out).confidence >= 0 && parse(out).confidence <= 1,
];

Um juiz LLM para o resto aberto — tom, utilidade, “isto realmente respondeu à pergunta”. Aqui você dá a um modelo a entrada, a saída e uma rubrica, e pede que ele pontue. Duas regras mantêm o juiz honesto: torne a rubrica específica (uma escala de 1 a 5 com âncoras descritas vence “avalie a qualidade”), e use um modelo forte como juiz — julgar é uma tarefa de raciocínio, então este é um lugar onde pago com prazer pelo Sonnet mesmo quando o próprio agente roda no Haiku conforme a matemática de custos. Uma rubrica vaga ou um juiz fraco te dá ruído que parece sinal.

Execute o harness antes de cada mudança

O harness existe para responder a uma pergunta: esta mudança tornou o agente melhor ou pior? Então o executo antes de cada edição de prompt, troca de modelo ou mudança de ferramenta.

# baseline na main
npm run eval -- --suite=booking-agent > baseline.json

# faça a mudança, depois reexecute
npm run eval -- --suite=booking-agent > candidate.json

# compare
npm run eval:diff baseline.json candidate.json

O diff mostra a pontuação agregada, o passa/falha por caso e — crucialmente — quais casos específicos regrediram. Um agregado que sobe enquanto três casos quebram silenciosamente não é uma melhoria; é uma troca que quero ver e aprovar, não uma que passa despercebida. Vigiar o diff por caso é como você evita “consertei uma coisa, quebrei outras duas”, o modo de falha que faz as pessoas terem medo dos próprios prompts.

Defina um portão de regressão e deixe-o bloquear

Assim que você confia no harness, ligue-o ao caminho para a produção como um portão. Minha regra é direta: uma mudança que derruba a pontuação abaixo do limiar da baseline não é lançada. Não “vou ver isso depois” — está bloqueada, igual a um teste de CI que falha.

const PASS_THRESHOLD = 0.90; // 90% dos casos devem passar
if (candidate.passRate < PASS_THRESHOLD || candidate.passRate < baseline.passRate) {
  throw new Error(`Eval regression: ${candidate.passRate} < ${baseline.passRate}`);
}

É isso que converte as avaliações de um luxo opcional naquilo que permite você se mover rápido. O portão é o que torna “lançar sem medo” literalmente verdadeiro: o pior cenário para uma mudança ruim é uma execução de avaliação em vermelho, não um incidente de produção. E como o conjunto de testes cresce toda vez que algo quebra, o portão fica mais rígido e mais protetor ao longo do tempo, por conta própria.

Considere o não determinismo na pontuação

Uma sutileza que faz as pessoas tropeçarem: a mesma entrada pode pontuar de forma diferente entre execuções porque o modelo amostra de modo distinto. Se você executa cada caso uma única vez, verá regressões fantasma — um caso que “quebrou” e que na verdade é só ruído de amostragem.

Duas mitigações. Execute as avaliações a temperature: 0 para reduzir a variância (não a eliminará por completo). E para os casos que você viu oscilar, execute-os N vezes e pegue a taxa de aprovação, não um único passa/falha. Um caso que passa 9 de 10 está em melhor forma do que um que passa 5 de 10, mesmo que ambos possam mostrar uma única execução verde. É o mesmo princípio de volume-sobre-anedota que uso ao depurar falhas intermitentes — uma execução é uma opinião, cinquenta execuções são dados.

Feche o ciclo com monitoramento de produção

O harness de avaliação testa contra casos conhecidos. A produção lança casos inéditos. Então o ciclo é: monitore o comportamento ao vivo, capture um novo modo de falha, transforme-o em um caso de avaliação, conserte-o, e agora ele está permanentemente protegido. O lado do monitoramento — rastrear a taxa de sucesso, a validade da saída e o custo por execução no tráfego ao vivo — é o que abordo em como meço se um agente de IA está realmente funcionando. Avaliações e monitoramento são duas metades do mesmo sistema: o monitoramento encontra os bugs, as avaliações garantem que eles permaneçam mortos.

Esse ciclo de feedback é o verdadeiro produto. Qualquer conjunto de avaliação isolado fica obsoleto; um processo que converte cada falha de produção em um teste permanente fica mais forte a cada semana. É assim que um agente passa de “assustador de tocar” para algo que vou refatorar numa tarde de sexta-feira sem pestanejar.

Perguntas frequentes

O que entra em um conjunto de avaliação para um agente de IA?

Entradas reais de produção transformadas em casos avaliados — caminho feliz, casos extremos, entradas adversariais e malformadas — cada um com asserções rígidas e, para saídas abertas, uma rubrica de juiz LLM. De 30 a 50 casos extraídos de falhas reais vencem centenas de sintéticos que testam todos o caminho fácil.

Devo usar um LLM para avaliar as saídas do agente?

Use asserções rígidas sempre que a saída for estruturada (JSON válido, campo correto, chamada de ferramenta certa) — são gratuitas e determinísticas. Reserve um juiz LLM para qualidades abertas como tom e utilidade, com uma rubrica específica e um modelo juiz forte para obter sinal, não ruído.

Como impeço uma mudança de prompt de quebrar a produção silenciosamente?

Execute o harness de avaliação antes de cada mudança e faça o diff contra uma baseline, observando as regressões por caso, não apenas a pontuação agregada. Depois condicione os deploys ao resultado para que qualquer mudança que caia abaixo do limiar da baseline seja bloqueada como um teste que falha.

Como lido com o não determinismo nas avaliações?

Execute a temperatura 0 para reduzir a variância e, para os casos que oscilam, execute-os várias vezes e pontue a taxa de aprovação em vez de uma única execução. Um caso que passa 9 de 10 vezes é mais saudável do que um que passa 5 de 10, mesmo que uma única execução mostre ambos verdes.