---
title: "Entendendo, em ordem, a engenharia de harness, loop e grafo dos agentes de IA"
locale: pt
category: knowledge_base
category_name: "Base de Conhecimento"
translation_status: reviewed
license: cc_by
author: "injoys"
source_url: https://injoys.com/en/articles/ai-agent-harness-loop-graph-engineering
published_at: 2026-08-16T00:45:12+09:00
---

# Entendendo, em ordem, a engenharia de harness, loop e grafo dos agentes de IA

> O harness projeta o ambiente de trabalho e os mecanismos de controle do agente; o loop, as regras de repetição e encerramento; e o grafo, os estados permitidos e as rotas de transição. É mais correto entender os três termos como perspectivas práticas para lidar com a autonomia e os riscos dos agentes de IA do que como uma classificação oficialmente padronizada.

## Key Points

- A engenharia de harness consiste em projetar o contexto, as ferramentas, as permissões, a validação, os logs e os procedimentos de aprovação externos ao modelo como um único ambiente de execução.
- A engenharia de loop define as condições, o orçamento e os critérios de encerramento para que o agente repita o ciclo de planejamento, execução, validação e correção.
- A engenharia de grafo usa estados e regras de transição para limitar ou ajustar explicitamente as rotas que o agente pode escolher.
- Para a maioria das organizações, é mais eficiente aprimorar primeiro o harness e a estrutura de avaliação de um único agente do que adotar um grafo complexo com múltiplos agentes.
- Aprovar apenas um relatório resumido produzido por IA não é suficiente para códigos de alto risco; também é necessário verificar os testes, o escopo das alterações, os limites de segurança e os resultados originais.

À medida que os agentes de IA passaram a assumir tarefas de longa duração, tornou-se difícil obter resultados estáveis apenas escrevendo bons prompts. Isso ocorre porque também é necessário projetar quais informações o agente verá, quais ferramentas usará, quando repetirá uma ação, por quais caminhos seguirá e em quais pontos deverá obter aprovação humana.

Ao explicar esse problema, aparecem com frequência as expressões **engenharia de harness**, **engenharia de loops** e **engenharia de grafos**. Elas não são padrões internacionais nem classificações acadêmicas rigorosamente consensuais. Há sobreposição entre elas, e seus significados podem variar de acordo com o produto e a equipe de desenvolvimento. Portanto, em vez de memorizá-las como termos da moda de cada ano, é mais útil distingui-las pelas perguntas de controle às quais cada uma busca responder.

## Comparação dos três conceitos em uma visão geral

| Conceito | Pergunta central | Principal objeto de projeto | Mecanismos típicos de prevenção de falhas |
|---|---|---|---|
| Engenharia de harness | Em qual ambiente e sob quais regras o agente trabalha? | Contexto, ferramentas, permissões, sandbox, hooks, logs, aprovações, avaliações | Privilégio mínimo, aprovação de comandos perigosos, execução de testes, seleção de contexto |
| Engenharia de loops | O que deve ser repetido e quando deve parar? | Ciclos de planejamento, execução e verificação, processamento de eventos, novas tentativas, orçamento, condições de encerramento | Número máximo de repetições, limites de tempo e tokens, avaliação de progresso, encaminhamento em caso de falha |
| Engenharia de grafos | Quais estados e caminhos são permitidos? | Nós, estados, transições, ramificações, processamento paralelo, checkpoints | Transições proibidas, validação de estado, nós de aprovação, caminhos de recuperação |

Em resumo, **o harness define o ambiente e os limites**, **o loop define as regras de repetição** e **o grafo define a estrutura dos caminhos possíveis**. Em sistemas reais, pode haver um loop dentro de um nó do grafo, enquanto o grafo inteiro é executado dentro de um único harness.

## Como os métodos de controle de agentes evoluíram

### Agentes iniciais: workflows predefinidos complementavam a autonomia

Os primeiros agentes de IA generativa frequentemente esqueciam seus objetivos em tarefas longas, repetiam chamadas incorretas de ferramentas ou produziam resultados sem fundamento. Por isso, os desenvolvedores dividiam tarefas grandes em etapas menores e fixavam as entradas e saídas de cada etapa.

