Harness, Loop e Graph Engineering:
as 3 camadas de um agente de IA de verdade

SEÇÃO 01

O que muda quando o agente sai da demo

Uma demo de agente é fácil de impressionar: você dá um prompt, o modelo responde bem, todo mundo aplaude. O problema aparece depois — quando esse mesmo agente precisa rodar sem você olhando, tocar em dados reais e não pode simplesmente "tentar de novo" até dar certo.

Um modelo, sozinho, não sabe manter estado entre sessões, chamar uma ferramenta com segurança, validar se o próprio resultado está certo, decidir quando parar ou dizer para um humano "preciso de ajuda aqui". Tudo isso vem do que é construído ao redor do modelo.

Esse "ao redor" costuma virar uma bagunça de conceitos misturados. Um jeito prático de organizar é separar em três camadas, cada uma resolvendo um problema diferente:

Harness engineering
  → constrói o ambiente ao redor do modelo

Loop engineering
  → projeta o ciclo repetido de ação e correção

Graph engineering
  → deixa o fluxo de trabalho explícito

Elas ficam ao redor do mesmo modelo, todas afetam a confiabilidade do agente e, sim, todas podem conter algum tipo de repetição. Mas resolvem problemas diferentes — e misturar as três é o motivo mais comum de alguém depurar a camada errada quando o agente falha.

SEÇÃO 02

Harness engineering: o ambiente do modelo

Harness é o "arnês" — tudo que dá ao modelo condições de operar no mundo real: ferramentas, memória, controle de execução, segurança e uma forma de você enxergar o que ele está fazendo.

Sem harness, um modelo não consegue:

• manter estado de um projeto entre sessões diferentes;
• chamar uma ferramenta com segurança (API, navegador, terminal, banco de dados);
• respeitar permissões e limites de acesso;
• tentar de novo quando algo falha, dentro de um orçamento de tempo e custo;
• ser auditado depois — o que ele viu, o que ele fez, por quê.

Um bom harness costuma cobrir seis frentes:

Contexto
  instruções, memória, estado da conversa, políticas

Ferramentas
  APIs, navegador, terminal, bancos de dados, MCP

Persistência
  arquivos, checkpoints, histórico, memória de longo prazo

Controle de execução
  retries, timeouts, orçamento de custo, aprovações

Segurança
  permissão mínima necessária, isolamento, allowlist

Observabilidade
  traces, logs de entrada/saída, custo, latência

Duas equipes usando exatamente o mesmo modelo chegam a resultados bem diferentes. Uma dá ferramentas limpas, memória estruturada, permissões claras e execução observável. A outra dá um prompt vago, ferramentas bagunçadas, contexto ruidoso e nenhuma forma de verificar o que aconteceu. O modelo é o mesmo — a condição de trabalho não.

SEÇÃO 03

Loop engineering: ciclos de ação e evidência

Todo agente que usa ferramenta já tem um loop mínimo embutido: chama o modelo, observa o resultado, roda a ferramenta, devolve a observação, repete até terminar.

Loop engineering começa quando você projeta ciclos adicionais de propósito ao redor desse comportamento — não é só "pedir de novo", é um sistema real de trabalho e correção.

Gatilho
  o que inicia um novo ciclo?

Meta
  qual condição específica queremos atingir?

Estado
  o que o próximo ciclo precisa saber?

Política de ação
  o que o agente tem permissão de fazer?

Evidência
  como sabemos que funcionou?

Regra de parada
  quando o ciclo termina?

O ponto mais importante de loop engineering cabe numa frase: não faça loop na confiança, faça loop na evidência. "O agente disse que terminou" não é critério de parada. Critério de parada de verdade é coisa como: os testes passam, o schema valida, as citações resolvem, um revisor aprovou.

Prompt melhora uma resposta. Loop melhora um processo — e isso é um problema de engenharia bem diferente:

• como o sistema verifica o resultado;
• como ele reage a uma falha;
• como ele guarda progresso entre tentativas;
• como ele decide continuar ou parar.

SEÇÃO 04

Graph engineering: o fluxo explícito

Graph engineering responde uma pergunta diferente das outras duas: não "o que o agente deve fazer agora", mas "o que tem permissão de acontecer em seguida".

Passos viram nós, transições viram arestas, e cada coisa que antes ficava escondida dentro de um código cheio de if passa a ser desenhada:

Nó
  chamada de LLM, função determinística,
  agente especialista, revisão humana

Aresta
  transição, ramificação, paralelismo, junção, ciclo

O grafo define
  rota, checkpoint, recuperação, controle

Um exemplo: um agente de pesquisa e publicação, que precisa escolher um tema, juntar fontes, filtrar citações, escrever um rascunho, passar por revisão jurídica e só então publicar.

escopo do tema
   │
   ▼
pesquisa (fontes)
   │
   ▼
triagem de citações
   │
   ▼
síntese e rascunho
   │
   ▼
