Graph Engineering com Claude 🕸️

Graph engineering é a quarta era da engenharia de IA: depois de prompt engineering, context engineering e loop engineering, vem o desenho explícito de vários agentes com rotas, falhas, verificações e pontos de entrada humana. A mudança principal não é um modelo maior; é uma arquitetura que representa o trabalho.

“Um loop é um agente ficando mais inteligente. Um grafo são muitos agentes ficando coordenados.”

Por que um loop não basta

Um loop funciona para uma tarefa de propósito único, como corrigir um bug ou resumir um documento. Ele quebra quando precisa pesquisar, analisar, codificar e revisar ao mesmo tempo: um agente mistura contextos, perde o fio e produz algo que parece completo, mas não resiste à inspeção.

A correção não é uma janela de contexto maior. É dividir o trabalho entre agentes que fazem uma coisa bem, encadeando a saída de um como entrada do próximo.

Os quatro blocos

• Node: função que faz uma coisa, recebe state e devolve state.
• Edge: conexão entre nodes, incondicional ou condicional.
• Router: node que inspeciona o state e escolhe o caminho; despacha, não executa.
• State: dicionário que flui pelo grafo e registra o que cada node aprendeu.

def router(state, condition, if_true, if_false):
    if condition(state):
        return if_true(state)
    return if_false(state)

Cinco padrões de grafo

1. Sequential chain

A → B → C, sem ramificação. É adequada quando a ordem nunca muda, mas propaga o erro de A para B e C. Mesmo cadeias simples se beneficiam de um node de verificação no final.

2. Router

Inspeciona a entrada e escolhe entre especialistas. Roteamento é classificação, não raciocínio; um modelo barato costuma bastar. Cada especialista deve ter seu próprio prompt e conjunto de ferramentas, evitando chamadas erradas e contexto desperdiçado.

3. Parallel fan-out

Vários nodes trabalham sobre a mesma entrada e um collector espera todos. O tempo total é o do agente mais lento, não a soma, mas isso só funciona quando há independência. O merge exige seu próprio prompt e barra de qualidade; não é apenas concatenar strings.

4. Loop com gate

Um builder produz, um reviewer separado revisa e o builder tenta novamente com o feedback. Builder e reviewer precisam ser agentes diferentes, com prompts diferentes e, às vezes, tiers diferentes. O reviewer deve ser adversarial: procurar falhas, inconsistências e edge cases, em vez de perguntar apenas se “está bom”.

5. Human-in-the-loop

O grafo pausa antes de qualquer coisa cara, irreversível ou de alto risco. A aprovação precisa mostrar o que vai acontecer e quanto custará; “aprova?” é menos útil do que descrever a ação concreta em cinco segundos.

State e tiering

Todo node deve declarar quais chaves lê e escreve. Sem isso, o grafo fica difícil de depurar. O modelo também deve combinar com o papel:

Fallback paths

O caminho feliz não pode ser o único. Se uma pesquisa der timeout, devolva resultado parcial e sinalize; se o reviewer quebrar, mande para revisão humana; se o grafo falhar após o limite de tentativas, salve o state e alerte. Fallback não é ignorar o erro, mas oferecer um caminho separado que trate a falha com elegância.

def safe_node(func, state):
    try:
        return func(state)
    except Exception as error:
        state["error"] = str(error)
        state["needs_human"] = True
        return state

O primeiro grafo

Um pipeline de suporte combina os padrões: classifica o ticket, roteia para o especialista, rascunha a resposta, revisa, tenta novamente se necessário e envia apenas após aprovação. Depois de um número máximo de tentativas, cai para uma pessoa.

A mesma arquitetura serve para análise competitiva, revisão de PR, posts, ETL com validação e resposta a incidentes. Os erros mais comuns são um node monolítico, ausência de state, nenhum fallback, modelo caro no roteamento e o pulo do gate.

Adaptado de 0xRafy, “Graph Engineering with Claude: The 11-Step Roadmap”, thread no X, 2026-07-21. Thread original.