Nessa abordagem, uma pessoa descreve todo o processo como uma cadeia, um fluxograma ou uma máquina de estados, enquanto o LLM assume tarefas limitadas, como classificação, extração, resumo e elaboração de rascunhos. Frameworks como LangGraph são usados para representar ramificações, ciclos, checkpoints e intervenção humana mantendo o estado.

No entanto, a orquestração baseada em grafos não é uma abordagem ultrapassada que terminou em determinado ano. Ainda hoje, grafos explícitos são adequados para trabalhos em que auditabilidade, reprodutibilidade, conformidade regulatória ou procedimentos precisos de recuperação são importantes.

### Melhoria do desempenho dos modelos: de caminhos fixos ao uso dinâmico de ferramentas

Com o avanço da capacidade de raciocínio e de uso de ferramentas, um único agente passou a poder escolher ações como pesquisar, editar código, executar testes e ler arquivos de acordo com a situação. As abordagens da família ReAct são uma estrutura representativa que alterna raciocínio, ação e observação.

Essa mudança reduziu a necessidade de uma pessoa definir previamente todas as ramificações. Por outro lado, tornou mais importante gerenciar as informações lidas pelo agente, as permissões que ele possui, o custo de execução e os métodos de recuperação de erros. É nesse contexto que a engenharia de contexto e a engenharia de harness passam a ocupar o centro da prática.

### Tarefas longas e múltiplos agentes: a recombinação de loops e grafos

Em tarefas longas, ciclos repetidos de planejamento, execução e verificação são mais importantes do que uma única chamada ao modelo. Quando vários agentes participam, também é necessário especificar papéis, formatos dos entregáveis, permissões e condições de encerramento. Ao mesmo tempo, deixar loops autônomos completamente sem supervisão pode causar explosão de custos, novas tentativas infinitas, hacking de recompensa e otimização de objetivos incorretos.

Por isso, os sistemas modernos de agentes são projetados para **combinar trechos em que a autonomia é permitida com trechos controlados de forma determinística**, em vez de eliminar a autonomia. Isso não é um simples retorno às antigas cadeias fixas, mas uma forma de cercar a execução flexível com estados, transições e políticas.

Essa mudança representa mais uma alteração de ênfase no projeto do que uma cronologia exata. Grafos, loops e harnesses coexistem desde o início e continuam sendo usados em conjunto.

## O que a engenharia de harness abrange

O harness não é o modelo-base em si, mas **o sistema de execução que envolve o modelo para que ele realize o trabalho de fato**. Mesmo usando o mesmo modelo, a taxa de sucesso, o custo, a segurança e a reprodutibilidade podem variar muito conforme o harness.

### Principais componentes de um harness

1. **Sistema de instruções**: diretrizes do sistema, regras do repositório, padrões de código, prioridades e ações proibidas
2. **Fornecimento de contexto**: pesquisa, seleção de arquivos, resumo, memória e inserção de documentos no momento necessário
3. **Interfaces de ferramentas**: edição de arquivos, terminal, navegador, banco de dados e APIs externas
4. **Permissões e isolamento**: escopo de leitura e gravação, acesso a informações secretas, restrições de rede e sandbox
5. **Mecanismos de verificação**: testes, linters, verificação de tipos, validação de schemas e checagem de fatos
6. **Aprovação humana**: aprovação de ações difíceis de reverter, como implantação, pagamento, exclusão e envio externo
7. **Observabilidade**: registros de chamadas, custos, latência, erros, histórico de alterações e fundamentos das decisões
8. **Políticas de recuperação**: novas tentativas, restauração do estado anterior, interrupção da tarefa e encaminhamento ao responsável

Arquivos de instruções de projeto ou hooks do Claude Code podem ser vistos como exemplos de componentes de um harness. No entanto, uma funcionalidade específica de um produto não representa todo o harness.

### Diferença em relação à engenharia de contexto

A engenharia de contexto otimiza quais informações e instruções devem ser incluídas na chamada atual ao modelo. Isso inclui recuperar apenas documentos relevantes por meio de pesquisa, resumir conversas antigas, salvar o estado da tarefa em arquivos externos e separar o contexto por subtarefa.

A engenharia de harness é mais ampla. Além do contexto, ela abrange permissões de ferramentas, ambiente de execução, aprovações, verificações, logging e limites de custo. Portanto, a engenharia de contexto é uma parte central do harness, mas é impreciso usar os dois termos como se tivessem exatamente o mesmo significado.

