Engenharia de Harness: Como Construir Agentes de IA que Realmente Funcionam

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

Quando um agente falha, elas reescrevem o prompt. Quando ele falha de novo, adicionam mais instruções, trocam de modelo, aumentam a janela de contexto ou conectam outra ferramenta.

E então os mesmos problemas voltam.

O agente esquece uma decisão importante. Usa a ferramenta errada. Perde o fio da meada do que aconteceu três passos atrás. Diz que a tarefa foi concluída sem conferir o resultado. Tenta repetir a mesma ação que falhou até acabar o orçamento.

O problema nem sempre é o modelo.

O problema é o ambiente ao redor dele.

Esse ambiente é o harness.

Harness Engineering (Engenharia de Harness) é a prática de construir o sistema ao redor de um modelo, definindo o que ele pode ver, o que pode fazer, do que se lembra, o que conta como sucesso e o que acontece quando algo dá errado.

Um prompt melhor pode aprimorar uma única resposta.

Um harness melhor aprimora todas as execuções.

Siga meu Substack para mais análises práticas sobre agentes de IA, automação e sistemas em produção:

substack.com/@lunarresearcher

1. O Modelo Não É o Agente

Um modelo consegue raciocinar, gerar, comparar e escolher.

Isso não faz dele um agente confiável.

Um agente de verdade também precisa encontrar o contexto certo, usar ferramentas, preservar estado, respeitar permissões, verificar o próprio trabalho e se recuperar quando o ambiente se comporta de forma diferente do esperado.

O modelo é apenas o motor de raciocínio.

O harness é tudo aquilo que transforma esse raciocínio em execução real.

1SOLICITAÇÃO DO USUÁRIO
2      |
3      v
4+-----------------------------+
5|           HARNESS           |
6|                             |
7| contrato      contexto      |
8| ferramentas   estado        |
9| política      verificação   |
10| rastros       recuperação   |
11+-----------------------------+
12      |
13      v
14    MODELO
15      |
16      v
17AMBIENTE REAL

Coloque o mesmo modelo dentro de um chat e ele responderá perguntas.

Coloque-o dentro de um repositório com acesso a terminal, testes, ferramentas de navegador, memória do projeto, permissões controladas e um ciclo de revisão, e ele conseguirá entregar trabalho real.

O modelo não mudou.

O harness mudou.

2. Transforme Toda Solicitação em um Contrato

A linguagem natural é flexível.

A execução autônoma não deveria ser.

Uma solicitação como:

Melhore o fluxo de onboarding.

funciona bem quando há um humano sentado ao lado do modelo.

Mas é péssima como instrução de produção.

Antes de o agente agir, transforme a solicitação em um contrato de tarefa delimitado.

1objetivo: reduzir o abandono no onboarding
2
3entradas:
4  - briefing do produto
5  - dados de analytics
6  - repositório
7
8restrições:
9  - preservar a autenticação
10  - não alterar o schema do banco de dados
11  - manter o comportamento atual no mobile
12
13entregável:
14  - pull request revisável
15
16concluído_quando:
17  - testes passarem
18  - evento de analytics disparar corretamente
19  - fluxo desktop passar na revisão
20  - fluxo mobile passar na revisão
21
22aprovação_necessária:
23  - deploy em produção

A parte mais importante é o concluído_quando.

Sem isso, o agente pode resolver uma versão um pouco mais fácil do problema e ainda assim afirmar, cheio de confiança, que a tarefa foi concluída.

Com isso, a conclusão passa a ser mensurável.

O agente não deveria perguntar:

O que eu faço agora?

Ele deveria perguntar:

Qual ação aproxima o ambiente atual do resultado contratado?

Esse é um ciclo muito mais forte.

3. Dê ao Agente um Mapa, Não uma Janela de Contexto Gigante

Uma reação comum aos erros de um agente é dar mais contexto ao modelo.

Mais documentação.

Mais histórico de conversa.

Mais arquivos.

Mais saídas de ferramentas.

No fim, o agente recebe tudo e entende menos.

Contexto não é armazenamento.

É um orçamento de atenção.

Em vez de despejar o projeto inteiro em cada execução, dê ao agente um mapa pequeno mostrando onde estão as informações úteis.

1MAPA DO PROJETO
2
3regras do produto -> docs/product/
4arquitetura       -> docs/architecture.md
5frontend          -> apps/web/
6backend           -> services/api/
7testes            -> tests/
8comandos          -> docs/commands.md
9segurança         -> docs/security.md

Depois, expanda apenas quando necessário.

1TAREFA
2  |
3  v
4MAPA DO PROJETO
5  |
6  v
7SISTEMA RELEVANTE
8  |
9  v
10ARQUIVOS EXATOS
11  |
12  v
13INSTRUÇÕES LOCAIS

