LangGraph na prática: como estruturar grafos cíclicos e checkpoints para agentes

Se você já construiu um agente que repete a mesma chamada sem progresso ou que perde o contexto ao encontrar um erro, o LangGraph ataca esse problema. Ele trata o agente como uma máquina de estados, com checkpoints que permitem pausar, inspecionar e retomar.

O repositório langchain-ai/langgraph tem mais de 44 mil estrelas, licença MIT e recebeu atualização em 8 de novembro de 2026. Faz parte do ecossistema LangChain, mas pode ser usado de forma independente.

O que é o LangGraph e como funciona o grafo de estado

Um agente baseado em cadeia linear executa passos em ordem fixa. Se um passo falha, a cadeia quebra. Se o agente precisa voltar e tentar de novo, você precisa reimplementar a lógica de retry manualmente.

O LangGraph modela o agente como um grafo. Cada nó é uma função que recebe o estado atual e retorna uma atualização. As arestas definem a ordem de execução, incluindo condições. Um nó pode levar de volta a um nó anterior, criando um ciclo controlado.

O estado é um objeto compartilhado, geralmente um TypedDict ou uma classe Pydantic. Cada nó lê e escreve campos desse estado. Isso torna o fluxo explícito e inspecionável.

Essa abordagem é útil para agentes que precisam planejar, executar, verificar e replanejar. O ciclo planejar-executar-verificar é natural em um grafo, mas incômodo em uma cadeia linear.

Como instalar o LangGraph e criar um grafo simples

A instalação é direta. O pacote principal é langgraph.

$ pip install langgraph

Depois, defina o estado e os nós.

from typing import TypedDict
from langgraph.graph import StateGraph, END

class Estado(TypedDict):
    entrada: str
    saida: str

def processar(estado: Estado) -> Estado:
    return {"saida": estado["entrada"].upper()}

grafo = StateGraph(Estado)
grafo.add_node("processar", processar)
grafo.set_entry_point("processar")
grafo.add_edge("processar", END)

app = grafo.compile()
resultado = app.invoke({"entrada": "olá"})
print(resultado)

O método compile gera um aplicativo executável. O método invoke roda o grafo com o estado inicial. Você pode usar stream para acompanhar cada passo, o que ajuda na depuração.

Se você já usa LangChain, pode reutilizar modelos e ferramentas. O LangGraph não obriga o uso do LangChain, mas a integração é natural.

Como usar checkpoints para recuperar estado

Checkpoints são o diferencial do LangGraph. A cada passo, o framework pode salvar o estado em um armazenamento, como SQLite ou PostgreSQL. Se o processo cair, você retoma do último checkpoint em vez de recomeçar.

Isso é essencial para agentes de longa duração, como os que processam documentos grandes ou executam tarefas em segundo plano. Também facilita auditoria, porque você pode inspecionar o estado em qualquer ponto.

Para ativar checkpoints, passe um checkpointer ao compilar o grafo.

from langgraph.checkpoint.sqlite import SqliteSaver

memoria = SqliteSaver.from_conn_string("checkpoints.db")
app = grafo.compile(checkpointer=memoria)
config = {"configurable": {"thread_id": "1"}}
resultado = app.invoke({"entrada": "olá"}, config=config)

O thread_id identifica a execução. Com ele, você pode retomar depois ou inspecionar o histórico de estados.

Quando usar LangGraph e quando uma cadeia linear basta

Nem todo agente precisa de grafo. Se a tarefa é uma sequência fixa de chamadas, como resumir um texto e depois traduzir, uma cadeia linear é mais simples e mais rápida de implementar.

Use o LangGraph quando o agente precisa iterar, decidir caminhos diferentes ou recuperar de falhas. Casos típicos incluem agentes de pesquisa que refinam a busca, agentes de código que testam e corrigem, e fluxos com aprovação humana no meio.

Se você precisa de memória persistente entre execuções, combine o LangGraph com uma camada de memória. Veja Mem0: como dar memória persistente a agentes de IA. Se a tarefa envolve navegador, veja browser-use: como conectar agentes de IA ao navegador.

Limites e boas práticas

Grafos adicionam complexidade. Um grafo mal desenhado pode entrar em loop infinito ou gerar estados inconsistentes. Defina limites de iteração e valide o estado em cada nó.

Outro ponto é a depuração. Grafos são mais difíceis de depurar que cadeias lineares. Use stream e logging para acompanhar cada transição. A documentação oficial traz ferramentas de visualização que ajudam.

Boas práticas que valem para qualquer agente baseado em grafo:

• Mantenha o estado pequeno e focado
• Valide entradas e saídas em cada nó
• Defina um limite máximo de iterações
• Use checkpoints em produção, não apenas em desenvolvimento
• Teste cada nó isoladamente antes de compor o grafo

Se você coordena vários agentes, cada um pode ser um subgrafo com seu próprio estado. No bridgecode você monta esse squad e acompanha cada etapa, do planejamento à entrega.

Perguntas frequentes sobre o LangGraph

O LangGraph é gratuito?

Sim. É open source com licença MIT. O custo vem do provedor de modelo e da infraestrutura de checkpoint.

Preciso usar LangChain para usar o LangGraph?

Não. O LangGraph pode ser usado de forma independente. A integração com LangChain é opcional e facilita o reuso de modelos e ferramentas.

LangGraph substitui o LangChain?

Não. Eles se complementam. O LangChain oferece componentes e integrações. O LangGraph oferece a orquestração baseada em grafo. Você pode usar os dois juntos.

Como evitar loops infinitos em um grafo?

Defina um limite de iterações no estado e verifique-o em cada nó. O LangGraph também permite configurar limites de recursão ao invocar o grafo.

Funciona com modelos locais?

Sim, desde que você use um modelo compatível. Ollama e vLLM funcionam quando integrados via LangChain ou diretamente.