Seu agente não tem avaliação? Então você não sabe se ele funciona — o que é um eval harness

Testar LLM "no olho" não escala. Um eval harness transforma "acho que melhorou" em "a suíte passou de 82% pra 89%". Montei um com 5 peças e ele virou o portão de "pronto" dos meus agentes em produção.

Você mexe no prompt, roda uns 3 exemplos na mão, parece melhor, sobe. Duas semanas depois descobre que quebrou um caso que funcionava. Sem avaliação sistemática, todo deploy é fé — e fé não é engenharia.

🎯 O problema: "no olho" não escala

LLM é probabilístico. A mesma entrada pode gerar saídas diferentes, e uma mudança de prompt que melhora 5 casos pode piscar 3 outros que você nem testou. Rodar exemplos na mão te dá uma amostra minúscula e enviesada — você testa o que lembra, não o que importa.

O que engenharia de verdade exige: rodar make eval e receber um número. Repetível, automático, comparável entre versões.

🪝 O que é um eval harness

Harness é a infraestrutura que roda avaliações de forma repetível. No meu motor de propostas ele tem 5 peças — e a graça é que o esqueleto é reusável entre projetos.

classDiagram
    class Caso {
        +id
        +input
        +expectativa
    }
    class Dataset {
        +casos
        +goldens
    }
    class Runner {
        +roda_sistema()
        +isola_erro()
    }
    class Comparador {
        +compara(saida, esperado)
    }
    class Reporter {
        +PASS_FAIL_ERR()
        +exit_code()
    }
    Dataset --> Caso
    Runner --> Dataset
    Comparador --> Runner
    Reporter --> Comparador

Traduzindo: o Dataset guarda os casos e suas respostas certas (os goldens). O Runner roda o sistema sob teste e isola erros. O Comparador confronta a saída com o esperado. O Reporter cospe PASS/FAIL/ERR e um código de saída. Simples — e mortal quando falta.

💡 A peça que muda por tipo de pergunta: o comparador

O esqueleto é sempre o mesmo; o comparador é que se especializa. Três sabores:

Pergunta que você faz	Comparador	Métrica
"Minha mudança quebrou algo?"	Igualdade exata vs golden	PASS/FAIL
"O agente achou tudo que devia?"	Matching de conjuntos	Precisão / Recall
"Modelo A ou B é melhor?"	Critério / qualidade	Qualidade × latência × custo

💡 O harness é reusável; o comparador é que muda. Escolha o comparador pela pergunta, não o contrário.

📚 O que a teoria diz

Chip Huyen (AI Engineering) coloca avaliação como o grande problema da engenharia de IA — justamente porque saída aberta não tem gabarito exaustivo. A saída dela é a mesma que uso: quando dá pra estruturar a resposta (um JSON, uma classificação), você transforma o problema aberto num fechado, e aí consegue medir.

Michael Albada (Building Applications with AI Agents) trata o eval como parte da resiliência e do aprendizado contínuo: sem um laço que meça, o agente repete os mesmos erros pra sempre. E aponta o antipadrão que eu levo a sério — nunca regrave o golden só pra passar. Se um caso adversarial quebrou, é o sistema que deixou passar lixo, não o teste que está errado.

⚠️ O ponto cego honesto

⚠️ Harness testa o que você codificou como golden. Ele não descobre problemas que você nunca imaginou — cobre regressão, não o desconhecido. E o falso-negativo (o caso ruim que você não colocou na suíte) é invisível por definição.

Por isso o dataset é vivo: todo bug que escapa em produção vira um caso novo no harness. O harness não substitui pensar nos casos — ele garante que, uma vez pensados, eles nunca mais quebrem em silêncio.

🏁 O que fica

Antes de otimizar seu agente, pergunte: "como eu vou saber se melhorei?" Se a resposta é "vou rodar uns exemplos na mão", você está adivinhando. Monte as 5 peças, defina seus goldens, e transforme "acho que melhorou" em um número que a suíte te dá.

---

Você tem eval automatizado nos seus agentes, ou ainda testa no olho antes de subir? E se tem — usa qual comparador? Conta aí.