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

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

Quando um agente falha, eles reescrevem o prompt.

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

Antes de começarmos:

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

Então 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.

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

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 | política |
7| ferramentas | estado | verificações |
8| rastreamento | 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.

Ele 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 se 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 integração.

Essa frase pode ser suficiente para uma conversa.

Não é suficiente para uma 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 a desistência na integração
2
3escopo:
4  - fluxo de cadastro
5  - análise da integração
6
7restrições:
8  - não alterar a autenticação
9  - preservar o comportamento mobile existente
10
11aceitação:
12  - testes passam
13  - evento de análise é emitido
14  - capturas de tela cobrem desktop e mobile
15
16aprovação_necessária:
17  - implantação 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 uma atividade plausível.

Com um contrato, ele pode otimizar para a 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 se 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 desatualizado
• 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 espaço de trabalho 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 as tentativas 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 cada 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 é uma 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  - a validação do 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 do lado do servidor
11  restante:
12    - atualizar teste de integração
13
14lições:
15  - o 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. A Conclusão Exige Evidências

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"            simulação e reversão passam
6"o relatório está correto"       valores correspondem aos dados de origem
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, soma de verificação, 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 o contrato
6  -> procura por casos ausentes
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 novamente seu trabalho", ele geralmente preserva as suposições que criaram o erro.

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

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

A 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 espaço de trabalho
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 espaço de trabalho, executar testes
7-> automático com rastreamento
8
9EFEITO EXTERNO
10enviar mensagem, implantar, comprar
11-> aprovação explícita
12
13IRREVERSÍVEL OU SENSÍVEL
14excluir dados, rotacionar credenciais, publicar globalmente
15-> barreira forte ou proibido

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

Autonomia não é a 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-> tentar novamente com backoff
3
4argumentos inválidos
5-> reparar a chamada da ferramenta
6
7contexto ausente
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 nova tentativa 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:

• tentativas máximas
• tempo máximo
• gasto máximo
• escopo destrutivo máximo
• condição de escalonamento

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 é importante 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 uma reversão de migração"
8-> exigir arquivo de reversão no CI
9
10"não modifique arquivos gerados"
11-> bloquear gravações em caminhos gerados
12
13"cite toda afirmação externa"
14-> validar cobertura de citação

Isso cria uma escada de instruções:

1explicação
2  -> lista de verificação
3      -> modelo
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 as 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 rastreamentos 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  implantação externa bloqueada: aprovação necessária

Um rastreamento útil registra:

• transições de estado
• fontes de contexto
• entradas e saídas da ferramenta
• mudanças no ambiente
• resultados da verificação
• motivos da 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 ponto de verificação confiável em vez de reproduzir toda a tarefa.

13. Toda Execução Precisa de um Recibo de Alteração

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 alteração.

1OBJETIVO
2Corrigir a 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 de produção
15
16DECISÕES
17- preservada a ordem de prioridade de cupons existente
18
19RISCOS
20- cliente mobile legado não estava disponível localmente
21
22APROVAÇÃO NECESSÁRIA
23- implantar em 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 que falhou.

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

Após uma falha, pergunte:

1O contrato da tarefa era ambíguo?
2O contexto importante estava invisível?
3A ferramenta errada foi exposta?
4Uma pré-condição estava ausente?
5O resultado era inverificável?
6A política foi deixada dentro do prompt?
7A recuperação era muito ampla?
8O rastreamento 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 se Degradam

Mais harness nem sempre é melhor.

Modelos melhoram. Ferramentas melhoram. Tarefas mudam. Salvaguardas antigas podem se tornar atritos desnecessários.

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

Isso cria degradação 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 estão gerando valor.

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
• pontos de verificação
• decisões
• lições

Nível 5: Evidência

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

Nível 6: Recuperação e aprendizado

• classificação de falhas
• repetições limitadas
• escalonamento
• 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 falhas observadas.

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 ponto de verificação:
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 escalonamento:
44   reversão segura:
45
468. OBSERVABILIDADE
47   eventos de rastreamento:
48   métricas:
49   recibo de alteração 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.

Nem é o número de tarefas tentadas.

A unidade útil é o trabalho aceito.

Uma métrica prática é:

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

Acompanhe também:

• taxa de aceitação na primeira tentativa
• 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 um 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 questão 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 o 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.