Harness Engineering: O Guia Completo para Construir Agentes de IA que Não Falham

A maioria das pessoas está tentando melhorar agentes de IA na camada errada.

Quando um agente falha, elas reescrevem o prompt.

Quando falha de novo, adicionam mais instruções.

Antes de começarmos:

Siga meu Substack para novidades frescas sobre IA, workflows de agentes e guias passo a passo antes de chegarem ao X: [https://substack.com/@lunarresearcher

Depois trocam de modelo, adicionam mais ferramentas, aumentam a janela de contexto e torcem para a próxima execução ser diferente.

Mas muitas falhas de agentes não são falhas de raciocínio.

São falhas de ambiente.

O agente não sabia quais arquivos eram importantes.

Usou a ferramenta certa no lugar errado.

Perdeu as decisões tomadas na sessão anterior.

Afirmou sucesso sem executar as verificações.

Repetiu uma ação após uma falha parcial.

Tinha permissão para fazer algo que deveria exigir aprovação.

O modelo não era necessariamente o problema. O sistema ao redor do modelo estava incompleto.

Esse sistema é o harness (arnês).

E projetá-lo está se tornando uma disciplina de engenharia própria.

Engenharia de Harness é a prática de construir o ambiente que transforma a inteligência do modelo em trabalho confiável.

Um prompt muda uma tentativa.

Um harness muda todas as tentativas.

Este guia explica como construir um.

1. O Modelo Não É o Agente

Um modelo pode raciocinar, gerar, comparar e escolher.

Mas um agente também precisa interagir com um ambiente real.

Ele precisa:

• entender a tarefa
• encontrar o contexto relevante
• selecionar e usar ferramentas
• preservar o estado
• respeitar permissões
• inspecionar o resultado
• recuperar-se de falhas
• provar que o trabalho está completo

O modelo é o motor de raciocínio dentro desse sistema.

O harness é tudo que torna o raciocínio operacional.

1solicitação do usuário
2     |
3     v
4+-----------------------------+
5|          HARNESS            |
6| contrato | contexto | regras|
7| ferram.  | estado   | verif.|
8| rastros  | recuperação       |
9+-----------------------------+
10     |
11     v
12    modelo
13     |
14     v
15ambiente real

Um modelo poderoso dentro de um harness fraco ainda é um agente fraco.

Pode produzir respostas individuais impressionantes, mas se comportará de forma inconsistente em tarefas longas, ambientes mutáveis e falhas parciais.

O objetivo da engenharia de harness não é remover a incerteza do modelo.

É conter essa incerteza dentro de um sistema que possa observar, verificar e recuperar.

2. Comece com um Contrato de Tarefa

A maioria das tarefas de agentes começa como uma intenção vaga:

Melhorar o fluxo de onboarding.

Essa frase pode ser suficiente para uma conversa.

Não é suficiente para execução autônoma.

Antes do agente agir, o harness deve converter a solicitação em um contrato de tarefa.

Um contrato útil responde a cinco perguntas:

1. Qual resultado deve existir?
2. O que está dentro do escopo?
3. O que não deve mudar?
4. Que evidência prova a conclusão?
5. Quais ações exigem aprovação humana?

1objetivo: reduzir abandono no onboarding
2
3escopo:
4  - fluxo de cadastro
5  - análises do onboarding
6
7restrições:
8  - não alterar autenticação
9  - preservar comportamento mobile existente
10
11aceitação:
12  - testes passam
13  - evento de analytics é emitido
14  - capturas de tela cobrem desktop e mobile
15
16aprovacao_necessaria:
17  - deploy em produção
18  - migração de banco de dados

Isso muda a pergunta do agente de:

O que devo fazer a seguir?

para:

Qual ação move o ambiente em direção ao resultado contratado?

Sem um contrato, o agente otimiza para atividade plausível.

Com um contrato, ele pode otimizar para conclusão verificada.

3. Dê ao Agente um Mapa, Não um Manual

Despejar todo o repositório, conjunto de documentação e histórico de conversas no contexto não é uma boa engenharia de contexto.

É inundação de contexto.

O harness deve fornecer um pequeno mapa primeiro, depois permitir que o agente recupere detalhes quando se tornarem relevantes.

1MAPA DO PROJETO
2
3regras do produto     -> docs/produto/
4arquitetura           -> docs/arquitetura.md
5frontend              -> apps/web/
6backend               -> services/api/
7testes                -> tests/
8comandos              -> docs/comandos.md
9regras de release     -> docs/release.md

Isso é divulgação progressiva:

1tarefa
2  -> mapa do projeto
3      -> subsistema relevante
4          -> arquivos exatos
5              -> instruções locais

O contexto deve expandir porque a tarefa exige, não porque a informação existe.

Um bom compilador de contexto decide:

• o que é sempre necessário
• o que pode ser recuperado depois
• o que se tornou obsoleto
• o que pode ser resumido
• o que deve permanecer literal

O objetivo não é o contexto máximo.

É o sinal máximo por token.

4. Construa um Portal de Ferramentas, Não uma Pilha de Ferramentas

Dar vinte ferramentas a um agente não o torna capaz.

Dá ao agente vinte maneiras de cometer um erro.

Cada ferramenta deve ter um contrato claro:

1FERRAMENTA: editar_arquivo
2
3entradas:
4  caminho
5  patch
6
7pré-condições:
8  caminho existe
9  caminho está dentro do workspace permitido
10
11evidência de sucesso:
12  patch aplicado
13  diff resultante retornado
14
15comportamento em falha:
16  sem sobrescrita parcial
17  erro estruturado retornado
18
19classe de risco:
20  reversível

O harness deve controlar como as ferramentas são expostas e usadas.

Ele pode:

• ocultar ferramentas irrelevantes
• validar argumentos
• restringir caminhos e domínios
• anexar timeouts
• tornar retentativas idempotentes
• normalizar saídas
• exigir confirmação para ações arriscadas
• retornar evidências, não apenas "sucesso"

Isso cria uma separação importante:

1modelo decide a intenção
2portal valida a ação
3ferramenta altera o ambiente
4sensor observa o resultado

O modelo pode propor uma ação.

O portal de ferramentas decide se essa ação é válida o suficiente para ser executada.

5. Separe o Cérebro, as Mãos e o Histórico

Muitos agentes frágeis misturam tudo em uma transcrição crescente.

Raciocínio, chamadas de ferramentas, arquivos, decisões, erros e observações antigas competem pela mesma janela de contexto.

Um sistema mais forte separa três responsabilidades:

1CÉREBRO
2planeja, raciocina, escolhe
3
4MÃOS
5executam ferramentas dentro de um ambiente controlado
6
7HISTÓRICO
8armazena fatos duráveis, decisões e estado da execução

O modelo não precisa de todo evento bruto no contexto ativo.

Ele precisa do estado atual correto.

O sandbox não precisa entender todo o objetivo.

Ele precisa executar com segurança uma ação delimitada.

O log da sessão não precisa raciocinar.

Ele precisa preservar o que aconteceu depois que o contexto atual desaparecer.

Essa separação torna mais fácil retomar, inspecionar e reparar agentes de longa duração.

Também permite substituir uma parte sem reconstruir todo o sistema.

6. A Memória Deve se Tornar Estado Durável

O histórico da conversa não é memória confiável.

É um fluxo de eventos.

A memória útil deve ser convertida em estado explícito.

No mínimo, preserve quatro categorias:

1FATOS
2informações estáveis descobertas sobre o ambiente
3
4DECISÕES
5escolhas feitas e a razão por trás delas
6
7PROGRESSO
8trabalho concluído, ativo, bloqueado e restante
9
10LIÇÕES
11falhas que devem mudar o comportamento futuro

Por exemplo:

1fatos:
2  - validação de checkout está em services/orders
3
4decisões:
5  - reutilizar o pipeline de validação existente
6  - motivo: evita uma segunda fonte de verdade
7
8progresso:
9  concluído:
10    - adicionada regra no servidor
11  restante:
12    - atualizar teste de integração
13
14lições:
15  - comando de teste local requer TEST_DB_URL

Isso é muito mais útil do que reproduzir cinquenta páginas de transcrição e torcer para o modelo notar a linha importante.

Armazene o histórico bruto para auditoria.

Compile o estado durável para execução.

7. Conclusão Exige Evidência

Um agente dizer "pronto" não é evidência de que a tarefa está concluída.

É apenas outra saída do modelo.

A conclusão deve ser decidida por mudanças observáveis no ambiente.

1afirmação                     evidência
2--------------------------------------------------
3"o bug foi corrigido"         teste que falhava agora passa
4"a página funciona"           fluxo do navegador concluído
5"a migração é segura"         dry run e rollback passam
6"o relatório está correto"    valores correspondem aos dados fonte
7"a tarefa está completa"      toda verificação de aceitação passa

O harness deve executar as verificações determinísticas mais baratas primeiro.

1sintaxe
2  -> tipos
3      -> testes focados
4          -> testes de integração
5              -> revisão visual ou semântica
6                  -> aprovação humana

Não use outro modelo onde um compilador, esquema, checksum, consulta ou teste possa responder à pergunta.

Use modelos para ambiguidade.

Use código para encanamento.

Um modelo pode propor que a tarefa está completa.

Apenas o ambiente pode provar isso.

8. A Verificação Deve Atacar o Resultado

Trabalhadores e avaliadores não devem compartilhar o mesmo objetivo.

O trabalhador tenta criar a solução mais forte.

O avaliador tenta encontrar a razão pela qual ela deve ser rejeitada.

1trabalhador
2  -> produz candidato
3
4verificador
5  -> verifica contrato
6  -> procura por casos faltantes
7  -> testa afirmações não suportadas
8  -> tenta quebrar o resultado
9
10sobrevive
11  -> aceitar
12
13falha
14  -> retornar evidência direcionada

Essa assimetria é importante.

Se você pedir ao mesmo agente, no mesmo contexto, para "verificar seu trabalho", ele frequentemente preserva as suposições que criaram o erro.

Um estágio de verificação útil deve ter:

• uma rubrica explícita de rejeição
• acesso ao artefato produzido
• acesso ao contrato de aceitação
• ferramentas independentes ou contexto novo quando necessário
• permissão para rejeitar sem reparar

Verificação não é uma segunda opinião.

É uma tentativa de refutação.

9. O Modelo Propõe, a Política Autoriza

Algumas regras nunca devem depender de o modelo se lembrar delas.

1nunca publicar sem aprovação
2nunca expor um segredo
3nunca escrever fora do workspace
4nunca exceder o limite de gastos
5nunca marcar testes como aprovados a menos que tenham sido executados

Estas não são sugestões de prompt.

São políticas.

O design mais seguro mantém a política fora do loop de raciocínio.

1BAIXO RISCO
2ler arquivos, pesquisar, inspecionar
3-> automático
4
5MUDANÇA REVERSÍVEL
6editar workspace, executar testes
7-> automático com rastro
8
9EFEITO EXTERNO
10enviar mensagem, fazer deploy, comprar
11-> aprovação explícita
12
13IRREVERSÍVEL OU SENSÍVEL
14excluir dados, rotacionar credenciais, publicar globalmente
15-> barreira rígida ou proibido

Quanto mais forte a consequência, mais difícil a barreira.

Autonomia não é ausência de controle.

É a capacidade de operar livremente dentro de um limite claramente definido.

10. A Recuperação Deve Mirar na Classe da Falha

A estratégia de recuperação mais comum é:

Algo falhou. Tente novamente.

Isso não é recuperação.

É repetição.

O harness deve classificar a falha antes de selecionar a próxima ação.

1timeout da ferramenta
2-> repetir com backoff
3
4argumentos inválidos
5-> reparar a chamada da ferramenta
6
7contexto faltante
8-> recuperar fonte específica
9
10teste falhou
11-> inspecionar comportamento da falha
12
13permissão negada
14-> solicitar aprovação ou escolher caminho seguro
15
16requisitos contraditórios
17-> escalar para humano
18
19falha repetida inalterada
20-> parar o loop

Uma repetição deve alterar pelo menos uma condição relevante.

Caso contrário, o sistema está pagando para reproduzir a mesma falha.

Um loop de agente limitado se parece com isso:

1observar
2  -> decidir
3      -> agir
4          -> medir
5              -> aceitar
6              -> reparar
7              -> escalar
8              -> parar

Cada loop precisa de um orçamento:

• número máximo de tentativas
• tempo máximo
• gasto máximo
• escopo destrutivo máximo
• condição de escalação

Agentes confiáveis sabem como continuar.

Eles também sabem quando continuar não é mais racional.

11. Instruções Devem se Tornar Infraestrutura

Instruções de agente são úteis quando explicam a realidade local.

Mas instruções sozinhas são uma aplicação fraca.

Se uma regra importa repetidamente, mova-a para baixo na pilha.

1"use o formatador"
2-> executar formatador automaticamente
3
4"não importe entre camadas"
5-> adicionar teste de arquitetura
6
7"inclua um rollback de migração"
8-> exigir arquivo de rollback no CI
9
10"não modifique arquivos gerados"
11-> bloquear escritas em caminhos gerados
12
13"cite toda afirmação externa"
14-> validar cobertura de citações

Isso cria uma escada de instruções:

1explicação
2  -> checklist
3      -> template
4          -> verificação automatizada
5              -> política aplicada

Mova o conhecimento importante o mais para baixo possível nessa escada.

O prompt deve explicar o julgamento.

O harness deve aplicar os invariantes.

12. Observe a Execução, Não Apenas a Resposta Final

Um artefato final limpo pode esconder um processo terrível.

O agente pode ter:

• acessado os dados errados
• ignorado um comando que falhou
• repetido uma ação externa duas vezes
• consumido dez vezes o orçamento esperado
• chegado à resposta certa pelo motivo errado

Você precisa de rastros que tornem a execução reconstruível.

109:14  contrato criado
209:15  fonte de contexto carregada: arquitetura.md
309:17  arquivo editado: checkout.ts
409:18  teste focado falhou: cupom duplicado
509:21  implementação reparada
609:22  teste focado passou
709:24  teste de integração passou
809:25  deploy externo bloqueado: aprovação necessária

Um rastro útil registra:

• transições de estado
• fontes de contexto
• entradas e saídas de ferramentas
• mudanças no ambiente
• resultados de verificação
• motivos de repetição
• decisões de aprovação
• custo e latência

O objetivo não é vigilância.

O objetivo é reparo local.

Quando uma execução falha no passo 18, você deve ser capaz de reiniciar a partir de um checkpoint confiável em vez de reproduzir toda a tarefa.

13. Toda Execução Precisa de um Recibo de Mudança

Transcrições longas de agentes são difíceis de revisar.

Ao final de uma execução, o harness deve compilar um pequeno recibo de mudança.

1OBJETIVO
2Corrigir aplicação de cupom duplicado durante o checkout.
3
4ALTERADO
5- lógica de validação do checkout
6- teste de regressão focado
7
8VERIFICADO
9- lint passou
10- testes unitários passaram
11- teste de integração do checkout passou
12
13NÃO VERIFICADO
14- provedor de pagamento em produção
15
16DECISÕES
17- preservada ordem de prioridade de cupom existente
18
19RISCOS
20- cliente mobile legado não estava disponível localmente
21
22APROVAÇÃO NECESSÁRIA
23- deploy para staging

O recibo não é um resumo do que o modelo disse.

É um resumo do que o sistema pode provar.

Isso dá aos humanos uma superfície de revisão compacta e dá à próxima sessão do agente um ponto de partida confiável.

A melhor transferência não é "aqui está a conversa."

É "aqui está o estado, a evidência e o risco não resolvido."

14. Toda Falha Deve Atualizar o Harness

As equipes mais fracas corrigem a saída com falha.

As equipes mais fortes também corrigem o sistema que a permitiu.

Após uma falha, pergunte:

1O contrato da tarefa era ambíguo?
2Contexto importante estava invisível?
3A ferramenta errada foi exposta?
4Uma pré-condição estava faltando?
5O resultado era impossível de verificar?
6A política foi deixada dentro do prompt?
7A recuperação era muito ampla?
8O rastro era insuficiente?

Em seguida, converta a lição em uma melhoria reutilizável.

1falha
2  -> diagnóstico
3      -> novo sensor, regra, mapa, teste ou contrato de ferramenta
4          -> execuções futuras melhoram automaticamente

Este é o volante do harness.

O sistema se torna mais confiável porque as falhas deixam infraestrutura para trás.

Uma resposta corrigida ajuda uma execução.

Um harness corrigido ajuda todas as execuções futuras.

15. Harnesses Também Decaem

Mais harness nem sempre é melhor.

Modelos melhoram. Ferramentas melhoram. Tarefas mudam. Salvaguardas antigas podem se tornar atrito desnecessário.

Uma gambiarra criada para o modelo de ontem pode impedir o modelo de hoje de usar uma estratégia melhor.

Isso cria decadência do harness:

1limitação do modelo antigo
2  -> gambiarra no harness
3      -> modelo melhora
4          -> gambiarra permanece
5              -> sistema se torna mais lento ou menos capaz

Trate os componentes do harness como código de produção.

Meça se eles ainda fornecem ganho.

Para cada roteador, avaliador, camada de memória e regra de repetição, pergunte:

• Qual falha isso previne?
• Com que frequência essa falha ainda ocorre?
• Que latência e complexidade isso adiciona?
• O mesmo resultado pode ser alcançado de forma mais simples agora?
• O que acontece se removermos isso?

O melhor harness não é o maior.

É o menor sistema que fecha de forma confiável a lacuna entre intenção e evidência.

Construa para deletar.

16. O Harness Mínimo Viável

Você não precisa de uma plataforma de orquestração para começar.

Construa o harness em camadas.

Nível 1: Uma tarefa delimitada

• objetivo
• escopo
• restrições
• verificações de aceitação

Nível 2: Um ambiente legível

• mapa do projeto
• comandos
• instruções locais
• dependências conhecidas

Nível 3: Ações controladas

• ferramentas tipadas
• validação de argumentos
• limites de caminho e permissão
• resultados estruturados

Nível 4: Execução durável

• estado de execução explícito
• checkpoints
• decisões
• lições

Nível 5: Evidência

• verificações determinísticas
• verificação adversarial
• recibo de mudança

Nível 6: Recuperação e aprendizado

• classificação de falhas
• repetições limitadas
• escalação
• atualizações do harness a partir de falhas recorrentes

Construa a menor camada que elimina a falha que você realmente tem.

Não comece com uma arquitetura multi-agente porque um prompt único ocasionalmente precisa de esclarecimento.

A complexidade deve ser conquistada por falha observada.

17. Uma Especificação de Harness Reutilizável

Antes de dar a um agente autonomia significativa, defina isto:

1ESPECIFICAÇÃO DO HARNESS DO AGENTE
2
31. CONTRATO
4   objetivo:
5   escopo:
6   restrições:
7   evidência de aceitação:
8
92. CONTEXTO
10   mapa sempre carregado:
11   fontes de recuperação:
12   instruções locais:
13   regras de atualização:
14
153. FERRAMENTAS
16   ferramentas permitidas:
17   pré-condições:
18   efeitos colaterais:
19   evidência de sucesso:
20   política de timeout e repetição:
21
224. ESTADO
23   fatos:
24   decisões:
25   progresso:
26   lições:
27   formato do checkpoint:
28
295. POLÍTICA
30   ações automáticas:
31   ações que exigem aprovação:
32   ações proibidas:
33   limites de orçamento:
34
356. VERIFICAÇÃO
36   verificações determinísticas:
37   verificações adversariais:
38   regra de aceitação:
39
407. RECUPERAÇÃO
41   classes de falha:
42   limites de repetição:
43   condições de escalação:
44   rollback seguro:
45
468. OBSERVABILIDADE
47   eventos de rastro:
48   métricas:
49   recibo de mudança final:

Se esses campos não estiverem definidos, o agente não é autônomo.

Ele está improvisando.

18. Meça o Sistema no Nível Certo

A contagem de tokens não é a métrica final.

Tampouco o é o número de tarefas tentadas.

A unidade útil é trabalho aceito.

Uma métrica prática é:

1saídas aceitas
2------------------------------
3minutos de revisão humana + custo de execução

Acompanhe também:

• taxa de aceitação na primeira passagem
• taxa de recuperação após falha de ferramenta
• taxa de falha repetida
• intervenções humanas por tarefa
• alegações de conclusão não suportadas
• tempo desde a solicitação até o resultado verificado
• sobrecarga do harness por componente

Isso evita uma ilusão comum:

Um agente pode parecer altamente produtivo enquanto cria trabalho de revisão caro.

O objetivo não é mais atividade do agente.

É mais resultados confiáveis por unidade de atenção humana.

19. Quando Você Não Precisa de um Harness Pesado

Nem toda chamada de modelo precisa de um sistema operacional.

Use um prompt simples quando:

• a tarefa é curta
• a saída é fácil de inspecionar
• a falha é barata
• nenhum efeito colateral externo ocorre
• o usuário permanece no loop

Adicione um harness quando:

• o trabalho abrange várias ferramentas ou sessões
• o ambiente pode mudar
• as ações têm consequências reais
• a conclusão é difícil de julgar manualmente
• a mesma falha aparece repetidamente
• a revisão humana se torna o gargalo

O propósito de um harness não é fazer uma demonstração parecer sofisticada.

É tornar o trabalho real confiável.

A Verdadeira Mudança

A primeira geração de produtos de IA foi construída em torno de prompts.

A próxima geração está sendo construída em torno de ambientes.

A pergunta não é mais apenas:

Como fazemos o modelo responder melhor?

É:

Como construímos um sistema onde boas ações são fáceis, ações perigosas são controladas, falhas são visíveis e a conclusão é comprovável?

Essa é a mudança da engenharia de prompt para a engenharia de harness.

O modelo fornece inteligência.

O harness fornece estrutura.

Juntos, eles produzem execução confiável.

Se seu agente continua desmoronando, pare de adicionar adjetivos ao prompt.

Construa o ambiente que ele precisa para ter sucesso.

Se Você Chegou Até Aqui

Marque este guia.

Siga @LunarResearcher no X

Inscreva-se no meu Substack

Envie este artigo para alguém que ainda está tentando corrigir toda falha de agente com um prompt mais longo.