revisão jurídica ── reprovado ──▶ volta pro rascunho
   │
 aprovado
   │
   ▼
gate humano
   │
   ▼
publicação

Grafo compensa quando o processo tem ramificação real, aprovação, transferência entre especialistas, trabalho em paralelo ou caminho de recuperação. Quando o trabalho é só "dar algumas ferramentas pra um agente e deixar ele resolver", um harness sólido com alguns loops já basta — e formalizar isso num grafo cedo demais só deixa o sistema mais rígido.

SEÇÃO 05

Como as três camadas se relacionam

Elas não são intercambiáveis, mas trabalham juntas — e cada uma cobre uma etapa diferente do mesmo trajeto:

Harness → torna o modelo operacional
Loop    → torna o trabalho iterativo e verificável
Graph   → torna o fluxo explícito e controlável

No exemplo do agente de pesquisa e publicação, as três camadas aparecem juntas, cada uma numa função diferente:

• Harness fornece acesso a navegador, busca, workspace de arquivos, memória, registro de citações e as aprovações necessárias;
• Loop refaz a busca quando a evidência é fraca, corrige citações quebradas e roda verificações antes de seguir adiante;
• Graph controla o caminho — escopo, pesquisa, triagem, síntese, rascunho, revisão, publicação — com um gate humano antes de qualquer coisa ir ao ar.

Um grafo perfeito não salva um harness fraco. Um harness forte ainda desperdiça dinheiro sem bons loops. E loops limpos ficam difíceis de gerenciar quando ramificação e aprovação continuam escondidas em código improvisado, em vez de estarem explícitas num grafo.

SEÇÃO 06

Em qual camada está o problema

Antes de mexer em qualquer coisa, vale diagnosticar em qual camada a falha realmente mora:

"O agente nem consegue operar"
  → conserte o harness
  (falta acesso a ferramenta, estado velho,
   memória fraca, permissão errada, sem observabilidade)

"Quase funciona, mas é inconsistente"
  → conserte o loop
  (primeiro rascunho é bom mas fraco, sucesso
   inconstante, retry sem controle, sem prova de conclusão)

"O processo em si é complexo"
  → conserte o graph
  (muitos especialistas, aprovações,
   lógica de ramificação, caminhos paralelos)

Essa ordem também importa como prioridade: um grafo bonito não conserta um agente que não consegue nem chamar a ferramenta certa. Comece resolvendo o harness, depois o loop, e só formalize o grafo quando o processo realmente pedir.

SEÇÃO 07

Erros comuns

• Desenhar o grafo cedo demais. Times costumam diagramar um workflow gigante antes de ver como o trabalho realmente se comporta. Melhor começar com um harness mais simples, coletar traces reais e só formalizar em grafo o que de fato precisa de controle.
• Deixar o mesmo modelo escrever e avaliar o próprio trabalho sem nenhuma proteção. Autoavaliação ajuda, mas carrega os mesmos pontos cegos. Prefira verificação determinística onde der, um avaliador externo, ou aprovação humana em ações de alto impacto.
• Usar "tenta de novo" como se fosse um loop. Isso não é design de loop, é vazamento de custo sem controle. Todo loop precisa de meta mensurável, evidência real, limite de tentativas e regra de escalonamento.
• Tratar o harness como gaveta de bagunça. Mais ferramenta não é sinônimo de agente melhor — é mais chance de escolha errada, contexto ruidoso e superfície de risco maior. Um bom harness é enxuto, não lotado.
• Culpar o modelo por falha de orquestração. Um modelo não compensa API quebrada, estado velho, condição de parada ausente ou schema de ferramenta mal descrito. A falha é da camada que deveria ter resolvido isso — quase nunca do modelo.

SEÇÃO 08

Checklist prático

HARNESS

• as ferramentas são estreitas e bem documentadas?
• o estado é durável entre sessões?
• as permissões seguem o mínimo necessário?
• dá pra pausar, inspecionar e retomar a execução?
• os traces estão visíveis pra quem opera?

LOOP

• qual evidência prova que o resultado está certo?
• que feedback volta pro agente quando falha?
• quantas tentativas são permitidas?
• qual é a regra de parada?
• o que acontece quando o orçamento acaba?

GRAPH

• quais caminhos precisam ser determinísticos?
• o que pode rodar em paralelo?
• onde estão os gates humanos?
• que estado é compartilhado entre nós?
• onde começam os caminhos de recuperação?

SEÇÃO 09

Conclusão

O que costuma ser chamado de "o agente" na verdade é um sistema de três camadas com responsabilidades bem diferentes:

Harness engineering:
constrói as condições de operação do modelo.

Loop engineering:
transforma o trabalho em ciclos iterativos e verificáveis.

Graph engineering:
deixa o fluxo de decisão explícito e controlável.

O modelo raramente é o diferencial em produção. O que separa um protótipo de brinquedo de um sistema confiável é a engenharia construída ao redor dele — e diagnosticar a falha na camada certa é o que evita meses depurando o lugar errado.