Engenharia de Grafos: Como construir sistemas de agentes de IA que não falham em escala

A maioria dos builders ainda projeta agentes de IA como uma linha reta

Pesquisar primeiro

Escrever depois

Revisar em seguida

Publicar por último

Cada etapa espera a anterior, mesmo quando metade delas nunca precisou do resultado anterior

O sistema não ramifica

Não paraleliza

Não sabe se recuperar

Ele só continua alimentando uma janela de contexto até o agente ficar lento, confuso ou caro

O problema não é mais o prompt

O problema é o formato do trabalho

É isso que a engenharia de grafos resolve

Eu publico análises práticas de agentes de IA, workflows e sistemas de produção no Substack

Assine a newsletter aqui

O que a engenharia de grafos realmente significa

Engenharia de grafos é a prática de transformar um workflow agentic em um mapa de execução explícito

Em vez de esconder cada decisão dentro de um único loop do modelo, você define o sistema como nós e arestas

1NODE   = uma unidade delimitada de trabalho
2EDGE   = uma dependência real entre dois nós
3STATE  = os dados que sobrevivem entre os nós
4ROUTER = a regra que seleciona a próxima aresta
5GATE   = a verificação que decide se o trabalho pode continuar

Um nó pode ser um agente, uma chamada de ferramenta, uma função determinística, um verificador ou uma etapa de aprovação humana

Uma aresta define o que pode ser executado em seguida e quais dados cruzam a fronteira

O grafo decide quais loops rodam, em que ordem, com quais ramificações, junções e caminhos de recuperação

Um loop ajuda um agente a melhorar seu trabalho. Um grafo coordena muitos loops em um único sistema

1. Pare de tratar todo "e depois" como uma dependência

A maioria dos workflows de agentes é linear porque é assim que as pessoas escrevem instruções

Faça A, depois B, depois C

Mas sequência não é o mesmo que dependência

Se B não consome a saída de A, não há motivo para B esperar

1RUIM
2
3coletar dados de mercado -> inspecionar repositório -> verificar preços dos concorrentes
4
5MELHOR
6
7                 -> coletar dados de mercado ---------
8SOLICITAÇÃO DO USUÁRIO -> inspecionar repositório ----------> SINTETIZAR
9                 -> verificar preços dos concorrentes ----

A primeira pergunta na engenharia de grafos é simples

A próxima etapa realmente lê a saída da etapa anterior?

Se a resposta for não, corte a aresta

Essa única mudança geralmente transforma uma cadeia lenta em um grafo paralelo rápido

2. Dê a cada nó um contrato

Um nó que você não consegue descrever com precisão é um nó que você não consegue rotear, testar ou substituir

Todo nó útil precisa de quatro coisas

• Uma única função
• Entrada explícita
• Saída estruturada
• Um estado de falha claro

1{
2  "node": "source_researcher",
3  "input": {
4    "topic": "string",
5    "source_type": "primary"
6  },
7  "output": {
8    "claim": "string",
9    "source_url": "string",
10    "confidence": "high | medium | low"
11  },
12  "failure": "no_primary_source_found"
13}

Texto livre força o próximo nó a adivinhar o que aconteceu

Saída estruturada transforma a resposta do modelo em algo em que o grafo pode confiar

Isso também torna os nós substituíveis

Você pode trocar o modelo, o prompt ou a ferramenta sem reconstruir o sistema inteiro, desde que o contrato permaneça o mesmo

3. Trate arestas como contratos de dados, não setas

Uma aresta não deve significar "B vem depois de A"

Deve significar "A produziu dados que B pode consumir"

Essa distinção importa porque a maior parte do encanamento de workflows não precisa de outra chamada de modelo

Achatar arrays, remover duplicatas, filtrar nulos, verificar um status e unir registros são operações determinísticas

1const usable = results
2  .filter(Boolean)
3  .flatMap(result => result.items)
4
5const unique = [...new Map(
6  usable.map(item => [item.source_url, item])
7).values()]

Nenhum agente é necessário aqui

Guarde as chamadas de modelo para julgamento

Use código para encanamento

Um grafo onde cada aresta é outro agente está pagando tokens pela própria fiação

4. Aprenda as quatro formas por trás de quase todo grafo de agentes

