Harness engineering: o que separa um agente de demo de um agente de produção

Em março de 2026, o time de engenharia da LangChain pegou o próprio agente de código, que estava em 30º lugar no Terminal Bench 2.0, e o colocou em 5º. Não trocou o modelo. Mexeu só no que está em volta dele.

Dois meses depois, o SWE-Atlas, da Scale AI, mediu a mesma variável e concluiu o oposto: a escolha do harness é ruído dentro da margem de erro. O Opus 4.6 marca 2,5 pontos a mais rodando dentro do Claude Code do que num agente genérico, e o GPT 5.2 faz o caminho inverso.

As duas medições estão certas. Entender por que é a diferença entre um agente que impressiona na demo e um que aguenta a segunda-feira.

Harness engineering é a prática de projetar tudo que cerca o modelo num agente, de forma que o agente erre menos sem que o modelo mude. O harness é essa camada em volta: prompt de sistema, o conjunto de ferramentas que o agente pode chamar, a memória que ele carrega entre passos, os testes que rodam antes de ele dizer "pronto", os limites do que ele não pode fazer e a telemetria que registra o que aconteceu.

O termo veio de um lugar específico. Em fevereiro de 2026, Mitchell Hashimoto — cofundador da HashiCorp e criador do Terraform — publicou no blog pessoal a descrição de um hábito que tinha desenvolvido trabalhando com agentes: toda vez que o agente errava, ele não escrevia um prompt melhor. Ele modificava o ambiente para que aquele erro se tornasse estruturalmente impossível. Chamou isso de engineering the harness. Em semanas, OpenAI e Anthropic publicaram material expandindo a ideia.

A fórmula que ficou é curta: agente = modelo + harness.

A confusão mais comum é achar que isso é engenharia de prompt com nome novo. São coisas diferentes. Engenharia de prompt escolhe palavras. Harness engineering é escrever código e configuração: qual ferramenta existe, o que ela devolve quando falha, o que roda automaticamente antes do commit, o que o agente não consegue executar nem se quiser.

Se você já ajustou um CLAUDE.md que orienta o agente ou configurou hooks para garantir que algo sempre rode, já fez harness engineering. Só não chamava assim.

As duas medições estão certas porque não medem a mesma coisa.

A LangChain otimizou o harness do próprio agente e subiu 25 posições no Terminal Bench 2.0, em março de 2026, com o modelo intacto (Faros AI, 22 de maio de 2026, acesso em 27/08/2026). No mesmo material, a Faros relata que modelos abertos com harness otimizado igualaram ou superaram rotas de modelos frontier em 211 tarefas reais de engenharia.

O SWE-Atlas, da Scale AI, comparou modelos rodando dentro de harnesses diferentes e achou o contrário: a diferença fica dentro da margem de erro, e nem sequer aponta sempre na mesma direção — o Opus 4.6 vai melhor no Claude Code, o GPT 5.2 vai pior. O Latent.Space, ao resumir o achado, titulou a edição com a pergunta que o mercado prefere não fazer: "Is Harness Engineering real?"

Esse padrão já apareceu neste blog: o texto sobre Claude Code em produção abre com METR e Microsoft chegando a resultados opostos sobre ganho de produtividade. Medições sérias discordam quando medem coisas diferentes com o mesmo nome.

O que muda entre as duas colunas é o tipo de tarefa. O Terminal Bench mede tarefas de terminal com muitos passos encadeados. O SWE-Atlas compara desempenho em tarefas isoladas. É a mesma variável medida em dois horizontes diferentes, e o horizonte decide se o harness aparece ou some no ruído.

Quem leu só a manchete de que "harness engineering é o futuro" está com metade da informação. Quem leu só o SWE-Atlas e concluiu que não vale investir está com a outra metade. Passei uma semana achando que os dois estudos se anulavam, até olhar o que cada um tinha medido.

O harness importa em proporção ao número de passos que o agente precisa acertar seguidos.

O número que fecha o argumento: o acerto de um agente cai de 60% numa única rodada para 25% quando ele precisa acertar oito vezes consecutivas na mesma tarefa (Fiddler AI, 29 de abril de 2026, citando arXiv 2511.14136v1; acesso em 27/08/2026). Erro se acumula. A cada passo, a chance de o anterior ter saído torto entra na conta.

A aritmética de uma cadeia de agentes é ainda mais cruel: três agentes com 70% de acerto cada entregam 0,7 × 0,7 × 0,7 = 34% ponta a ponta. Ninguém precisa de um modelo ruim para chegar lá; basta encadear três bons.

<!-- [ORIGINAL DATA] -->

Antes de prometer prazo, faça essa conta para o seu caso. É uma potência simples: o acerto por passo elevado ao número de passos.