## O essencial na engenharia de loops são as condições de encerramento

Um loop faz com que o agente verifique o resultado depois de produzi-lo e tente novamente caso seja insuficiente. O importante não é a repetição em si, mas **a definição de progresso e as condições de interrupção**.

### Tipos representativos de loops

- **Loop de verificação**: após criar um rascunho, verifica-o com testes ou critérios de avaliação e corrige os itens que falharam.
- **Loop orientado a eventos**: inicia uma tarefa quando ocorre um evento externo, como um e-mail, uma notificação, uma alteração de código ou dados de sensores.
- **Loop de exploração**: investiga várias hipóteses ou fontes e ajusta o escopo da busca até obter evidências suficientes.
- **Loop de melhoria**: escolhe a próxima estratégia com base no resultado anterior e nos valores de avaliação. Como otimizar apenas uma pontuação pode causar hacking de recompensa, são necessários vários critérios de avaliação e revisão humana.
- **Loop de recuperação**: classifica a causa do erro, faz novas tentativas dentro do escopo permitido e encaminha a tarefa a uma pessoa caso o problema não seja resolvido.

### Contratos necessários para loops seguros

Um contrato entre agentes não é um contrato jurídico, mas uma especificação de execução que define entradas, saídas e responsabilidades. É recomendável incluir os seguintes itens.

| Item do contrato | O que especificar |
|---|---|
| Objetivo | Resultado que deve ser concluído e itens fora do escopo |
| Entrada | Dados que podem ser usados, atualidade e nível de confiança |
| Saída | Schema JSON, formato do documento, evidências obrigatórias e resultados de testes |
| Permissões | Ferramentas permitidas, escopo de arquivos, envio externo e permissões de alteração |
| Verificação | Testes e critérios de avaliação que devem ser aprovados |
| Orçamento | Tokens, tempo, número de chamadas e quantidade de tarefas paralelas |
| Encerramento | Condições de sucesso, ausência de progresso, esgotamento do orçamento e detecção de risco |
| Encaminhamento | Qual pessoa ou agente assumirá em caso de falha |

Se as condições de conclusão forem ambíguas, o agente poderá considerar que está avançando mesmo enquanto apenas altera frases ou repete a mesma pesquisa. Em vez de estabelecer somente um número máximo de repetições, é melhor considerar em conjunto a qualidade do resultado, o aumento de novas informações, a evolução dos erros e o custo.

## A engenharia de grafos estrutura os limites da autonomia

Um grafo representa o trabalho por meio de nós e conexões. Um nó pode ser uma chamada ao modelo, a execução de uma ferramenta, uma aprovação humana ou um processo de verificação, enquanto as conexões representam a próxima ação de acordo com o estado.

### Diferença entre cadeias e grafos

- **Uma cadeia** é adequada para procedimentos lineares que seguem de A para B e de B para C.
- **Um grafo** é adequado para tarefas que exigem ramificações condicionais, repetições, execução paralela, recuperação de falhas e salvamento intermediário.
- **Um grafo dinâmico** permite que o modelo proponha a próxima subtarefa ou o próximo caminho durante a execução.
- **Um grafo restrito** faz com que o modelo se mova somente entre os nós e as transições permitidos, mesmo quando é ele que faz a escolha.

O objetivo do projeto moderno de grafos não é fazer com que uma pessoa decida previamente todas as ações. Trata-se de inserir na estrutura **condições invariáveis que devem ser respeitadas**, como exigir a passagem por um nó de aprovação antes da exclusão de dados ou impedir a transição de um estado de falha nos testes para o estado de implantação.

### Sinais de que um grafo é necessário

Se várias das condições abaixo se aplicarem, vale a pena considerar um grafo explícito.

- Há um ponto de recuperação claro ao qual se deve retornar após uma falha.
- Existe uma etapa que exige obrigatoriamente aprovação humana.
- É necessário executar várias tarefas em paralelo e depois combinar os resultados.
- As ferramentas ou permissões disponíveis variam de acordo com o estado.
- É necessário auditar ou reproduzir todo o caminho de execução.
- Um loop de um único agente repete a mesma falha.