Você não precisa de cinquenta padrões

A maioria dos grafos de produção é uma combinação de quatro formas

A cadeia

1A -> B -> C

Use quando cada etapa realmente exige a saída anterior

É simples, previsível e frequentemente mais lento do que o necessário

O diamante

1        -> B1 -
2A ->    -> B2 --> C
3        -> B3 -

Divida um trabalho em ramos independentes, execute-os juntos e depois mescle os resultados

Essa é a forma ideal para pesquisa, revisão de código, due diligence e varreduras de mercado

O roteador

1             -> CAMINHO RÁPIDO
2CLASSIFICAR  ---
3             -> AUDITORIA COMPLETA

Inspecione o estado e escolha apenas o caminho que a tarefa precisa

Trabalho pequeno continua barato

Trabalho arriscado recebe um grafo mais profundo

O ciclo controlado

1TRABALHAR -> VERIFICAR -> PASSAR -> SAIR
2          |
3          -> FALHAR -> FEEDBACK -> TRABALHAR

Repita apenas quando a evidência indicar que o resultado está incompleto

Todo ciclo precisa de uma parada rígida, um orçamento e uma regra de convergência

5. Distribua o trabalho independente e depois una tudo deliberadamente

Paralelismo é a vantagem mais fácil de entender em um grafo e a mais fácil de abusar

Se cinco nós são independentes, execute-os juntos

1const settled = await Promise.allSettled(
2  sources.map(source => researchNode(source))
3)
4
5const findings = settled
6  .filter(result => result.status === "fulfilled")
7  .map(result => result.value)

Um ramo com falha não deve destruir os outros quatro

Mas não coloque uma barreira depois de cada estágio

Uma junção só vale a espera quando o próximo nó precisa do conjunto completo

Exemplos incluem deduplicação entre fontes, classificação de todos os candidatos, comparação de alternativas ou decidir se a cobertura está completa

Se cada item pode continuar de forma independente, mantenha o grafo em streaming

Paralelo não é automaticamente rápido. Sua topologia decide onde o sistema espera

6. Torne o roteamento inspecionável

O modelo pode fazer um julgamento

O grafo deve impor o que esse julgamento pode acionar

1const decision = await classifyRisk(change)
2
3switch (decision.severity) {
4  case "low":
5    return quickReview(change)
6
7  case "high":
8    return fullParallelAudit(change)
9
10  default:
11    return humanReview(change)
12}

O classificador é probabilístico

As rotas permitidas são determinísticas

Isso dá a flexibilidade do modelo sem dar a ele controle ilimitado sobre o sistema

O visual Agent Builder da OpenAI torna essa mudança óbvia: o comportamento do agente é cada vez mais projetado como um workflow inspecionável, em vez de uma cadeia oculta de prompts

https://x.com/OpenAIDevs/status/1975269388195631492

7. Coloque a verificação na aresta

O nó de maior alavancagem em um grafo costuma ser aquele que não produz nada de novo

O trabalho dele é impedir que trabalho fraco avance

Um verificador pode checar

• Se cada afirmação tem uma fonte
• Se a fonte citada apoia a afirmação
• Se o código passa nos testes
• Se o resultado corresponde ao esquema solicitado
• Se outro caminho independente chega à mesma conclusão

1GERADOR -> VERIFICADOR -> PASSAR -> SINTETIZADOR
2                 |
3                 -> FALHAR -> REPARAR

Não peça ao mesmo agente para gerar, aprovar e publicar o próprio trabalho em um único contexto

Separe os papéis

Separe os prompts

Separe as fronteiras de falha

O sistema de pesquisa de produção da Anthropic segue essa lógica em uma escala maior: um agente líder coordena subagentes paralelos, os resultados são sintetizados e um estágio dedicado de citação anexa as evidências antes que o resultado chegue ao usuário

https://x.com/claudeai/status/2041927687460024721

8. O estado é a parte que a maioria dos diagramas esconde

Caixas e setas parecem limpas até o sistema precisar retomar após uma falha

Um grafo de produção precisa de estado durável

1task_id
2current_node
3completed_nodes
4artifacts
5decisions
6evidence
7budgets
8retry_counts
9human_approvals

