Phase 14 - Lesson 13

LangGraph: Grafos com Estado e Execução Durável

O LangGraph é a referência de 2026 para orquestração com estado de baixo nível. O agente é uma máquina de estados; os nós são funções; as arestas são transições; o estado é imutável e salvo em um checkpoint após cada etapa. Retome a partir de qualquer falha exatamente de onde ela parou.

Tipo: Aprender + Construir Idiomas: Python (stdlib) Pré-requisitos: Phase 14 · 01 (Agent Loop), Phase 14 · 12 (Workflow Patterns) Tempo: ~75 minutos

Objetivos de Aprendizagem

• Descrever o modelo central do LangGraph: máquina de estados com estado imutável, nós de função, arestas condicionais e checkpoints pós-etapa.
• Nomear os quatro recursos destacados pela documentação: execução durável, streaming, human-in-the-loop (humano no circuito) e memória abrangente.
• Explicar as três topologias de orquestração suportadas pelo LangGraph: supervisor, peer-to-peer (swarm) e hierárquica (subgrafos aninhados).
• Implementar um grafo de estado da stdlib com estado imutável, arestas condicionais e um ciclo de checkpoint/resume.

O Problema

Agentes e fluxos de trabalho compartilham um problema: quando uma execução de 40 etapas falha na etapa 38, você deseja retomar a partir da etapa 38, não começar do zero. Modelos de estado de segunda classe forçam os operadores a criarem gambiarras de tentativas em torno de uma biblioteca que pressupõe execuções limpas.

A resposta de design do LangGraph: o estado é um objeto tipado de primeira classe, as mutações são explícitas e os checkpoints persistem após cada nó. A retomada é uma chamada a load_state(session_id).

O Conceito

O grafo

Um grafo é definido por:

• State type (Tipo de estado). Um dicionário tipado (ou modelo Pydantic) que cada nó lê e muda.
• Nodes (Nós). Funções puras (state) -> state_update. As atualizações são mescladas no estado após o retorno.
• Edges (Arestas). Transições condicionais ou diretas entre nós.
• Entry and exit (Entrada e saída). Nós sentinela START e END marcam o limite.

Exemplo: um agente com nós classify, refund, bug, sales, done — um fluxo de trabalho de roteamento como um grafo.

Execução durável

Após o retorno de cada nó, o runtime serializa o estado e o grava em um checkpointer (SQLite, Postgres, Redis, personalizado). Em caso de falha na etapa N, o runtime pode fazer resume(session_id) e continuar a partir da etapa N+1 com o estado exato.

A documentação do LangGraph destaca explicitamente usuários em produção onde isso importa: Klarna, Uber, J.P. Morgan. A alegação principal não é o formato do grafo; é que o formato do grafo mais o checkpointing tornam a recuperação barata.

Streaming

Cada nó pode produzir saídas parciais. O grafo transmite eventos de delta por nó para o chamador, de modo que as interfaces de usuário (UIs) sejam atualizadas conforme o grafo é executado.

Human-in-the-loop (Humano no circuito)

Inspecione e modifique o estado entre os nós. Implementações: pausar antes de um nó crítico, apresentar o estado a um humano, aceitar modificações, retomar. O checkpointer facilita isso porque o estado já está serializado.

Memória

Curto prazo (dentro de uma execução — histórico de conversas no estado) e longo prazo (entre execuções — persistente via checkpointer mais um armazenamento de longo prazo separado). O LangGraph se integra com sistemas de memória externa (Mem0, personalizado) por meio de ferramentas.

Três topologias

1. Supervisor. O LLM roteador central delega tarefas para subagentes especialistas. create_supervisor() em langgraph-supervisor (embora a equipe do LangChain em 2026 recomenda fazer isso diretamente por meio de chamadas de ferramenta para maior controle de contexto).
2. Swarm / peer-to-peer. Os agentes passam o bastão diretamente por meio de uma superfície de ferramentas compartilhada. Sem roteador central.
3. Hierárquica. Supervisores que gerenciam sub-supervisores, implementados como subgrafos aninhados.

Onde esse padrão falha

• Checkpoints pequenos demais. Salvar checkpoints apenas nos turnos de conversa deixa o estado das ferramentas e as gravações de memória irrecuperáveis. Todo o estado deve ser serializado.
• Nós não determinísticos. A retomada assume que as entradas dos nós produzem a mesma atualização de estado. Sementes aleatórias, relógio de parede e APIs externas devem ser capturados.
• Uso excessivo de arestas condicionais. Um grafo onde todas as arestas são condicionais é uma máquina de estados sobre a qual é impossível raciocinar. Prefira cadeias lineares com ramificações ocasionais.

Construa

code/main.py implementa um grafo com estado na stdlib:

• State — um dicionário tipado com messages, step, route, output, human_approval.
• Node — um chamável (callable) que recebe o estado e retorna um dicionário de atualização.
• StateGraph — nós + arestas + arestas condicionais + run (execução) + resume (retomada).
• SQLiteCheckpointer (simulado em memória) — serializa o estado após cada nó; load(session_id) restaura.
• Um grafo de demonstração: classify -> branch(refund / bug / sales) -> human gate -> send.

Execute-o:

python3 code/main.py

O rastreamento (trace) mostra a primeira execução falhando no portão humano, a persistência e, em seguida, a retomada produzindo a saída final.

Use

• LangGraph — a referência pronta para produção. Use create_react_agent, create_supervisor ou construa seu próprio grafo.
• AutoGen v0.4 (Lesson 14) — alternativa de modelo de ator para cenários de alta concorrência.
• Claude Agent SDK (Lesson 17) — harness gerenciado com armazenamento de sessão integrado.
• Personalizado — quando você precisa de controle exato sobre o formato do estado ou o backend do checkpointer.

Envie para Produção

outputs/skill-state-graph.md gera um grafo de estado no formato do LangGraph em qualquer runtime de destino com checkpointing e retomada integrados.

Exercícios

1. Adicione uma aresta condicional de classify para end quando a confiança da classificação estiver abaixo de um limite. Retome a execução após um humano definir route manualmente.
2. Substitua o simulado baseado em SQLite por um checkpointer SQLite real. Meça a sobrecarga de serialização por etapa.
3. Implemente arestas paralelas: dois nós são executados simultaneamente, mesclados por um reducer personalizado. O que o estado imutável nos proporciona aqui?
4. Leia a referência do langgraph-supervisor. Portabilidade do brinquedo (toy) para create_supervisor. Compare os formatos dos traces.
5. Adicione streaming: cada nó produz um estado parcial enquanto é executado. Imprima os deltas conforme eles chegam.

Termos Chave

Leituras Adicionais

• LangGraph overview — documentação de referência
• langgraph-supervisor reference — API do padrão supervisor
• AutoGen v0.4, Microsoft Research — alternativa de modelo de ator
• Claude Agent SDK overview — armazenamento de sessão e subagentes