O material original descreve isso como divulgação progressiva: o harness deve carregar mais informações porque a tarefa precisa delas, e não simplesmente porque a informação existe.

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

O objetivo é ter o máximo de sinal útil.

4. Coloque um Gateway Entre o Modelo e Suas Ferramentas

Um modelo com vinte ferramentas não é automaticamente vinte vezes mais capaz.

Ele pode apenas ter vinte maneiras a mais de falhar.

Toda ferramenta deveria ter um contrato.

1FERRAMENTA: edit_file
2
3ENTRADAS
4caminho
5patch
6
7PRÉ-CONDIÇÕES
8o caminho existe
9o caminho está dentro do workspace
10
11SUCESSO
12patch aplicado
13diff retornado
14
15FALHA
16erro estruturado
17nenhuma sobrescrita parcial
18
19RISCO
20reversível

Assim, o caminho de execução passa a ser:

1MODELO PROPÕE
2      |
3      v
4GATEWAY VALIDA
5      |
6      v
7POLÍTICA AUTORIZA
8      |
9      v
10FERRAMENTA EXECUTA
11      |
12      v
13HARNESS REGISTRA O RESULTADO

O modelo decide qual ação quer tomar.

O harness decide se essa ação é válida, permitida e segura.

Essa distinção se torna crítica quando as ferramentas podem enviar mensagens, modificar a produção, gastar dinheiro ou apagar dados.

Um bom gateway de ferramentas também pode adicionar timeouts, validar argumentos, restringir caminhos de arquivo, normalizar erros e tornar as tentativas seguras.

Boas ferramentas reduzem o número de coisas que o modelo precisa adivinhar.

5. Tire a Memória de Dentro da Conversa

A conversa não deveria ser o registro oficial do sistema.

Agentes de longa duração acabam atingindo limites de contexto, travando, reiniciando ou passando o trabalho para outra sessão.

Se cada decisão importante existir apenas dentro do histórico, o fluxo de trabalho fica frágil.

Armazene o estado duradouro separadamente.

1{
2  "task_id": "feature_042",
3  "status": "verificando",
4  "current_step": "mobile_check",
5
6  "completed": [
7    "implementação",
8    "testes_unitários",
9    "desktop_check"
10  ],
11
12  "decisions": [
13    "reutilizar endpoint de exportação existente",
14    "manter o formato de data atual"
15  ],
16
17  "artifacts": [
18    "export.csv",
19    "desktop-after.png"
20  ],
21
22  "open_risks": [
23    "a barra de ferramentas mobile pode transbordar"
24  ],
25
26  "next_action": "renderizar viewport mobile"
27}

Um sistema útil separa a memória em quatro categorias:

1FATOS
2conhecimento estável
3
4DECISÕES
5o que foi escolhido e por quê
6
7ESTADO
8em que ponto a execução atual está
9
10LIÇÕES
11falhas que devem afetar execuções futuras

A próxima sessão do agente deve herdar o estado do trabalho, e não uma história comprimida sobre a conversa anterior.

6. Faça da Evidência o Portão para a Conclusão

Um agente dizendo "pronto" não é prova de que o trabalho acabou.

É apenas mais uma saída do modelo.

O harness precisa de evidências observáveis.

1AFIRMAÇÃO                 EVIDÊNCIA
2
3"bug corrigido"           teste que falhava agora passa
4
5"a página funciona"       fluxo no navegador concluído
6
7"os dados estão certos"   valores batem com a fonte
8
9"a migração é segura"     dry run + rollback passaram
10
11"tarefa concluída"        todos os critérios de aceite passaram

Use verificações determinísticas primeiro.

1sintaxe
2  |
3  v
4tipos
5  |
6  v
7testes focados
8  |
9  v
10testes de integração
11  |
12  v
13revisão visual / semântica
14  |
15  v
16aprovação humana

Não peça para outro modelo responder algo que um compilador, teste, schema ou query de banco de dados possa provar.

Use modelos para julgamento.

Use sistemas determinísticos para fatos.

O modelo cria o artefato.

O ambiente gera evidências sobre o artefato.

O harness decide se a evidência é suficiente.

7. Separe Quem Constrói de Quem Verifica

Existe outro problema na autorrevisão.

O agente que cometeu o erro costuma levar as mesmas premissas para a revisão.

Uma arquitetura mais robusta separa o executor do verificador.

1CONSTRUTOR
2   |
3   v
4cria o candidato
5   |
6   v
7VERIFICADOR
8   |
9   +-- confere o contrato
10   +-- busca casos ausentes
11   +-- testa afirmações sem base
12   +-- tenta quebrar o resultado
13   |
14   +------ PASSOU ------> ACEITAR
15   |
16   +------ FALHOU ------> DEVOLVER EVIDÊNCIA