Não mova transcrições gigantes entre os nós

Mova referências para os artefatos

Um nó de pesquisa deve armazenar seu relatório e retornar um caminho, ID ou resumo estruturado

Um revisor deve ler o artefato diretamente, em vez de receber uma versão comprimida através de três agentes

Isso reduz a perda de contexto e torna cada transição auditável

O grafo deve ser capaz de responder três perguntas a qualquer momento

1O que já aconteceu
2Por que o sistema escolheu esta rota
3Onde a execução pode retomar com segurança

Se não conseguir respondê-las, o grafo ainda é uma demonstração

9. Adicione ciclos apenas quando eles convergem

Um ciclo é útil quando a quantidade de trabalho é desconhecida de antemão

Descoberta de bugs, pesquisa profunda e reparo iterativo são bons exemplos

Mas "repetir até ficar bom" não é uma condição de parada

Use convergência mensurável

1let dryRounds = 0
2let iteration = 0
3const seen = new Set()
4
5while (dryRounds < 2 && iteration < 6) {
6  const findings = await discover()
7  const fresh = findings.filter(item => !seen.has(item.key))
8
9  fresh.forEach(item => seen.add(item.key))
10  dryRounds = fresh.length === 0 ? dryRounds + 1 : 0
11  iteration += 1
12}

Observe o que o sistema lembra

Ele deduplica contra tudo o que já foi visto, não apenas contra os resultados que passaram pela verificação

Caso contrário, ideias rejeitadas continuam voltando e o grafo paga para redescobrir os mesmos becos sem saída para sempre

Todo ciclo controlado precisa de

• Um teste de conclusão
• Um número máximo de rodadas
• Um orçamento de tokens ou custo
• Um registro das tentativas anteriores
• Um caminho de escalada quando a convergência falha

10. Projete a falha como um evento local

Em uma cadeia, uma etapa quebrada pode congelar o workflow inteiro

Em um grafo, a falha deve permanecer dentro da menor fronteira possível

Cada nó precisa de uma política

1RETRY      falha transitória de ferramenta ou rede
2FALLBACK   modelo ou fonte preferida indisponível
3SKIP       ramo opcional falhou
4REPAIR     saída falhou na validação
5ESCALATE   risco ou incerteza ultrapassou um limite
6STOP       limite de orçamento, segurança ou permissão atingido

Crie checkpoints após nós caros

Torne as escritas idempotentes para que uma tentativa não duplique efeitos colaterais

Dê espaços de trabalho isolados a workers paralelos quando eles modificam arquivos

Registre cada decisão de roteamento com o estado que a produziu

Confiabilidade não vem de esperar que todo nó tenha sucesso

Vem de decidir o que o grafo faz quando um deles falha

11. Topologia é o seu modelo de custo

Um grafo não é automaticamente mais barato que um único agente

Ele pode queimar muito mais tokens se cada tarefa aciona uma frota

A forma controla tanto a latência quanto o custo

Use modelos mais baratos para extração limitada, classificação e formatação

Use modelos mais fortes para decomposição, síntese e verificação difícil

Roteie tarefas simples por um caminho curto

Reserve o grafo completo para o trabalho que justifica

1SOLICITAÇÃO SIMPLES -> MODELO PEQUENO -> VERIFICAÇÃO RÁPIDA -> CONCLUÍDO
2
3SOLICITAÇÃO COMPLEXA -> PLANEJADOR -> ESPECIALISTAS PARALELOS
4                              -> VERIFICADORES
5                              -> SINTETIZADOR FORTE
6                              -> PORTÃO HUMANO

A Anthropic relata que pesquisa multiagente pode superar materialmente um único agente em trabalho de amplitude, mas também usa muito mais tokens

Esse é o tradeoff

Engenharia de grafos não é sobre maximizar o número de agentes

É sobre gastar coordenação apenas onde paralelismo, especialização ou verificação independente criam valor suficiente

12. Um grafo de produção para pesquisa e publicação

Aqui está um grafo prático para transformar uma ideia em um artigo com citações