Transformar em grafo até mesmo um simples resumo de documento ou uma única conversão de dados pode apenas aumentar a complexidade.

## Ordem de aplicação prática: começar pelo harness e expandir conforme necessário

Para a maioria das equipes, a ordem a seguir é realista.

1. **Defina uma única tarefa e os critérios de sucesso.** Primeiro, reúna as entradas, as saídas esperadas e os casos de falha.
2. **Crie um harness mínimo.** Forneça apenas o contexto e as ferramentas necessários e configure permissões, testes, logs e limites de custo.
3. **Construa um conjunto de avaliação.** Inclua não apenas casos normais, mas também solicitações ambíguas, documentos incorretos, erros de ferramentas e tentativas de exceder permissões.
4. **Transforme em loops os pontos que exigem repetição.** Permita novas tentativas apenas nos trechos em que a verificação e a correção realmente elevam a qualidade.
5. **Promova para um grafo quando as ramificações e a recuperação se tornarem complexas.** Especifique estados e transições e coloque nós de aprovação antes de ações arriscadas.
6. **Use múltiplos agentes apenas quando a separação do trabalho trouxer benefícios.** Se não forem necessárias exploração paralela ou diferentes funções especializadas, um único agente pode ser mais simples e barato.

## Diferenças de aplicação em programação e pesquisa

| Item | Tarefas de programação | Tarefas de pesquisa |
|---|---|---|
| Possibilidade de verificação | A verificação automática por testes, build e checagem de tipos é relativamente fácil | É necessário avaliar de forma abrangente a qualidade das fontes, omissões e evidências conflitantes |
| Valor da exploração dinâmica | Pode ser limitado quando o escopo das alterações está claro | É alto ao comparar diferentes caminhos de pesquisa e hipóteses |
| Principais riscos | Alterações incorretas, vulnerabilidades de segurança e código ajustado apenas aos testes | Alegações sem fontes, materiais duplicados e viés de confirmação |
| Controles adequados | Limitação do escopo do repositório, testes, revisão de diff e aprovação de implantação | Registro de fontes, pesquisa independente, busca de evidências contrárias e verificação de citações |

Não se pode afirmar categoricamente que workflows dinâmicos sejam sempre ineficientes para programação e sempre vantajosos para pesquisa. Uma migração de grande escala que possa ser testada pode ser adequada a agentes autônomos, enquanto uma consulta factual com resposta clara pode ser mais eficiente com um procedimento fixo de pesquisa. As variáveis centrais não são a área, mas **a clareza do objetivo, a possibilidade de verificação automática, o espaço de exploração e o custo dos erros**.

## A revisão de código não desaparece; o que muda é a unidade de revisão

Quando agentes escrevem código, os desenvolvedores passam a assumir mais a função de supervisionar requisitos, design, resultados de testes, escopo das alterações e riscos, em vez de digitar diretamente cada linha. Resumos de Pull Requests e relatórios de agentes podem acelerar a revisão.

No entanto, ler apenas o resumo e aprovar não é uma opção padrão segura. Alterações omitidas pelo agente ou lógicas que ele compreendeu de forma incorreta podem não aparecer nem mesmo no resumo. Nas situações abaixo, é necessário revisar diretamente o diff original e o código relacionado.

- Alterações em autenticação, pagamentos, dados pessoais, criptografia e controle de acesso
- Alterações no schema do banco de dados ou migrações irreversíveis
- Código sensível a desempenho e concorrência
- Refatorações de grande escala fora do escopo dos testes
- Alterações em dependências externas, configurações de implantação e tratamento de informações secretas
- Casos em que a explicação do agente não corresponde ao diff real

Human-in-the-loop não significa que uma pessoa apenas pressione formalmente um botão. Também inclui fornecer evidências das alterações, resultados de testes, possibilidades de falha e procedimentos de reversão para que a pessoa possa tomar uma decisão.

## Armadilhas frequentes

### Múltiplos agentes sem propósito

Aumentar o número de agentes gera custos de coordenação de papéis, chamadas duplicadas, transferência de contexto e combinação de resultados. Se não houver necessidade de exploração paralela a partir de diferentes perspectivas nem motivo para separar o contexto, um único agente é melhor.

### Workflows dinâmicos sem limites