A leitura prática está na terceira linha. Uma ferramenta com 90% de confiabilidade passa por boa quando você a testa sozinha, e sobra 12% de uma tarefa de vinte passos. Para um agente entregar quatro em cada cinco tarefas longas, cada passo precisa acertar 99% das vezes. É esse número que a camada de verificação existe para comprar — cada teste que roda dentro do loop transforma um passo incerto num passo conferido.

É por isso que o SWE-Atlas não enxergou o harness. Em tarefa de um passo, o modelo carrega quase todo o resultado. A partir do quinto ou oitavo passo, o que decide é se existe alguém conferindo o trabalho no meio do caminho.

E é por isso que a taxa de fracasso em produção é o que é. A Fiddler estima entre 70% e 95%, dependendo de como se mede, e sustenta o número com três referências independentes: no benchmark WebArena, um agente com GPT-4 completou 14,41% das tarefas ponta a ponta contra 78,24% de desempenho humano; a Carnegie Mellon mediu falha em cerca de 70% das tarefas de escritório; e o MIT relatou que 95% dos pilotos de IA generativa não produziram impacto mensurável no resultado financeiro.

As duas primeiras camadas dão o maior retorno, e nessa ordem.

Ferramentas definem o teto. Um agente só é tão capaz quanto o conjunto de coisas que ele consegue chamar, e tão confiável quanto o que essas ferramentas devolvem quando falham. Uma ferramenta que retorna Error sem dizer o que aconteceu força o agente a adivinhar, e adivinhação em passo três vira desastre no passo seis. Mensagem de erro é interface de agente. Conectar uma ferramenta é a parte fácil, e o guia de MCP na prática cobre essa metade; desenhar o que ela devolve é a que decide o resultado.

A diferença aparece em uma linha. Uma ferramenta de leitura de arquivo que falha assim:

Error: ENOENT

deixa o agente com três hipóteses e nenhuma pista: o caminho está errado, o arquivo não existe ou ele não tem permissão. Ele vai tentar as três, gastando passos. A mesma falha, escrita para quem vai ler:

Arquivo não encontrado: lib/posts.ts
O diretório lib/ existe e contém: posts-meta.ts, markdown.ts, site.ts
Você quis dizer lib/posts-meta.ts?

O agente corrige na primeira tentativa. Custou três linhas a mais no tratamento de erro e economizou dois passos — que, pela aritmética da seção anterior, é a diferença entre 60% e 25%.

Verificação é a camada que quase ninguém implementa e que muda mais o resultado. A ideia é simples: o build, os testes e o lint rodam dentro do loop, não depois que o agente disse que terminou. Sem isso, "pronto" significa apenas que o modelo parou de gerar tokens.

O dado da Faros mostra o tamanho do efeito: modelos abertos com harness otimizado igualaram ou superaram rotas de modelos frontier em 211 tarefas reais. A camada de verificação compensou diferença de modelo.

Há um limite importante nessa camada, e ele é estrutural: o agente não consegue revisar o próprio trabalho com a mesma confiabilidade com que executa. Quem verifica precisa ser o ambiente, com build, teste e lint. Não outra passada do mesmo modelo sobre o texto que ele acabou de escrever.

Quando a tarefa é grande demais para um loop só, delegue parte dela a um subagente com contexto próprio.

Por baixo dessas duas camadas existe uma decisão de infraestrutura que costuma ser tomada por inércia: como a ferramenta chega até o agente. MCP, A2A e WebMCP resolvem problemas diferentes e estão em maturidades muito diferentes, e escolher errado aqui custa reescrita depois.

Contexto é o que o agente sabe. Guardrail é o que ele não pode fazer. As duas coisas costumam ser confundidas e resolvem problemas opostos.

Na camada de contexto entram a indexação do que existe, o histórico da sessão e o que sobrevive entre sessões. O modo de falhar é conhecido: o agente esquece no meio da tarefa e recomeça com informação pela metade. Organizar isso tem quatro pilares, e eles se resolvem em ordem.

Memória é a parte do contexto que sobrevive à sessão, e o instinto de guardar tudo é o erro mais caro dessa camada. O que merece persistir é decisão e restrição: por que uma biblioteca foi descartada, qual convenção o repositório segue, o que já foi tentado e não funcionou. Transcrição de conversa cresce sem limite e empurra para fora da janela o que importa.

Como recuperar o que ficou de fora é a pergunta que mudou de resposta nos últimos dois anos. Com janelas de contexto grandes, recuperação deixou de ser obrigatória em toda tarefa. Ela continua ganhando por custo em boa parte dos casos.

Guardrails são limites duros — sandbox, teto de orçamento, aprovação humana para ação irreversível, lista do que nunca executa. A diferença para contexto é que guardrail não depende de o modelo concordar. É a única camada que continua valendo quando o modelo interpreta a instrução de outro jeito, e é o assunto de permissões e auto mode.

