Engenharia de Avaliação: o passo que transforma um modelo de US$ 200 em um sistema de US$ 200.000 (construção completa)

Todos estão alugando o mesmo cérebro agora.

O modelo que você pode ter por algumas centenas de reais por mês é, mais ou menos, o mesmo modelo que uma empresa com mil engenheiros está usando. Isso era para nivelar tudo. Em vez disso, fez a distância entre duas equipes alugando o cérebro idêntico ser maior do que a distância entre dois modelos.

Um agente de viagens, do tipo software, respondeu a uma pergunta sobre uma viagem: uma taxa de câmbio com uma casa decimal, a temperatura da semana, o horário de funcionamento de um museu. Específico, limpo, com som de útil. Tudo inventado.

A ferramenta de busca tinha voltado vazia, e o modelo silenciosamente preencheu o buraco e entregou sua própria invenção como um fato que ele havia pesquisado.

Então a equipe mediu isso em 100 sessões reais e obteve dois números que nunca deveriam estar tão distantes.

O quão boas eram as respostas: 83,9%.

O quanto dessas respostas estava fundamentado no que as ferramentas realmente retornaram: 32,3%.

O agente escrevia lindamente e dizia a verdade cerca de um terço das vezes.

Ninguém percebeu, porque a escrita era a única parte que alguém olhava.

83,9% de qualidade de resposta contra 32,3% de fidelidade, na mesma execução

Mesmo agente, mesmo dia: a barra da esquerda é o que a demonstração mostra, a barra da direita é o que um cliente realmente recebe.

Um modelo melhor não teria pego isso. O que faltava era a camada que decide se uma resposta estava correta, e então faz algo com o veredito.

Essa camada é toda a distância entre uma IA que impressiona as pessoas e uma IA pela qual se paga. É a linha mais barata da pilha e a única que ninguém pode te vender, porque ela codifica sua própria definição de correto.

Este texto não é para ser lido superficialmente. Abra um terminal ao lado. A configuração começa com um único comando que você já possui, e termina em algo que parece irracional: pull requests que são mesclados sem ninguém os ler.

Antes de começarmos, siga-me no X e entre no meu canal do Telegram, onde publico mais conteúdo de IA todos os dias. Ambos são gratuitos.

X -

https://x.com/Argona0x Telegram -

https://t.me/+r0clI4-MMC03ZjAy

O que é engenharia de avaliação

Uma empresa executando agentes em produção disse a parte que ninguém fala em uma frase. Em versões sucessivas de seu agente, eles mudaram nenhum modelo, nenhum prompt, nenhum incentivo humano, apenas as avaliações — e as pontuações se moveram em todas as dimensões.

Mesmo cérebro. Examinador diferente. Produto melhor.

A conclusão deles depois foi mais direta: as avaliações deveriam estar no sistema desde o primeiro dia, não no nono mês.

Um termômetro te diz que a sala está fria. Um termostato liga o aquecimento.

Quase todo mundo que constrói com IA possui, no máximo, um termômetro: um painel, uma sensação, uma sexta-feira à tarde onde alguém rola os resultados e diz que parece pior do que na semana passada.

Engenharia de avaliação é a fiação que vai da leitura até o forno.

← termômetro contra termostato, com o veredito retornando ao gráfico

Toda a diferença é a seta de retorno à direita: o veredito volta para o gráfico e muda o que é executado em seguida.

Isso chegou em uma ordem fixa. Primeiro veio um agente em um loop, para que pudesse tentar, olhar o que voltou e tentar novamente. Depois, muitos agentes organizados como um grafo, para que trabalhos que nunca dependiam uns dos outros fossem executados lado a lado em vez de ficarem em fila.

Loops, depois grafos, depois avaliações.

https://x.com/Argona0x/status/2080626046903157126

O grafo foi a última atualização que te fez mais rápido. O juiz decide se essa velocidade valeu a pena.

Vinte agentes executando ao mesmo tempo, todos se reportando a um único juiz congelado, são vinte vezes mais lugares para uma resposta errada parecer completa.

É também a única parte do sistema que se torna mais valiosa a cada semana que você a executa. O modelo é um aluguel. O examinador é seu, e cada falha que você alimenta a ele fica lá permanentemente.

O que torna o preço de entrada estranho. O examinador custa quase nada para instalar, e o modelo que ele examina custa cerca de $200 por mês.

Passo 1 · O motor de avaliação que você já possui