Permitir que o agente continue criando subtarefas faz com que o custo de tokens e chamadas de ferramentas aumente rapidamente. O custo é determinado aproximadamente pela soma do custo dos tokens de entrada e saída em cada etapa, do custo das ferramentas, do número de agentes paralelos e da quantidade de repetições. É necessário limitar separadamente o número de chamadas, a quantidade de execuções simultâneas, o orçamento total e o tempo máximo de execução.

### Otimização de uma única métrica de avaliação

Se o único objetivo for a taxa de aprovação nos testes, podem surgir otimizações incorretas, como enfraquecer os testes ou ocultar o tratamento de exceções. É necessário usar em conjunto qualidade, segurança, volume de alterações, custo, latência e avaliação humana.

### Confundir inserção de documentos com fine-tuning

Os resultados podem mudar de forma persistente por meio da pesquisa de documentos ou das instruções do projeto, mas os pesos do modelo não são alterados. Em sentido amplo, isso pode ser descrito como um efeito de aprendizagem do sistema, mas, rigorosamente, trata-se de adaptação por meio de memória externa e contexto. Os documentos ou o índice de pesquisa precisam ser preservados para que as mudanças sejam mantidas nas execuções seguintes.

## Avaliação, segurança e viabilidade econômica frequentemente negligenciadas na operação

O projeto de agentes não termina no diagrama de arquitetura. Na operação real, é importante ter **um sistema que meça o que realmente aconteceu, e não apenas o que foi permitido**.

### Métricas operacionais mínimas

- Taxa de sucesso das tarefas e taxa de correções humanas
- Custo de modelos e ferramentas por tarefa e tempo total de execução
- Número de repetições e proporção de chamadas consumidas sem progresso
- Número de solicitações de aprovação, recusas e tentativas de exceder permissões
- Chamadas incorretas de ferramentas e taxa de sucesso da recuperação
- Proporção de resultados enviados sem fontes ou testes
- Grau de variação dos resultados para a mesma entrada

### Condições invariáveis necessárias para a segurança

- As instruções de documentos externos não têm prioridade superior à política do sistema.
- Informações secretas não são expostas desnecessariamente na entrada do modelo nem nos logs.
- As permissões de leitura são separadas das permissões de gravação, exclusão e implantação.
- Envios externos e ações irreversíveis exigem aprovação separada ou verificação por políticas.
- O agente não pode modificar arbitrariamente seus próprios critérios de avaliação, testes ou logs de auditoria.

É mais seguro impor essas condições invariáveis por meio de sandbox, controle de acesso, transições de grafo e verificadores independentes do que por uma única frase no prompt. A gestão de riscos da IA generativa deve abranger não apenas a precisão do modelo, mas também o ambiente operacional, a supervisão humana e a resposta a incidentes.

## Qual conceito deve ser aprendido primeiro

Na prática atual, o primeiro conceito a dominar é a engenharia de harness. Um contexto preciso, privilégio mínimo, verificação automática, logs, aprovações e limites de custo podem reduzir muitas falhas de um único agente.

Em seguida, adicione loops com condições de encerramento às tarefas em que a repetição melhora a qualidade. Quando as ramificações, o processamento paralelo, a recuperação e os procedimentos de aprovação se tornarem complexos, represente-os explicitamente com grafos. Antes de adotar termos complexos, a prioridade é tornar mensuráveis os objetivos, as permissões, as evidências, os custos e as condições de interrupção do agente.

## FAQ

### Qual é a diferença entre engenharia de harness e engenharia de prompts?
A engenharia de prompts lida principalmente com as instruções e formulações fornecidas ao modelo. A engenharia de harness é o projeto de um ambiente de execução mais amplo, que inclui não apenas prompts, mas também busca de contexto, ferramentas, permissões, sandbox, testes, logs, aprovação humana e recuperação de erros.

### Engenharia de contexto e engenharia de harness significam a mesma coisa?
Não. A engenharia de contexto se concentra em selecionar, buscar, resumir e organizar as informações que o modelo precisa saber no momento. A engenharia de harness lida, além da gestão de contexto, com permissões, ferramentas, validação, limites de custos e políticas operacionais.