A lista inicial é curta e quase sempre a mesma: git push --force, rm -rf, migração de banco, qualquer chamada que gaste dinheiro. Cada item ou pede confirmação humana ou não existe no conjunto de ferramentas. Escrever "tome cuidado com force push" no prompt cobre o caso em que o modelo leu a instrução; retirar o comando cobre o resto.

A referência para desenhar essa camada hoje tem data: em 9 de dezembro de 2025, a OWASP publicou o Top 10 for Agentic Applications, construído com mais de 100 especialistas, catalogando as dez classes de risco específicas de agentes que planejam, guardam memória, chamam ferramentas e agem com autoridade delegada (OWASP GenAI Security Project, acesso em 27/08/2026). É a lista contra a qual desenhar guardrail hoje, e as dez ameaças estão destrinchadas uma a uma.

Uma delas não sai da lista por engenharia: injeção de prompt não tem correção definitiva, o que empurra a defesa para o desenho do sistema em vez do filtro de entrada. E a autoridade que o agente carrega para agir precisa de dono: a credencial que ninguém revoga é o buraco mais comum dessa camada em 2026.

Sem telemetria você não sabe se o harness melhorou. Sabe que a última tarefa deu certo, e só.

O problema é que bug de agente não se reproduz. A mesma entrada não produz a mesma saída, então o rastro precisa existir antes do erro, não depois. Isso significa registrar o que o agente pediu, o que a ferramenta devolveu, quantos passos ele levou e onde recomeçou.

Um registro que serve para investigar tem cinco campos: a tarefa como ela chegou, cada chamada de ferramenta em ordem, o retorno bruto de cada uma, o número de passos até a conclusão e o ponto em que o agente trocou de estratégia. O quinto é o que quase ninguém guarda e o que mais explica. Quando o agente abandona um caminho e tenta outro, uma de duas coisas aconteceu: a ferramenta devolveu algo inútil ou o contexto encheu.

Contagem de passos merece atenção separada, porque é o número que se move antes de todos os outros. Uma tarefa que levava seis passos e passou a levar onze está avisando que alguma ferramenta começou a responder pior, ou que a janela está no limite. A taxa de acerto cai depois disso, e quando ela cai a semana já foi.

As métricas que importam ficam do lado do negócio. A Faros propõe quatro: dólar por PR mergeado, tempo até o merge, taxa de acerto de primeira e defeitos que escapam para produção. Nenhuma fala de tokens ou de latência, e é por isso que servem para decidir se vale continuar investindo.

Telemetria diz o que aconteceu. Dizer se está bom é outro problema, e exige avaliar o agente na tarefa real em vez de confiar na impressão da última sessão. Quando o avaliador é outro modelo, vale saber quando confiar na nota que ele dá.

Se o assunto for a conta no fim do mês, o custo por padrão de uso muda mais do que a escolha do modelo. E, na API em escala, o dinheiro vaza em lugares que o dashboard não mostra.

<!-- [PERSONAL EXPERIENCE] -->

Entre 21 e 27 de agosto de 2026, este blog publicou 23 artigos escritos com agente. Vale o aviso: é operação, com N pequeno e o viés de quem construiu. Ainda assim mostra a disciplina do Hashimoto funcionando na prática: toda vez que o agente errou, a correção foi para o ambiente.

O harness tem as cinco camadas. Ferramentas: acesso ao repositório, ao navegador e ao build. Verificação: npm test, ESLint, tsc e next build rodando dentro do loop, mais um checklist de 16 itens que confere cada post publicado — H1 único, canonical, capa com alt, JSON-LD na data certa, entrada no sitemap. Contexto: um AGENTS.md na raiz. Guardrails: permissões explícitas e confirmação para ação irreversível. Observabilidade: Lighthouse e varredura de rotas a cada build.

O que ele deixou passar é a parte útil.

Os ScrollTriggers nasciam medidos antes das fontes carregarem. As fontes web do site usam display: swap. Quando elas entram, cada bloco de texto muda de altura e as posições calculadas viram números velhos: seções fixadas soltavam no lugar errado e uma galeria passava por cima do terminal. Nenhum teste pegava isso, porque o build passava. A correção foi ScrollTrigger.refresh() depois de document.fonts.ready, mais uma remedição ao voltar de aba em segundo plano. Erro estruturalmente impossível de repetir.

O srcSet das capas declarava 1600w para arquivos de 1200px. O descritor w é o número com que o navegador escolhe qual imagem baixar, e ele estava contando com pixels que não existiam em 20 das 35 capas. Ninguém notou por semanas: a página parecia certa. Só apareceu quando a verificação passou a comparar o naturalWidth real contra o declarado.

