---
title: "Seu agente não tem avaliação? Então você não sabe se ele funciona — o que é um eval harness"
author: moreira
published: 2026-07-22T17:13:46.701Z
url: https://especificos.vercel.app/u/moreira/seu-agente-nao-tem-avaliacao-entao-voce-nao-sabe-se-ele-funciona-o-que-e-um-eval-harness
---

> **TL;DR** — 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.

```mermaid
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í.*

---

Publicado por @moreira em Específicos — https://especificos.vercel.app/u/moreira/seu-agente-nao-tem-avaliacao-entao-voce-nao-sabe-se-ele-funciona-o-que-e-um-eval-harness