O verificador não deveria perguntar:

Isso parece bom?

Ele deveria perguntar:

O que tornaria isso inaceitável?

Isso transforma a revisão: de uma simples confirmação para uma tentativa de refutação.

O material original recomenda explicitamente dar à verificação seus próprios critérios de rejeição e independência suficiente para desafiar as premissas que geraram o primeiro resultado.

8. Tire as Permissões de Dentro do Modelo

Algumas regras nunca deveriam depender de o modelo lembrar delas.

1nunca publique sem aprovação
2nunca exponha secrets
3nunca ultrapasse o limite de gastos
4nunca escreva fora do workspace
5nunca diga que os testes passaram se eles não rodaram

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

São políticas.

Uma escada simples de permissões:

1BAIXO RISCO
2
3ler
4buscar
5inspecionar
6
7-> automático
8
9REVERSÍVEL
10
11editar workspace
12rodar testes
13criar rascunho
14
15-> automático + rastro
16
17EFEITO EXTERNO
18
19enviar
20fazer deploy
21comprar
22
23-> aprovação necessária
24
25IRREVERSÍVEL / SENSÍVEL
26
27apagar dados
28rotacionar credenciais
29publicar globalmente
30
31-> bloqueio rígido ou proibido

Quanto maior a consequência, mais forte o controle.

O modelo pode recomendar a ação.

O harness a autoriza.

A ferramenta a executa.

Autonomia não é ausência de controle.

É liberdade dentro de um limite imposto.

9. Pare de Tentar Novamente às Cegas

Uma das piores políticas de recuperação é:

Algo falhou. Tente de novo.

Se nada muda, o sistema está apenas pagando para reproduzir a mesma falha.

As falhas devem ser classificadas primeiro.

1TIMEOUT DA FERRAMENTA
2-> tentar novamente com backoff
3
4ARGUMENTOS INVÁLIDOS
5-> corrigir a chamada da ferramenta
6
7CONTEXTO AUSENTE
8-> buscar a fonte que falta
9
10TESTE FALHOU
11-> inspecionar o comportamento com falha
12
13PERMISSÃO NEGADA
14-> solicitar aprovação
15
16REQUISITOS CONFLITANTES
17-> escalar
18
19FALHA REPETIDA SEM MUDANÇA
20-> parar

Um ciclo de agente útil se parece com isto:

1OBSERVAR
2   |
3   v
4DECIDIR
5   |
6   v
7AGIR
8   |
9   v
10MEDIR
11   |
12   +---- ACEITAR
13   |
14   +---- CORRIGIR
15   |
16   +---- ESCALAR
17   |
18   +---- PARAR

Todo ciclo deve ter limites de tentativas, tempo, gastos e escopo destrutivo.

Um agente confiável precisa saber como continuar.

Mas também precisa saber quando uma nova tentativa já não vale a pena.

10. Transforme Instruções Repetidas em Infraestrutura

Imagine que o prompt contenha:

Sempre rode o formatador.

Essa regra fica muito mais forte se o formatador rodar automaticamente.

Imagine que as instruções digam:

Código de UI não pode acessar o banco de dados diretamente.

Isso fica muito mais forte como um teste de arquitetura que falha quando a regra é quebrada.

A progressão se parece com isto:

1EXPLICAÇÃO
2      |
3      v
4CHECKLIST
5      |
6      v
7TEMPLATE
8      |
9      v
10VERIFICAÇÃO AUTOMÁTICA
11      |
12      v
13POLÍTICA IMPOSTA

O prompt deve explicar o julgamento.

O harness deve impor as invariantes.

Cada erro recorrente deveria descer um degrau nessa escada.

Com o tempo, o modelo não precisa mais lembrar da lição.

O ambiente lembra por ele.

11. Registre a Execução

Um artefato final perfeito pode esconder um caminho de execução terrível.

Talvez o agente tenha acessado a fonte errada.

Talvez tenha ignorado um comando que falhou.

Talvez tenha repetido uma ação externa duas vezes.

Talvez tenha gasto dez vezes o orçamento previsto.

Talvez tenha chegado à resposta certa pelo motivo errado.

Registre informações suficientes para reconstruir o que aconteceu.

109:14  contrato de tarefa criado
209:15  architecture.md carregado
309:17  checkout.ts editado
409:18  teste focado falhou
509:21  implementação corrigida
609:22  teste focado passou
709:24  teste de integração passou
809:25  deploy bloqueado: aprovação necessária

Rastros úteis incluem fontes de contexto, chamadas de ferramentas, mudanças de estado, resultados de verificação, motivos de novas tentativas, decisões de aprovação, custo e latência.

A ideia não é coletar logs por diversão.

A ideia é localizar a falha.

Se o passo 18 quebrar, você deve conseguir corrigir o passo 18.