### Qual é a diferença mais importante entre um loop e um grafo?
Um loop define o que deve ser repetido, como planejamento, execução, validação e correção, e quando parar. Um grafo define quais estados existem e como é possível passar de um estado para outro. Um grafo pode conter um ou mais loops.

### Todos os agentes de AI precisam de um framework de grafos como o LangGraph?
Não. Para tarefas simples e curtas, um único agente e um harness mínimo podem ser suficientes. O valor de um grafo aumenta quando são necessários ramificações condicionais, processamento paralelo, salvamento intermediário, recuperação de falhas, aprovação humana ou auditoria dos caminhos de execução.

### Um sistema multiagente sempre apresenta desempenho melhor do que um único agente?
Não. Um sistema multiagente é útil quando são necessários pesquisa paralela, diferentes funções especializadas e separação de contexto. Se as funções se sobrepuserem ou os objetivos forem vagos, isso poderá apenas aumentar o trabalho duplicado, os erros de transferência, a demora e os custos.

### Como impedir que o loop de um agente se repita infinitamente?
É necessário definir não apenas um número máximo de repetições, mas também orçamentos de tempo, tokens, chamadas de ferramentas e custos. O sistema deve considerar como falta de progresso uma situação em que não haja novas informações nem redução de erros e ser projetado para interromper a execução ou encaminhá-la a uma pessoa quando determinado limite for atingido.

### É suficiente revisar apenas o resumo do Pull Request do código escrito pela AI?
O resumo é apenas um material de apoio e não substitui as alterações originais. Em alterações de alto risco, como autenticação, pagamentos, dados pessoais, migração de dados e configurações de implantação, é necessário revisar diretamente o diff real, a cobertura dos testes, as dependências e os procedimentos de reversão.

### Se os documentos da empresa forem fornecidos continuamente ao modelo, isso significa que ele foi treinado?
Os resultados podem mudar de forma persistente, mas isso não significa que os pesos do modelo tenham sido atualizados. Trata-se de uma adaptação no nível do sistema, que preserva documentos externos, índices de busca, memória e instruções para fornecê-los novamente em execuções posteriores, e deve ser diferenciada do ajuste fino em sentido estrito.

### A engenharia de grafos representa um retorno aos workflows fixos do início?
Não necessariamente. Os grafos modernos se aproximam mais de um controle híbrido: permitem que o agente planeje de forma autônoma e selecione ferramentas em determinados trechos, ao mesmo tempo que restringem explicitamente transições perigosas e pontos de aprovação obrigatória.

### O que deve ser definido primeiro ao projetar um harness?
Primeiro, é necessário definir os critérios de sucesso da tarefa e o custo das falhas. Em seguida, é recomendável fornecer apenas o contexto e as ferramentas necessários e estabelecer permissões mínimas, validação automática, logs de execução, limites de custos e condições de interrupção.

## Sources

- [Anthropic — Construindo agentes eficazes](https://www.anthropic.com/research/building-effective-agents)
- [Anthropic — Engenharia de contexto eficaz para agentes de IA](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents)
- [Anthropic — Como construímos nosso sistema de pesquisa multiagente](https://www.anthropic.com/engineering/multi-agent-research-system)
- [Visão geral do LangGraph](https://docs.langchain.com/oss/python/langgraph/overview)
- [ReAct: Sinergia entre raciocínio e ação em modelos de linguagem](https://arxiv.org/abs/2210.03629)
- [NIST AI 600-1 — Estrutura de Gestão de Riscos de Inteligência Artificial: Perfil de Inteligência Artificial Generativa](https://nvlpubs.nist.gov/nistpubs/ai/NIST.AI.600-1.pdf)

## Images

![Sistema central de IA cercado por setas cíclicas e uma rede de nós de sucesso e falha](https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6ODI0NSwicHVyIjoiYmxvYl9pZCJ9fQ==--3a03e254c3d24990df4c3fc46145a5db24e457ba/ai-eb0e40fe.webp)
![Robô de IA passa de um ambiente seguro por um ciclo de ferramentas e grafo ramificado até validação e alerta](https://injoys.com/rails/active_storage/blobs/proxy/eyJfcmFpbHMiOnsiZGF0YSI6ODI1MSwicHVyIjoiYmxvYl9pZCJ9fQ==--cea797c99aabaa4b8f760264327fe2ee8b34b423/ai-23d7d97a.webp)