Você assume que isso começa com uma plataforma: um contrato, um preço por assento, um trimestre de configuração antes do primeiro número útil.

Essa suposição é a razão pela qual a maioria das pessoas nunca constrói a camada, e ela deixou de ser verdadeira cerca de quatro semanas atrás.

O teste cego

1. Dois pesquisadores fizeram o teste honesto. Eles pegaram 100 rastros de produção reais de um agente de voz ao vivo, um especialista humano marcou cada falha manualmente, construiu uma taxonomia de 39 falhas rotuladas, depois escondeu os rótulos e entregou a mesma pilha para todos os sistemas de avaliação do mercado.

Encontre-os você mesmo.

A linha interessante não foi a vencedora:

1. Braintrust Loop: 87,2% das falhas sinalizadas por humanos foram recuperadas.
2. Codex no GPT-5.5 High: 84,6% de recall, 82,8% de precisão.
3. LangSmith: 79,5%.
4. Arize AX: 74,4% de recall, e a precisão mais limpa do grupo, com 91,0%.

Um agente de codificação geral, em uma assinatura que você já paga, ficou acima de duas plataformas de avaliação dedicadas. Uma delas escreveu a conclusão claramente: você pode obter resultados semelhantes usando seu agente de codificação.

Então as plataformas fizeram algo mais estranho do que perder. Elas se moveram.

Em quatro semanas, quatro fornecedores de avaliação enviaram sua expertise como uma habilidade instalada no agente de codificação de outra pessoa: LangChain em 22 de julho, Galileo, AWS sob Apache 2.0, e Arize colocando sua extração de rastros em habilidades voltadas para, nas palavras deles, seu agente de codificação favorito.

Ninguém contou esses quatro como um único movimento.

É uma categoria se desempacotando no terminal que você já tem aberto.

Instalando o examinador

Instalar tudo leva três linhas.

1npx skills add langchain-ai/langchain-skills --skill '*' --yes --global
2npx skills add langchain-ai/langsmith-skills --skill '*' --yes --global
3uv tool install evalkit --from git+https://github.com/awslabs/Agent-EvalKit.git

Dentro do Claude Code, a mesma coisa se instala como um plugin:

1/plugin marketplace add langchain-ai/langchain-skills
2/plugin install langchain-skills@langchain-skills

← execução real no terminal: as habilidades são instaladas, o evalkit init cria a estrutura da pasta

Uma execução real em uma máquina real: as habilidades são salvas como arquivos globais, e evalkit init monta a pasta onde sua avaliação vai viver.

Dois detalhes ali valem mais do que os comandos.

1. Dois repositórios, dois trabalhos: langchain-skills constrói as avaliações, langsmith-skills puxa as execuções reais de produção para construí-las. Quase todo mundo instala o primeiro, depois se pergunta de onde vem o material.
2. Não é um recurso do Claude Code: essas habilidades seguem a especificação de habilidades abertas, então os arquivos idênticos carregam no Codex, Cursor, Windsurf e Goose.

O kit da AWS é executado em seis comandos, cada um uma fase escrevendo em uma pasta eval/ que a próxima lê:

1evalkit init my-agent-evaluation
2# then, inside your coding agent:
3/evalkit.plan Evaluate my agent at ./my_agent for grounding and tool accuracy
4/evalkit.data
5/evalkit.trace
6/evalkit.run_agent
7/evalkit.eval
8/evalkit.report

O último comando é o que vale toda a configuração. /evalkit.report entrega recomendações priorizadas apontando para locais específicos em seu código.

O examinador está instalado. Agora ele precisa ser autorizado a fazer algo.

Passo 2 · Faça a pontuação mudar a próxima aresta

Você vai construir sua primeira avaliação, obter um número, olhar para ele e sentir que nada aconteceu.

Essa sensação está correta. Um número em um relatório não tem caminho de volta para a execução que ele mediu.

Uma linha corrige toda a disciplina, e ela pertence a um fundador de 21 anos em Tóquio com 258 seguidores, cujo post sobre isso recebeu dois likes:

Uma pontuação que nunca muda o comportamento é análise. Uma avaliação que muda a próxima aresta é engenharia.

A fiação dele são seis regras. Cada uma pega um veredito e faz algo estrutural na execução em andamento:

1low context recall   → reject the handoff
2bad tool use         → retry or swap the node
3hallucination        → quarantine the branch
4schema failure       → block the edge
5compliance risk      → route to human review
6verified completion  → terminate the run