Você não deveria precisar reproduzir a execução inteira.

12. Dê um Recibo a Cada Execução

Não obrigue o humano a revisar um histórico de quarenta mensagens.

Compile o resultado em um recibo curto.

1OBJETIVO
2
3Corrigir aplicação duplicada de cupom.
4
5ALTERADO
6
7validação do checkout
8teste de regressão
9
10VERIFICADO
11
12lint passou
13testes unitários passaram
14teste de integração passou
15
16NÃO VERIFICADO
17
18provedor de pagamento em produção
19
20RISCOS
21
22cliente mobile legado indisponível
23
24APROVAÇÃO NECESSÁRIA
25
26deploy para staging

Isso não é um resumo do que o modelo afirma ter acontecido.

É um resumo do que o harness consegue provar que aconteceu.

Essa distinção torna o recibo útil para revisões, passagens de bastão e sessões futuras do agente.

13. Faça Cada Falha Melhorar o Harness

A maioria das equipes corrige o resultado que falhou.

A abordagem melhor é corrigir o sistema que permitiu a falha.

1CONTEXTO AUSENTE
2-> melhorar o mapa do projeto
3
4FERRAMENTA ERRADA
5-> melhorar o roteamento ou o contrato da ferramenta
6
7SAÍDA RUIM
8-> adicionar validador
9
10LOOP REPETIDO
11-> adicionar limite de tentativas
12
13AÇÃO INSEGURA
14-> adicionar portão de permissão
15
16DECISÃO PERDIDA
17-> persistir o estado
18
19FALHA DESCONHECIDA
20-> melhorar o rastreamento

É aqui que o Harness Engineering começa a gerar juros compostos.

Um resultado corrigido ajuda uma execução.

Um harness corrigido melhora todas as execuções seguintes.

Os melhores sistemas de agentes ficam mais confiáveis porque os erros deixam infraestrutura para trás.

14. Comece com o Menor Harness Útil

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

Construa em camadas.

1NÍVEL 0
2
3prompt
4modelo
5
6NÍVEL 1
7
8contrato de tarefa
9mapa do projeto
10ferramentas
11
12NÍVEL 2
13
14estado estruturado
15verificação
16loop delimitado
17
18NÍVEL 3
19
20permissões
21rastros
22recuperação
23portões humanos

Uma tarefa curta de pesquisa pode precisar apenas de um prompt e uma revisão.

Uma tarefa de programação de seis horas, com acesso a arquivos, rede e capacidade de deploy, exige muito mais.

Adicione complexidade quando a superfície de falha justificar.

Não porque arquitetura de agentes pareça legal.

O Checklist do Harness Engineering

Antes de dar autonomia real a um agente, pergunte-se:

1[ ] O sucesso está definido antes da execução?
2
3[ ] O agente consegue achar o contexto certo
4    sem carregar tudo?
5
6[ ] Toda ferramenta tem um propósito claro,
7    schema e estado de falha?
8
9[ ] As decisões importantes são armazenadas
10    fora da conversa?
11
12[ ] A conclusão exige evidências?
13
14[ ] Ações arriscadas são protegidas por políticas?
15
16[ ] Todo loop tem um limite de tentativas?
17
18[ ] A execução pode ser retomada após uma interrupção?
19
20[ ] Você consegue reconstruir cada ação importante?
21
22[ ] A falha melhora alguma regra, ferramenta,
23    teste, mapa ou permissão?
24
25[ ] A alteração final pode ser revertida?

Se várias respostas forem "não", um modelo mais potente não vai tornar o agente confiável automaticamente.

Pode apenas tornar a falha mais rápida e mais cara.

A Verdadeira Mudança

A engenharia de prompt pergunta:

O que devo dizer ao modelo?

A engenharia de contexto pergunta:

O que o modelo deveria saber neste exato momento?

A engenharia de harness pergunta:

Qual sistema permite que o modelo aja, verifique seu trabalho, se recupere de falhas e opere com segurança?

1PROMPT
2-> instrução
3
4CONTEXTO
5-> visão de trabalho
6
7HARNESS
8-> ambiente operacional
9
10LOOP
11-> correção local
12
13GRAFO
14-> coordenação

Os modelos vão continuar mudando.

A vantagem duradoura vive ao redor deles.

Seus contratos melhoram.

Suas ferramentas melhoram.

Seus testes melhoram.

Seu estado fica mais limpo.

Suas permissões ficam mais seguras.

Sua lógica de recuperação fica mais inteligente.

Suas falhas viram infraestrutura.

É assim que modelos capazes se tornam agentes confiáveis.

Isso é Harness Engineering.

Se Você Chegou Até Aqui

Salve este guia nos favoritos.

Siga-me no X: x.com/0xjmori

Inscreva-se no meu Substack: substack.com/@lunarresearcher

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