E a otimização que quebrou a página. Numa tentativa de melhorar o tempo de bloqueio, adiei o carregamento de três componentes para quando a thread ficasse ociosa. O ganho era de laboratório; o efeito real foi quebrar a ordem de inicialização — pins deslocados, seções invisíveis. Revertido por inteiro. Ficou a regra: otimização que muda ordem de montagem precisa de verificação visual, não só de métrica.

Cinco passos para adicionar harness a um projeto que já roda, na ordem de retorno: do que rende no primeiro dia ao que só se paga depois de meses.

1. Escreva o arquivo de contexto. AGENTS.md ou CLAUDE.md na raiz, com o que é verdade sobre o projeto e não está óbvio no código: qual gerenciador de pacotes, qual comando roda os testes, quais diretórios são gerados e ninguém edita à mão, qual convenção de commit o repositório segue. É a correção mais barata que existe e a única que rende já no primeiro dia. O desperdício comum é encher esse arquivo com o que o agente deduz sozinho lendo o package.json.

2. Coloque a verificação dentro do loop. Se o agente pode rodar o teste, ele deve rodar antes de dizer que terminou. Na prática é um comando só, encadeando o que já existe no projeto: npm test && npx tsc --noEmit && npm run lint. O teste já estava lá; o ganho vem de o agente ver a falha enquanto ainda tem na cabeça o que mudou. Hooks fazem isso sem depender de o modelo lembrar.

3. Feche o que não pode acontecer. Um guardrail contra ação irreversível vale mais do que dez instruções pedindo cuidado. Comece pela lista da seção anterior e acrescente o que for específico do seu domínio — no meu caso, publicar em produção sem passar pelo checklist.

4. Registre. Sem rastro você vai discutir opinião sobre o que o agente fez. O mínimo cabe num arquivo por sessão, com os cinco campos que descrevi acima. Comece pela contagem de passos se for começar por um só.

5. Adote a disciplina. Erro novo vira mudança no ambiente. Toda vez. É o único item da lista que nunca termina, e é o que separa quem tem harness de quem tem configuração.

Nenhum desses passos exige trocar de modelo. É esse o ponto.

A versão mais forte desse argumento é a que dispensa a API: com harness decente, o que cabe no seu laptop em 2026 resolve boa parte do trabalho de rascunho e transformação de texto. A restrição ali deixa de ser dinheiro e passa a ser memória.

O que é harness engineering?

É a prática de projetar tudo que cerca o modelo num agente: ferramentas, verificação, contexto, limites e telemetria. A fórmula é agente = modelo + harness. O termo foi cunhado por Mitchell Hashimoto em fevereiro de 2026, a partir da disciplina de transformar cada erro do agente numa correção permanente no ambiente.

Qual a diferença para engenharia de prompt?

Engenharia de prompt escolhe palavras; harness engineering escreve código e configuração. Um prompt melhor pede ao agente que tome cuidado. Um harness melhor faz o build falhar quando ele não tomou.

Harness engineering realmente melhora o resultado?

Depende do horizonte da tarefa, e essa é a resposta honesta. Em tarefa longa, sim: a LangChain subiu 25 posições no Terminal Bench 2.0 sem trocar o modelo. Em tarefa curta e isolada, o SWE-Atlas mediu a escolha de harness dentro da margem de erro. Quanto mais passos o agente precisa acertar seguidos, mais o harness decide o resultado: o acerto cai de 60% em uma rodada para 25% em oito.

Preciso de um framework de agente para fazer isso?

Não. As cinco camadas são arquitetura e cabem no que o projeto já tem: um arquivo markdown na raiz, o comando de teste que você roda todo dia, uma lista de permissões e um log por sessão. Framework passa a valer quando você precisa orquestrar vários agentes ou trocar de modelo sem reescrever a integração. Comece sem, e adote quando a falta incomodar.

Por onde começar se eu tenho pouco tempo?

Pelo arquivo de contexto na raiz do projeto e pela verificação dentro do loop. As duas coisas cabem em uma tarde e cobrem as duas camadas de maior retorno.

• Harness é tudo que não é o modelo, e é onde está o ganho quando a tarefa tem muitos passos.
• Duas medições sérias discordam porque medem horizontes diferentes. Desconfie de quem cita só uma delas.
• A ordem de investimento é ferramentas, verificação, contexto e memória, guardrails, observabilidade.
• A disciplina vale mais que qualquer ferramenta: erro do agente vira mudança de ambiente, não observação no próximo prompt.

Este é o primeiro de 16 artigos sobre construir agentes que aguentam produção. Os outros quinze estão citados ao longo deste texto, cada um na camada a que pertence: ferramentas e protocolos na primeira, verificação na segunda, contexto e memória na terceira, segurança e identidade na quarta, medição e custo na quinta. Eles entram no ar ao longo dos próximos dias, e o link de cada um passa a funcionar quando o texto sai. Se quiser receber todos, assine a newsletter.