← seis vereditos, seis ações estruturais na execução em andamento

Cada uma dessas seis é uma decisão de roteamento que o grafo executa. A avaliação orienta a execução em pleno voo, uma aresta de cada vez.

Regras para o próprio juiz

O examinador precisa de sua própria higiene, e quase ninguém configura essa parte corretamente.

1. Julgue de outra família: um modelo reconhece sua própria escrita e a nota de forma mais branda quando o faz. Uma equipe de avaliação executa Sonnet como o juiz para a saída gerada por Haiku, de propósito. Uma linha no X diz isso em menos palavras: mesma família gera e avalia, então os pontos cegos são compartilhados.
2. Escreva a rubrica como uma linha: a forma funcional é literalmente Aprovado se [o resultado bem-sucedido observável independentemente]. Um veredito primário, nunca um pacote de pontuações proxy.
3. Divida o trabalho por tipo: o juiz decide as chamadas semânticas, o código simples decide as objetivas. O teste passou, o arquivo existe, o estado mudou.
4. Nunca recompense a forma de uma resposta: a regra escrita na habilidade proíbe pontuar com base no comprimento da resposta, palavras-chave, contagem de citações, redação exata, contagem de chamadas de ferramenta ou similaridade com uma referência. Recompense a forma e o agente aprende a forma.
5. Fixe o juiz e registre sua versão: um examinador que atualiza silenciosamente torna todas as pontuações antes e depois incomparáveis, e você não vai notar por um mês. A fixação da versão é a que as pessoas pulam, e a que torna um mês de pontuações ilegíveis depois.

Otimize contra um juiz por tempo suficiente e o agente aprende a parecer certo em vez de estar certo.

Agora a pontuação tem para onde ir. O próximo problema é de onde vêm os bons testes, porque inventá-los em uma mesa é a razão pela qual o primeiro conjunto de todo mundo é inútil.

Passo 3 · Transforme uma execução falha em uma avaliação

Testes que você inventa da imaginação te protegem de falhas que você já imaginou.

As que custam dinheiro estão sentadas em seus logs agora mesmo, carregando um carimbo de data/hora.

O loop inteiro tem cinco passos:

1mine traces -> identify a failure -> build an eval -> improve the agent -> rerun

De onde vêm os testes

O primeiro passo carrega todo o peso. A habilidade que faz isso profissionalmente nomeia quais execuções puxar, e começa com 25 rastros completos, nada mais, escolhidos de modo que o comportamento bom e o ruim fiquem lado a lado:

1. Uma solicitação normal que foi concluída: sua linha de base para como é o funcionamento.
2. Uma solicitação que o usuário confirmou: o raro rastro onde você sabe que a resposta era boa.
3. Uma solicitação que o usuário corrigiu ou reformulou: a correção é o rótulo, de graça.
4. Uma execução com uma chamada de ferramenta falha, vazia ou repetida: repetição significa um loop, vazio significa que uma resposta inventada está chegando.
5. Uma execução com uma falha externa: um timeout ou um limite de taxa, onde a única coisa testada é como seu agente se comporta quando o mundo diz não.

Cada uma é escrita em quatro linhas, e este modelo é a parte que vale a pena roubar:

1Observed behavior: what the user asked and what the agent actually did
2Comparison:       what worked and what did not
3Attribution:      agent behavior, dependency behavior, or unclear
4Eval candidate:   the capability to preserve or improve

Atribuição é onde os iniciantes perdem uma semana.

A mesma consulta chamada duas vezes com argumentos idênticos é um loop no seu agente. Um 429 voltando é um limite de outra pessoa, e só se torna sua avaliação se seu agente deveria se recuperar disso.

Da descoberta à pasta

Então a descoberta se torna uma pasta, e a pasta é o formato que a ferramenta executa:

1evals/<task-id>/
2├── task.toml
3├── instruction.md
4├── environment/
5└── tests/

← 25 rastros → uma falha → uma pasta de tarefa Harbor: o que o agente vê, o que fica escondido

Uma capacidade por pasta. A instrução e o ambiente são visíveis para o agente sendo testado. O resultado esperado, a rubrica e as credenciais do juiz não são, e essa separação é a única razão pela qual a pontuação significa algo.

Três regras impedem as falhas que fazem as pessoas desistirem:

1. Nunca trate a resposta gravada como verdade: o rastro te diz o que seu agente fez, nunca o que ele deveria ter feito. Pegue o gabarito dos testes, registros de origem, política, estado conhecido ou de uma pessoa.
2. Teste o teste antes de confiar nele: entregue ao verificador dois resultados falsos manualmente, um claramente correto e outro plausível, mas errado. Se algum deles for para o lado errado, a rubrica está quebrada, não o agente.
3. Cuidado com o ambiente entregando a resposta: se a configuração entrega o resultado antes do agente alcançar a ferramenta que deveria usar, a tarefa passa para sempre e não mede nada.

Qualquer coisa que custa dinheiro ou escreve em produção é simulada em vez de chamada, para que o conjunto seja executado quantas vezes você quiser sem uma conta.

Uma instrução inicia tudo isso, no agente que você já tem aberto:

1Use the eval-engineering skill.
2
3Map this repository's agent: entrypoint, tools, backing data, and what a good
4result looks like. Then read the 25 traces in ./traces and propose two or three
5eval candidates grounded in what actually failed there.
6
7Recommend one. Do not implement until I choose.
8Build it as a Harbor task under evals/, keep the rubric and expected outcome
9hidden from the target, and test the verifier on one passing and one plausible
10wrong result before the real run.

A etapa de entrevista é deliberada. A equipe que escreveu a habilidade descobriu que questionar o usuário supera a geração única todas as vezes, pela simples razão de que a definição de correto vive na sua cabeça e em nenhum lugar do modelo.

Execute algumas vezes e toda falha deixa de ser um incidente e se torna um teste permanente.

Passo 4 · Deixe o grafo mesclar seu próprio trabalho

Todo pull request que um agente abre cai no mesmo lugar: uma fila humana.

Você se torna o gargalo da sua própria automação, e a frota que você construiu opera na velocidade de um revisor cansado.

A saída não se parece em nada com confiar mais no modelo. Quando um agente abre um pull request, quatro sinais já estão disponíveis, e uma pontuação de confiança é calculada a partir deles no momento:

1. Resultado das proteções: uma aprovação ou reprovação determinística nos padrões de bloqueio. Nenhum modelo envolvido.
2. Trajetória de avaliação recente: como esta versão exata deste agente tem pontuado ultimamente.
3. Taxa de reversão histórica: com que frequência este agente, neste repositório, nesta classe de alteração, teve seu trabalho revertido antes.
4. Resultado do sandbox: foi executado.

Acima do limite, ele se mescla sozinho. Abaixo dele, um humano o recebe com o sinal de falha nomeado, para que a revisão comece no problema em vez de na linha um.

← quatro sinais → uma pontuação de confiança → mesclar-se sozinho, ou rotear para um humano

Três desses quatro são histórico e verificações determinísticas, e exatamente um deles toca no modelo.

Confiança em um agente é um cálculo atuarial.

O que você está construindo é um histórico com um preço nele, da mesma forma que uma seguradora constrói um, e ele fica mais preciso a cada semana, independentemente de os modelos melhorarem ou não.

Como é quando executa

Na mesma empresa que mudou nada além de suas avaliações, 19 de cada 20 pull requests no agente totalmente autônomo são mesclados sem envolvimento humano.

Entre os melhores agentes, cerca de três quartos do trabalho mesclado entra sem uma única edição humana, a taxa de reversão fica em dígitos únicos baixos, e somente as proteções rejeitam um em cada cinco pull requests antes que uma pessoa o veja.

Alguém executando este padrão em seus próprios repositórios colocou de uma forma que nenhum fornecedor faria:

Nos últimos 90 dias, aprovei e mesclei cerca de 1.500 pull requests. Não olhei para uma linha de código. Como posso colocar tanta confiança em agentes? Não confio neles nem um pouco. Também não confio na minha capacidade de revisar o código deles. Mas confio na minha capacidade de restringir o trabalho deles.

A restrição é o produto.

E o aviso que vale mais do que a fórmula vem de uma equipe que executou 285 iterações de uma base de código auto-melhorável e obteve 1.094 pull requests mesclados e zero regressões.

A própria linha deles é a que vale guardar: 38 testes verdes coexistiram com um produto completamente quebrado.

Um conjunto pode ficar todo verde enquanto o produto que ele protege desmorona, e é por isso que o loop tem que convergir para a especificação, e não para a pontuação.

Ative-o da maneira cuidadosa:

1. Execute-o em modo de sombra primeiro: o portão pontua todo pull request e não mescla nenhum deles, por pelo menos 4 horas de tráfego real.
2. Defina um limite de desvio de 2%: se o veredito automatizado e o veredito humano discordarem mais do que isso, o portão permanece fechado.
3. Amostre rastros a 1% a 5%: captura completa de tudo é um custo que você não precisa carregar.

Uma loja de duas pessoas onde toda alteração escrita por agente espera por um revisor pode assumir aproximadamente tanto trabalho quanto esse revisor consegue ler.

Com o portão fechado para a fatia arriscada e aberto para os 80% entediantes, as mesmas duas pessoas começam a cotar os contratos que costumavam recusar.

A conta do modelo não se move. Todo o resto sim.

Passo 5 · As avaliações para construir esta semana

Um conjunto que é muito lento ou muito vago nunca é executado, então esta é a parte para guardar.

Comece com três medições, não doze. As três que expuseram o agente de viagens são um padrão funcional para qualquer agente que chama ferramentas:

1. Fidelidade: a resposta está fundamentada no que as ferramentas realmente retornaram. Esta é a que estava em 32,3% enquanto todos os outros números no painel pareciam bons.
2. Precisão dos parâmetros da ferramenta: ferramenta certa, argumentos certos.
3. Qualidade da resposta: a saída é coerente e útil para a pessoa que perguntou.

Se seu agente envia código, pontue a alteração. As cinco dimensões usadas em produção em todo pull request: intenção e decisão, execução e artefato, completude e utilidade, instrução e limite, eficiência.

Escolha o tipo de conjunto de dados de propósito. Quatro existem: final_response para a resposta sozinha, single_step para uma decisão isolada, trajectory para todo o caminho que o agente percorreu, e RAG** para qualidade de recuperação.

Avaliar apenas a resposta final é como um agente alcança uma resposta correta através de uma sequência quebrada sem ninguém notar.

Dimensione-o para que permaneça vivo. Separe de 300 a 800 casos, e mantenha 500 deles sendo executados

em menos de 5 minutos.

Um conjunto que demora mais que uma pausa para o café deixa de ser executado.

As primeiras cinco avaliações, em ordem:

1. Resultado de ferramenta vazio: a ferramenta não retorna nada, e o agente tem que dizer isso em vez de inventar o número.
2. Chamada repetida: a mesma consulta com os mesmos argumentos duas vezes. Isso é um loop, e a avaliação reprova.
3. Recusa de limite: solicitado a algo fora de suas permissões, o agente recusa educadamente em vez de procurar um caminho alternativo.
4. Integridade da transferência: o que o nó anterior produziu é o que o próximo nó lê, sem nada inventado no meio.
5. Conclusão verificada: concluído significa que um sinal real diz concluído, nunca a própria palavra do agente.

← esta semana: três medições, um tipo de conjunto de dados, cinco avaliações (o cartão para salvar)

Três medições, um tipo de conjunto de dados, cinco avaliações. Isso é uma tarde de trabalho, e toda semana depois dela o conjunto vale mais do que valia na semana anterior.

As pessoas que vão primeiro

O modelo nunca foi a parte interessante. É um aluguel, idêntico para todos, e será substituído duas vezes antes do final do ano.

O que sobrevive a cada substituição é o examinador que você construiu ao redor dele: as falhas que você transformou em testes permanentes, as regras que permitiram que um veredito mudasse a próxima aresta, o histórico que permite que uma máquina mescle seu próprio trabalho.

Isso é o que decide se os $200 no extrato do seu cartão produzem uma demonstração ou produzem um negócio.

A maioria das pessoas vai voltar a rolar resultados numa sexta-feira e decidir que parece certo.

As que vão primeiro passam uma tarde conectando o termostato, e depois passam o próximo ano com um agente que não pode quebrar a mesma coisa duas vezes.

Três linhas resumem toda a disciplina:

1. Meça o caminho que o agente percorreu, nunca apenas a resposta em que ele parou.
2. Um veredito que não muda a próxima aresta é um relatório.
3. Qualquer falha que você não transformar em um teste permanente, você encontrará novamente.

Instale uma habilidade. Puxe 25 rastros. Construa uma avaliação hoje, e adicione uma toda vez que algo quebrar.

Se você quer se manter atualizado com tudo que está acontecendo em IA, siga-me no X e no Telegram:

X -

https://x.com/Argona0x Telegram -

https://t.me/+r0clI4-MMC03ZjAy