Um Guia Prático para as 3 Camadas que as Pessoas Insistem em Misturar
A maioria das pessoas fala sobre agentes de IA como se fosse uma coisa só.
Não é.
Quando um agente vai além de uma demonstração simples e começa a interagir com arquivos, APIs, documentos, clientes ou código de produção, você não está mais apenas "dando um prompt para um modelo".
Você está projetando um sistema.
E nesse sistema, três conceitos são constantemente confundidos:
- Engenharia de harness (ambiente de execução)
- Engenharia de loops (ciclos)
- Engenharia de grafos (fluxos de trabalho)
Eles todos orbitam o mesmo modelo.
Todos afetam a confiabilidade.
E sim, todos podem conter loops.
Mas eles resolvem problemas diferentes.
Se você os misturar, vai acabar depurando a camada errada.
A Resposta em 30 Segundos
Aqui está a versão simplificada:
- Engenharia de harness constrói o ambiente ao redor do modelo
- Engenharia de loops projeta o ciclo repetitivo de trabalho e feedback
- Engenharia de grafos torna a topologia do fluxo de trabalho explícita
Um bom modelo mental é:
Ambiente → Feedback → Fluxo
- O harness dá ao modelo ferramentas, memória, controle e um espaço de trabalho
- O loop decide como o trabalho é repetido, verificado e melhorado
- O grafo define qual etapa pode acontecer em seguida
Essa é a diferença.
Por Que Esses Termos Importam Agora
Um modelo bruto não consegue fazer trabalho real sozinho.
Ele não consegue:
- manter o estado do projeto entre sessões
- chamar ferramentas com segurança
- inspecionar um navegador
- aplicar permissões
- repetir trabalhos com falha
- validar a qualidade da saída
- rotear tarefas entre especialistas
- parar no momento certo
Tudo isso vem do sistema ao seu redor.
À medida que o software de agentes amadurece, uma pilha prática está emergindo:
- O harness dá ao modelo as condições de operação
- Os loops tornam o trabalho repetível e verificável
- O grafo torna fluxos de trabalho complexos explícitos e controláveis
Quando você enxerga essas como camadas separadas, grande parte da confusão sobre arquitetura de IA desaparece.
O Que Um Harness Sério Geralmente Inclui
- Injeção de Contexto
O que o modelo vê antes de agir:
- instruções
- conhecimento recuperado
- estado da conversa
- memória
- políticas
- regras específicas da tarefa
- Superfícies de Ação
O que o modelo pode fazer:
- chamadas de API
- ações no navegador
- comandos de shell
- execução de código
- ferramentas MCP
- bancos de dados
- funções personalizadas
- Persistência
O que sobrevive ao longo do tempo:
- arquivos
- checkpoints
- estado da sessão
- logs de progresso
- histórico do git
- memória de longo prazo
- Controle de Execução
Como a execução é gerenciada:
- repetições (retries)
- timeouts
- orçamentos
- seleção de modelo
- inicialização de subagentes
- portões de aprovação
- Segurança e Governança
O que mantém o sistema seguro:
- permissões de privilégio mínimo
- isolamento
- listas de permissão
- tratamento de segredos
- aprovação humana
- Observabilidade
O que permite depurar o sistema:
- rastreamentos (traces)
- entradas e saídas de ferramentas
- transições de estado
- latência
- custo
- resultados de avaliação
Por Que a Engenharia de Harness é Importante
Duas equipes podem usar o mesmo modelo e obter resultados completamente diferentes.
Por quê?
Porque uma equipe dá ao modelo:
- ferramentas limpas
- estado estável
- memória estruturada
- permissões claras
- execução observável
E a outra dá a ele:
- um prompt vago
- ferramentas bagunçadas
- contexto ruidoso
- sem memória
- sem verificação
O modelo pode ser o mesmo.
As condições de trabalho não são.
A engenharia de harness é importante sempre que o agente:
- não consegue acessar a capacidade certa
- perde contexto entre sessões
- age de forma inconsistente entre ambientes
- não pode ser auditado
- tem permissão demais
- não consegue se recuperar de forma limpa após uma interrupção
Se o modelo não consegue operar de forma confiável, o primeiro lugar para olhar é o harness.
2. Engenharia de Loop
O Que É
Todo agente que usa ferramentas já tem um pequeno loop embutido:
- chamar o modelo
- observar o resultado
- executar ferramentas
- alimentar o modelo com as observações
- repetir até terminar
A engenharia de loop começa quando você projeta intencionalmente ciclos adicionais ao redor desse comportamento.
Não apenas "pergunte de novo".
Não apenas "tente novamente".
Mas um sistema real de trabalho e feedback.
Anatomia de um Bom Loop
Gatilho
O que inicia um novo ciclo?
- solicitação do usuário
- teste com falha
- novo documento
- execução agendada
- webhook
- feedback de um avaliador
Objetivo
Qual condição específica estamos tentando alcançar?
Não "continue melhorando".
Um alvo real.
Estado
O que o próximo ciclo precisa saber?
- rascunho atual
- tentativa anterior
- resultados das ferramentas
- erros
- status do progresso
Política de Ação
O que o agente pode fazer?
- editar
- delegar
- chamar ferramentas
- gastar tokens
- escrever arquivos
- abrir PRs
Evidência
Como sabemos se funcionou?
- testes
- validação de esquema
- citações
- diffs
- métricas
- aprovação do revisor
Feedback
O que exatamente falhou?
O feedback deve ser compacto e acionável.
Regra de Parada
Quando termina?
- sucesso
- timeout
- orçamento esgotado
- número máximo de tentativas atingido
- falha irrecoverável
- escalonamento para um humano
O Princípio Mais Importante na Engenharia de Loop
**Não faça loop baseado em confiança.
Faça loop baseado em evidências.**
"O agente diz que está pronto" não é uma condição de parada.
Uma condição de parada real se parece mais com:
- os testes passam
- o esquema valida
- as citações se resolvem
- o revisor aprova
- a verificação de política está limpa
Isso é engenharia de loop.
Por Que Engenharia de Loop Não é Apenas Engenharia de Prompt
Um prompt diz ao modelo o que fazer durante uma chamada.
Um loop define o que o sistema faz após a chamada.
Isso inclui:
- como ele verifica os resultados
- como ele reage a falhas
- como ele persiste o progresso
- como ele decide continuar
- como ele termina
O prompting melhora uma resposta.
Um loop melhora um processo.
Esse é um problema de engenharia muito diferente.
3. Engenharia de Grafo
O Que É
A engenharia de grafo torna a estrutura do fluxo de trabalho explícita.
Ela responde a uma pergunta diferente:
Não apenas “o que o agente deve fazer?” Mas “o que pode acontecer em seguida?”
Na engenharia de grafo:
- as etapas são nós
- as transições são arestas
- a ramificação é explícita
- o trabalho paralelo é explícito
- as junções são explícitas
- as repetições são explícitas
- as interrupções humanas são explícitas
O grafo se torna o mapa de controle do sistema.
O Que Os Engenheiros de Grafo Realmente Projetam
Limites dos Nós
O que pertence a:
- uma função determinística
- uma chamada de LLM
- um agente especialista
- uma etapa de revisão humana
Esquema de Estado
O que cada nó pode ler ou escrever.
Condições de Roteamento
Que evidência move o trabalho:
- para frente
- para trás
- para os lados
- para escalonamento
Concorrência
O que pode ser executado em paralelo, e o que deve esperar.
Ciclos e Saídas
Onde as repetições são permitidas, quantas são permitidas e como elas param.
Durabilidade
Onde os checkpoints acontecem e como o fluxo de trabalho retoma após uma interrupção.
Quando os Grafos Valem a Pena
Os grafos são valiosos quando o processo inclui:
- ramificação significativa
- aprovações
- transferências entre especialistas
- trabalho paralelo
- caminhos de recuperação
- fluxos de trabalho de várias etapas com pontos de controle explícitos
Eles são menos úteis quando o trabalho é simplesmente:
“Dê algumas ferramentas a um agente e deixe-o trabalhar.”
Nesse caso, um harness sólido com alguns loops pode ser suficiente.
Um grafo adiciona clareza, mas também adiciona estrutura.
Muita estrutura muito cedo pode tornar o sistema frágil.
Como as 3 Camadas Funcionam Juntas
Digamos que você esteja construindo um agente de pesquisa e publicação.
Ele tem que:
- definir o escopo de um tópico
- reunir fontes
- triar citações
- redigir um relatório
- passar pela revisão jurídica
- publicar somente após aprovação
Aqui está como as camadas se mapeiam:
Harness
Fornece:
- acesso ao navegador
- ferramentas de busca
- espaço de trabalho de arquivos
- memória
- citações
- aprovações
- rastreamentos (traces)
- roteamento de modelo
Loop
Lida com:
- repetir a recuperação de fontes quando a evidência é fraca
- corrigir falhas de citação
- executar verificações de avaliação
- atualizar o trabalho quando o mercado muda
Grafo
Controla o caminho:
- definição de escopo
- pesquisa
- triagem
- síntese
- redação
- revisão
- publicação
Com um portal humano antes do lançamento.
É por isso que as 3 camadas não são intercambiáveis.
Elas trabalham juntas, mas não são a mesma coisa.
Diagnostique a Falha Antes de Escolher a Correção
Aqui está a regra prática:
Se o agente não consegue operar, corrija o harness
Exemplos:
- falta de acesso a ferramentas
- estado desatualizado
- memória fraca
- permissões ruins
- sem observabilidade
Se o agente quase funciona, mas é não confiável, corrija o loop
Exemplos:
- primeiro rascunho está próximo, mas é fraco
- sucesso é inconsistente
- repetições são descontroladas
- não há prova de conclusão
Se o processo em si é complexo, corrija o grafo
Exemplos:
- muitos especialistas
- aprovações
- lógica de ramificação
- caminhos paralelos
- transferências estruturadas
Erros Comuns
1. Construir o Grafo Muito Cedo
As equipes frequentemente diagramam um fluxo de trabalho enorme antes de ver como o trabalho realmente se comporta.
Melhor abordagem:
- comece com um harness mais simples
- colete rastreamentos (traces)
- encontre os padrões estáveis
- formalize apenas o que merece controle
2. Deixar o Mesmo Modelo Escrever e Avaliar Sem Salvaguardas
A auto-revisão pode ajudar, mas compartilha os mesmos pontos cegos.
Prefira:
- verificações determinísticas quando possível
- contexto de revisor separado
- avaliadores externos
- aprovação humana para ações de alto impacto
3. Usar “Continue Tentando” Como Um Loop
Isso não é um design de loop.
Isso é um vazamento de custo descontrolado.
Todo loop precisa de:
- um objetivo mensurável
- evidência real
- limites de repetição
- regras de escalonamento
4. Tratar o Harness Como Uma Gaveta de Bagunça
Mais ferramentas não significam automaticamente agentes melhores.
Muitas ferramentas criam:
- erros de seleção
- contexto ruidoso
- confiabilidade fraca
- superfície de risco maior
Um bom harness não é lotado.
Ele é preciso.
5. Culpar o Modelo por Falhas de Orquestração
Um modelo não pode compensar por:
- APIs quebradas
- estado desatualizado
- condições de saída ausentes
- esquemas de ferramentas vagos
- modos de falha invisíveis
Corrija a camada que é dona da falha.
Uma Lista de Verificação Simples para Produção
Harness
- As ferramentas são estreitas e documentadas?
- O estado é durável?
- As permissões são de privilégio mínimo?
- Os operadores podem pausar, inspecionar e retomar?
- Os rastreamentos (traces) são visíveis?
Loop
- Que evidência prova o sucesso?
- Que feedback é retornado em caso de falha?
- Quantas repetições são permitidas?
- Qual é a regra de parada?
- O que acontece quando o orçamento acaba?
Grafo
- Quais caminhos devem ser determinísticos?
- O que pode ser executado em paralelo?
- Onde estão os portões humanos?
- Qual estado é compartilhado?
- Onde os caminhos de recuperação começam?
Avaliação
- Você pode reproduzir rastreamentos (traces) reais?
- Você pode comparar versões?
- Você pode atribuir uma melhoria a uma mudança real?
Operações
- Você está rastreando custo?
- latência?
- taxa de falha?
- taxa de intervenção?
- sucesso da tarefa em produção?
A Maneira Mais Simples de Lembrar a Diferença
Se você só lembrar de uma coisa, lembre-se disso:
- Engenharia de harness torna o modelo operacional
- Engenharia de loop torna o trabalho iterativo e verificável
- Engenharia de grafo torna o caminho de execução explícito e controlável
Nenhuma substitui as outras.
Um grafo perfeito não salvará um harness fraco.
Um harness forte ainda desperdiçará dinheiro sem bons loops.
E loops limpos se tornam difíceis de gerenciar quando a ramificação e as aprovações permanecem escondidas em código ad hoc.
Sistemas de agentes confiáveis aparecem quando todas as 3 camadas são projetadas intencionalmente.
Essa é a pilha de arquitetura real.
Conclusão Final
As pessoas continuam falando sobre agentes de IA como se o grande avanço fosse o modelo.
Em produção, esse raramente é o verdadeiro diferencial.
O diferencial é o sistema ao redor do modelo:
- o harness que permite que ele trabalhe
- os loops que permitem que ele melhore
- o grafo que permite que ele opere sob controle
É assim que agentes de brinquedo se tornam sistemas reais.
Se você leu até aqui:
- SALVE ISTO NOS FAVORITOS.
- Siga @LunarResearcher
- Siga meu Substack
- Siga meu Canal Privado no Telegram
