Evals Antes de Impressões: Como Saber se o Seu Agente Realmente Funciona

A armadilha da intuição

Você construiu um agente. Conversou com ele por 30 minutos. Pareceu inteligente. Você o lançou.

Três dias depois, um usuário relata que ele deu com confiança uma resposta errada a uma pergunta básica. Você testa novamente — agora funciona bem. Você dá de ombros. O modelo devia estar tendo um dia ruim.

Esta é a armadilha da intuição: usar impressões informais como seu sinal de qualidade. Funciona em escala de hobby. Falha no momento em que você tem usuários reais, dinheiro real ou riscos reais.

Os evals são a saída.

O que é um eval de verdade

Um eval é uma função que recebe um prompt mais o comportamento esperado e retorna uma pontuação. É isso. Não é necessária infraestrutura sofisticada para começar.

O eval mais simples que você pode escrever:

interface EvalCase {
  input: string;
  expected: string;
  check: (output: string) => boolean;
}

const cases: EvalCase[] = [
  {
    input: "What is 2 + 2?",
    expected: "4",
    check: (out) => out.includes("4"),
  },
  {
    input: "Summarize: 'The quick brown fox jumps over the lazy dog'",
    expected: "mentions fox and dog",
    check: (out) => out.toLowerCase().includes("fox") && out.toLowerCase().includes("dog"),
  },
];

async function runEvals(model: (prompt: string) => Promise<string>) {
  let pass = 0;
  for (const c of cases) {
    const output = await model(c.input);
    if (c.check(output)) {
      pass++;
      console.log(`✓ ${c.input.slice(0, 40)}`);
    } else {
      console.log(`✗ ${c.input.slice(0, 40)}`);
      console.log(`  Got: ${output.slice(0, 100)}`);
    }
  }
  console.log(`\n${pass}/${cases.length} passed (${Math.round(pass / cases.length * 100)}%)`);
}

Execute isso em cada alteração de prompt. Agora você tem um conjunto de regressão.

Os três tipos de verificação que você precisa

1. Correspondência exata — para saídas estruturadas, códigos, IDs, decisões sim/não. Binário. Rápido.

2. Verificação de conteúdo — para saídas em prosa onde a redação exata varia mas fatos-chave devem aparecer. "A saída menciona 'Paris'" é mais robusto do que "a saída é igual a 'Paris é a capital da França'".

3. Avaliação por modelo — para tarefas complexas onde você precisa de julgamento semântico. Pergunte a um segundo modelo (mais barato, mais rápido): "Esta resposta responde corretamente à pergunta? Responda SIM ou NÃO com um motivo." Isso escala para qualidade subjetiva, tom e cadeias de raciocínio.

async function modelGrade(output: string, criterion: string): Promise<boolean> {
  const verdict = await callModel(
    `Criterion: ${criterion}\nOutput: ${output}\nDoes the output meet the criterion? Reply YES or NO only.`
  );
  return verdict.trim().startsWith("YES");
}

O que avaliar primeiro

Se você está começando do zero, avalie nesta ordem:

1. Caminho feliz — as 5-10 entradas para as quais seu agente foi explicitamente projetado. Todas devem passar. Se não passarem, você não tem um agente funcional, você tem uma demo.

2. Casos extremos que você já viu falhar — qualquer coisa que quebrou durante os testes. Encode-os imediatamente. Cada bug é um caso de eval.

3. Entradas adversariais — entradas vazias, entradas malformadas, perguntas fora do domínio, tentativas de injeção de prompt. Seu agente precisa degradar graciosamente.

4. Conjunto de regressão — um conjunto fixo de 50-100 casos que você executa em cada alteração. Verde significa que você não quebrou nada. Vermelho significa que você tem uma decisão a tomar.

O fluxo de trabalho de eval

Alteração de prompt → Executar evals → Verificar delta de pontuação → Lançar se delta > limiar → Pronto

Seu limiar depende dos riscos. Um projeto de brinquedo pode aceitar -2%. Um agente de produção que lida com dados de clientes deve exigir +0% ou melhor. Defina isso explicitamente antes de começar para não tomar a decisão sob pressão quando sua pontuação cair 4% após um "pequeno" ajuste de prompt.

Ferramentas que vale conhecer

• Braintrust — execuções de evals, registro, comparação de modelos. Tem um nível gratuito generoso.
• Promptfoo — open-source, executa localmente, excelente para red-teaming.
• Langfuse — observabilidade mais eval, bom se você quiser rastreamento junto com pontuações.
• Script DIY — para agentes simples, um script TypeScript de 50 linhas frequentemente é suficiente. Não complique demais.

A verdade desconfortável

A maioria das falhas agênticas são falhas de prompt, não falhas de modelo. Você não precisa de um novo modelo. Você precisa saber em que seu prompt atual falha e corrigi-lo.

Os evals te dizem isso. A intuição não diz.

Construa o conjunto de evals antes de adicionar o próximo recurso. O seu eu futuro ficará grato.