1                                  -> FONTES DA EMPRESA -----
2TÓPICO -> ESCOPO -> DECOMPOR       -> ARTIGOS --------------> DEDUPLICAR
3                                  -> POSTS DE ESPECIALISTAS -
4                                                             |
5                                                             v
6                PUBLICAR <- PORTÃO HUMANO <- VERIFICAÇÃO FINAL <- RASCUNHO
7                                                |          ^
8                                                -> FALHAR -> REPARAR

O sistema funciona assim

1. O nó de escopo define a pergunta, o público e os critérios de conclusão
2. O nó de decomposição cria trilhas de pesquisa independentes
3. Os nós de pesquisa rodam em paralelo com contextos separados
4. Código determinístico remove duplicatas e normaliza as fontes
5. O nó de rascunho escreve a partir de evidências estruturadas
6. O verificador valida afirmações, citações, estilo e seções ausentes
7. Verificações com falha roteiam apenas a seção relevante de volta para reparo
8. Um humano aprova o artefato final antes da publicação

Isso não é um agente gigante fingindo ser um time

É um sistema com propriedade, estado e autoridade explícitos

Quando um grafo é a resposta errada

Não transforme todo prompt em um diagrama de arquitetura

Mantenha um único agente em um único loop quando

• A tarefa é curta
• Um contexto consegue conter todas as informações relevantes
• Não há ramos independentes
• A falha é barata
• Um humano pode revisar o resultado final rapidamente

Mude para um grafo quando

• O trabalho pode rodar em paralelo
• Nós diferentes precisam de ferramentas ou permissões diferentes
• As saídas exigem verificação independente
• A tarefa precisa ser retomada após interrupção
• Vários loops precisam de estado compartilhado
• Custo e autoridade precisam ser controlados por rota

Comece com um único loop

Desenhe um grafo apenas quando as dependências forçarem você a isso

O checklist da engenharia de grafos

Antes de publicar, pergunte

1[ ] Toda aresta carrega dados ou autoridade reais
2[ ] Todo nó tem uma única função delimitada
3[ ] Entradas e saídas são estruturadas
4[ ] Nós independentes podem rodar em paralelo
5[ ] Junções são colocadas apenas onde o conjunto completo é necessário
6[ ] Resultados importantes são verificados antes de avançar
7[ ] Falhas podem ser tentadas novamente sem duplicar efeitos colaterais
8[ ] O grafo pode retomar de um checkpoint
9[ ] Todo ciclo tem uma parada rígida e um orçamento
10[ ] Um humano pode interromper caminhos de alto risco
11[ ] Você consegue explicar por que cada rota foi selecionada
12[ ] O grafo é mais simples do que o problema que resolve

Se a resposta à última pergunta for não, delete nós

A verdadeira mudança

Engenharia de prompt melhora a instrução

Engenharia de contexto controla o que o modelo vê

Engenharia de harness constrói o ambiente ao redor do modelo

Engenharia de loop faz uma unidade de trabalho melhorar através de feedback

Engenharia de grafos coordena o trabalho inteiro

1PROMPT -> CONTEXTO -> HARNESS -> LOOP -> GRAFO
2mensagem    memória      máquina    execução   coordenação

O modelo é apenas um nó

O produto é o sistema ao redor dele

Um promotor pede que o agente faça mais. Um arquiteto redesenha o grafo para que o sistema possa fazer mais com segurança

Continue lendo

• As Três Camadas por Trás de Agentes de IA Confiáveis: Engenharia de Harness vs Loop vs Grafo
• Como configurei Obsidian + Claude como meu segundo cérebro
• Como configurei o Claude para realmente fazer o trabalho
• Como configurei projetos do Claude para que realmente funcionem
• 30 system prompts do Claude que eu realmente uso
• Engenharia de Loop: a habilidade de IA que todo builder precisa em 2026
• 30 configurações, atalhos e workflows do Claude Code que a maioria dos usuários não conhece
• Como uso o Claude Cowork para operar como uma empresa de uma pessoa só

Para notas mais curtas, novas ferramentas e sistemas de IA que estou testando

Entre no meu Telegram

Para análises mais aprofundadas entregues diretamente

Assine meu Substack

Se você leu até aqui

Salve o artigo nos favoritos para poder usar os padrões depois

Siga o @0xwhrrari para mais sistemas de IA práticos

E envie isto para um builder que ainda está forçando todo agente através de uma longa cadeia