LangGraph: Guia Definitivo para Agentes Stateful em 2026

TL;DR — LangGraph é o framework de orquestração de agentes IA que trata seu agente como uma state machine, não como um chatbot. Com 36K stars, 34.5M downloads mensais e adoção por Klarna, Replit, LinkedIn e Uber, virou o padrão de produção para workflows stateful em 2026. Se você precisa de loops, branches, checkpointing, human-in-the-loop e controle determinístico sobre o fluxo do seu agente — LangGraph é a resposta. Este guia cobre da instalação ao deploy, com opinião inclusa.

Overview: O que é LangGraph e por que você deveria prestar atenção

Vamos direto ao ponto. A maioria dos frameworks de agentes IA nasceu com uma premissa implícita: o agente é basicamente um chatbot com ferramentas. Você manda um prompt, ele responde, talvez chame uma tool, devolve o resultado. Linear. Bonito. Simples.

Só que a realidade de produção não é simples.

Em produção você precisa que o agente faça loop quando a primeira tentativa falha. Que pare no meio do caminho esperando aprovação humana. Que sobreviva a um crash do servidor e retome exatamente de onde parou. Que coordene sub-agentes. Que tenha memória persistente entre sessões. Que rode em paralelo quando possível mas serial quando necessário.

É aqui que entra o LangGraph.

A genealogia

LangGraph nasceu dentro do ecossistema LangChain — mas não é LangChain. LangChain é ótimo para chains lineares (prompt → LLM → output). Quando você precisa de ciclos — e agentes sérios sempre precisam de ciclos — LangChain sozinho não dá conta. LangGraph surgiu para resolver exatamente isso: dar ao desenvolvedor um primitivo de grafo dirigido com ciclos onde cada nó é uma unidade de computação e o estado flui pelas arestas.

Lançado como GA 1.0 em outubro de 2025, atingiu a versão 1.1 em março de 2026 e já passou de 34.5 milhões de downloads mensais no PyPI. Não é hype de whitepaper — é código em produção em empresas que processam milhões de requests por dia.

O insight fundamental

Uma frase do Intellipaat captura perfeitamente: “serious AI agent systems behave less like chatbots and more like state machines.” E é exatamente isso que LangGraph implementa. Seu agente é um grafo de estados. Cada nó lê o estado, transforma, e passa adiante. Você tem controle total sobre as transições. Nada acontece “magicamente” — cada decisão é explícita no código.

Isso contrasta com frameworks como CrewAI (que abstrai demais e te dá pouco controle) ou o finado AutoGen (que virou Microsoft Agent Framework em abril 2026 e tá basicamente em maintenance mode).

Para entender melhor as diferenças entre frameworks e coding agents, vale a leitura do nosso comparativo de frameworks vs coding agents.

Tutorial: Do Zero ao Primeiro Agente

Chega de teoria. Vamos botar a mão no código.

Instalação

pip install langgraph langchain langchain-anthropic

Se você prefere OpenAI:

pip install langgraph langchain langchain-openai

Configure sua API key:

export ANTHROPIC_API_KEY="sua-chave-aqui"
# ou
export OPENAI_API_KEY="sua-chave-aqui"

Conceito-chave: O grafo

Em LangGraph, seu agente é um StateGraph. Ele tem:

• Nós (nodes): funções Python que recebem o estado e retornam atualizações
• Arestas (edges): conexões entre nós, podendo ser condicionais
• Estado (state): um TypedDict que acumula dados conforme o grafo executa

Parece simples? É. E esse é o poder.

Seu primeiro agente: passo a passo

Passo 1 — Defina as ferramentas e o modelo:

from langchain.tools import tool
from langchain.chat_models import init_chat_model

model = init_chat_model("claude-sonnet-4-6", temperature=0)

@tool
def buscar_clima(cidade: str) -> str:
    """Busca o clima atual de uma cidade."""
    # Em produção, chamaria uma API real
    return f"O clima em {cidade} está 22°C, parcialmente nublado."

@tool
def buscar_noticias(tema: str) -> str:
    """Busca notícias recentes sobre um tema."""
    return f"Últimas notícias sobre {tema}: [3 resultados encontrados]"

tools = [buscar_clima, buscar_noticias]
tools_by_name = {tool.name: tool for tool in tools}
model_with_tools = model.bind_tools(tools)

Passo 2 — Defina o estado:

from langchain.messages import AnyMessage
from typing_extensions import TypedDict, Annotated
import operator

class AgentState(TypedDict):
    messages: Annotated[list[AnyMessage], operator.add]
    tool_calls_count: int

O operator.add no annotation diz ao LangGraph para acumular mensagens em vez de substituir. Detalhe sutil mas crucial.

Passo 3 — Defina o nó do modelo (a “mente” do agente):

from langchain.messages import SystemMessage

def chamar_modelo(state: AgentState):
    """O LLM decide se chama uma tool ou responde ao usuário."""
    resposta = model_with_tools.invoke(
        [
            SystemMessage(
                content="Você é um assistente útil que pode buscar clima e notícias."
            )
        ]
        + state["messages"]
    )
    return {
        "messages": [resposta],
        "tool_calls_count": state.get("tool_calls_count", 0) + 1,
    }

Passo 4 — Defina o nó de ferramentas:

from langchain.messages import ToolMessage

def executar_tools(state: AgentState):
    """Executa as tools chamadas pelo LLM."""
    resultados = []
    for tool_call in state["messages"][-1].tool_calls:
        tool = tools_by_name[tool_call["name"]]
        resultado = tool.invoke(tool_call["args"])
        resultados.append(
            ToolMessage(content=resultado, tool_call_id=tool_call["id"])
        )
    return {"messages": resultados}

Passo 5 — Defina o roteamento condicional:

from typing import Literal
from langgraph.graph import END

def decidir_proximo_passo(state: AgentState) -> Literal["executar_tools", "__end__"]:
    """Se o LLM pediu tool calls, executa. Senão, encerra."""
    ultima_msg = state["messages"][-1]
    if ultima_msg.tool_calls:
        return "executar_tools"
    return END

Passo 6 — Monte e compile o grafo:

from langgraph.graph import StateGraph, START, END

# Construir o grafo
builder = StateGraph(AgentState)

# Adicionar nós
builder.add_node("chamar_modelo", chamar_modelo)
builder.add_node("executar_tools", executar_tools)

# Adicionar arestas
builder.add_edge(START, "chamar_modelo")
builder.add_conditional_edges("chamar_modelo", decidir_proximo_passo)
builder.add_edge("executar_tools", "chamar_modelo")

# Compilar
agente = builder.compile()

Passo 7 — Execute:

from langchain.messages import HumanMessage

resultado = agente.invoke({
    "messages": [HumanMessage(content="Como está o clima em São Paulo?")],
    "tool_calls_count": 0,
})

for msg in resultado["messages"]:
    msg.pretty_print()

Pronto. Você tem um agente que raciocina, decide chamar ferramentas, executa, e retorna o resultado — tudo dentro de um grafo explícito onde você controla cada transição.

Perceba o loop: chamar_modelo → executar_tools → chamar_modelo. O agente pode iterar quantas vezes precisar. Pode até chamar múltiplas tools em sequência antes de responder. Esse é o poder dos ciclos.

Deep Dive: O que faz LangGraph ser LangGraph

Grafos de Estado

O StateGraph é o coração. Diferente de um DAG (grafo acíclico dirigido), LangGraph permite ciclos. Isso é fundamental. Um agente real precisa iterar: tentar, falhar, retentar, buscar mais informação, recalcular.

Cada nó é uma função pura que:

1. Recebe o estado atual
2. Faz alguma computação (chamar LLM, executar tool, transformar dados)
3. Retorna atualizações parciais ao estado

O framework cuida da redução — aplicando as atualizações conforme os reducers definidos nos annotations (como operator.add para listas).

Você pode ter subgrafos dentro de grafos. Pode ter execução paralela de nós quando não há dependência. Pode ter roteamento condicional arbitrariamente complexo. E tudo fica legível no código — não escondido em abstrações mágicas.

Checkpointing: Sobrevivendo a falhas

Aqui mora uma das features matadoras. Um checkpointer salva um snapshot do estado do grafo a cada super-step. Na prática, isso significa:

• Fault tolerance: servidor caiu? O agente retoma de onde parou.
• Time travel: quer debugar o que aconteceu 5 passos atrás? Volta no tempo.
• Conversational memory: o agente lembra do contexto entre sessões.
• Human-in-the-loop: pausa a execução e espera input humano.

from langgraph.checkpoint.memory import MemorySaver

# Compilar com checkpointer
checkpointer = MemorySaver()
agente = builder.compile(checkpointer=checkpointer)

# Executar com thread_id para persistência
config = {"configurable": {"thread_id": "sessao-123"}}
resultado = agente.invoke(
    {"messages": [HumanMessage(content="Qual o clima?")]},
    config=config,
)

Para produção, troque MemorySaver por PostgresSaver ou SqliteSaver. O estado sobrevive a restarts do processo.

Human-in-the-Loop: O agente que sabe esperar

Já vi muita gente confundir “agente autônomo” com “agente que faz tudo sozinho sem supervisão”. Na vida real — especialmente em ambiente regulado — você quer que o agente pare antes de executar ações críticas e peça aprovação.

LangGraph resolve isso com a função interrupt():

from langgraph.types import interrupt

def executar_acao_critica(state: AgentState):
    """Pausa para aprovação humana antes de executar."""
    acao = state["messages"][-1].content
    
    # Interrompe e aguarda aprovação
    aprovacao = interrupt(
        {"acao_proposta": acao, "mensagem": "Aprovar esta ação?"}
    )
    
    if aprovacao == "sim":
        # Executar a ação
        return {"messages": [AIMessage(content="Ação executada com sucesso.")]}
    else:
        return {"messages": [AIMessage(content="Ação cancelada pelo operador.")]}

Quando o interrupt() é chamado, LangGraph salva o estado via checkpointer e para. Espera indefinidamente. Quando o humano aprova (via API, UI, webhook, tanto faz), você retoma com Command:

from langgraph.types import Command

# Retomar a execução após aprovação
resultado = agente.invoke(
    Command(resume="sim"),
    config=config,
)

Isso é game-changer para agentes em produção. Fintech, healthcare, legal — qualquer domínio onde “ops, o agente fez besteira” tem consequências reais.

Para entender a arquitetura de harness e loop que sustenta isso, recomendo nosso artigo sobre harness e loop na arquitetura de agentes.

LangSmith: Observabilidade de primeira classe

Não adianta ter um agente sofisticado se você não consegue debugar quando algo dá errado. E coisas vão dar errado.

LangSmith é a plataforma de observabilidade do ecossistema LangChain. Para LangGraph, ela oferece:

• Tracing estruturado: cada execução vira uma timeline de steps. Você vê exatamente qual nó executou, com qual input, qual output, quanto tempo levou.
• LangGraph Studio: interface visual para inspecionar e debugar grafos rodando localmente.
• LangSmith Engine: monitora traces em produção, detecta anomalias, sugere fixes.
• Evaluations: framework de testes para validar comportamento do agente antes do deploy.

A integração é trivial — basta setar a env var:

export LANGCHAIN_TRACING_V2="true"
export LANGCHAIN_API_KEY="sua-chave-langsmith"

E todo invoke do seu agente aparece automaticamente no dashboard. Sem instrumentação manual.

Comparando com alternativas: Laminar é melhor para debugging real-time e SQL nativo. Langfuse é melhor para self-hosting com schema explícito. Mas se você já está no ecossistema LangGraph, LangSmith é a escolha natural — integração mais profunda, Studio embutido, zero configuração extra.

Multi-agente e subgrafos

Precisa que múltiplos agentes colaborem? LangGraph suporta subgrafos nativamente. Cada sub-agente é um grafo compilado que vira um nó dentro do grafo principal. O estado flui entre eles de forma controlada.

# Agente pesquisador (subgrafo)
pesquisador = StateGraph(PesquisadorState)
pesquisador.add_node("buscar", buscar_informacao)
pesquisador.add_node("resumir", resumir_resultados)
# ... compile

# Agente escritor (subgrafo)
escritor = StateGraph(EscritorState)
escritor.add_node("redigir", redigir_texto)
escritor.add_node("revisar", revisar_texto)
# ... compile

# Orquestrador
orquestrador = StateGraph(OrchestradorState)
orquestrador.add_node("pesquisar", pesquisador.compile())
orquestrador.add_node("escrever", escritor.compile())
orquestrador.add_edge("pesquisar", "escrever")

Diferente de CrewAI onde você define “roles” e o framework decide como orquestrar, aqui você define a topologia. Mais trabalho? Sim. Mais controle? Absurdamente mais.

Temos um guia específico sobre multi-agentes trabalhando em paralelo que complementa muito bem essa seção.

Spider Chart: Avaliação em 8 Eixos

Prós e Contras

Prós

• Controle determinístico total — você define cada transição, cada condição, cada rota. Zero magia escondida.
• Checkpointing nativo — fault tolerance, time travel, human-in-the-loop sem gambiarras.
• Observabilidade madura — LangSmith é provavelmente a melhor ferramenta de tracing para agentes que existe hoje.
• Duas APIs — Graph API para quem pensa visualmente em grafos; Functional API para quem prefere loops e condicionais normais.
• Produção comprovada — Klarna, Replit, LinkedIn, Uber, Elastic. Não é brinquedo de hackathon.
• Ecossistema gigante — 100+ integrações via LangChain, MCP support, deployment cloud ou self-hosted.
• Subgrafos e composição — complexidade escala sem virar espaguete.

Contras

• Curva de aprendizado — pensar em grafos de estado não é natural pra todo mundo. Primeiros dias são frustrantes.
• Verbosidade — um agente simples demanda mais código que em CrewAI ou frameworks mais abstratos. O boilerplate é o preço do controle.
• Overhead para tarefas simples — se tudo que você precisa é “LLM + uma tool”, LangGraph é canhão pra matar formiga.
• Acoplamento ao ecossistema LangChain — embora funcione standalone, a integração mais suave é com LangChain. Se você odeia LangChain, vai sentir atrito.
• 601 issues abertas — em um projeto com 36K stars é normal, mas indica que nem tudo é perfeito. Edge cases existem.
• Vendor lock-in suave — LangSmith + LangGraph Platform criam dependência. Migrar depois é possível mas doloroso.

Quando Usar LangGraph

✅ Seu agente precisa de loops e retentativas — buscar, validar, buscar de novo.

✅ Você opera em ambiente regulado (fintech, healthcare, legal) onde human-in-the-loop é obrigatório.

✅ Precisa de fault tolerance — agentes que sobrevivem a crashes e retomam do checkpoint.

✅ Workflows multi-step complexos com branches condicionais, paralelismo, e sub-agentes.

✅ Você quer observabilidade séria — traces estruturados, replay, debugging de cada decisão.

✅ O agente vai rodar em produção real com SLA, não é um side project de fim de semana.

✅ Precisa de memória entre sessões — o agente lembra quem é o usuário e o que já aconteceu.

Quando NÃO Usar LangGraph

❌ Agente simples de uma tool — se é só “pergunta → busca → resposta”, use create_react_agent direto ou até um prompt com function calling nativo da API do modelo.

❌ Prototipagem rápida para hackathon — CrewAI vai te dar resultado em 20 linhas. LangGraph vai te dar resultado em 60.

❌ Você não quer aprender conceitos de grafo — se StateGraph, edges, conditional routing te causam alergia, considere a Functional API ou outro framework.

❌ Time pequeno sem experiência em infra — o deploy e observabilidade completos (LangSmith, PostgresSaver, LangGraph Platform) demandam maturidade operacional.

❌ Script descartável que roda uma vez — não precisa de checkpointing pra um batch que roda no cron. Overhead desnecessário.

Para entender melhor como ferramentas e MCP servers se encaixam nesse contexto, leia nosso guia sobre ferramentas, tools e MCP servers.

Comparativo rápido com alternativas

A regra de ouro em meados de 2026: LangGraph para produção, CrewAI para prototipagem rápida. AutoGen? Já era — quem está nele está migrando.

Próximos Passos

Se você chegou até aqui, o caminho natural é:

1. Monte o tutorial acima e execute localmente. Brinque com as tools, adicione mais nós, crie branches condicionais.

2. Adicione checkpointing com PostgresSaver — transforme o agente stateless em um que sobrevive a restarts:

   pip install langgraph-checkpoint-postgres

3. Implemente human-in-the-loop em um ponto crítico. Sinta como é ter controle de aprovação no meio de um workflow autônomo.

4. Conecte LangSmith e execute 10 conversas diferentes. Observe os traces. Identifique onde o agente demora, onde erra, onde poderia ser otimizado.

5. Explore subgrafos — crie dois agentes especializados e orquestre-os. Pesquisador + Escritor é um clássico pra começar.

6. Leia os patterns de produção — o blog da LangChain tem excelentes posts sobre architectures que escalam (supervisor pattern, plan-and-execute, reflection).

Recursos essenciais

• Documentação oficial LangGraph
• LangGraph Academy — curso gratuito
• LangSmith — observabilidade
• LangGraph Platform — deploy gerenciado

Opinião pessoal: onde LangGraph se encaixa no mapa

Tenho acompanhado o ecossistema de agentes de código desde o começo. E o que me fascina no LangGraph não é a tecnologia em si — grafos de estado existem há décadas em teoria de computação. O que me fascina é que alguém finalmente aplicou esse conceito corretamente ao problema de orquestração de LLMs.

A maioria dos frameworks de agentes tenta esconder a complexidade. “Defina roles, deixe os agentes conversarem, tudo vai dar certo.” Na prática? Quando dá errado — e sempre dá — você não tem onde olhar. Não tem trace. Não tem checkpoint. Não tem como reproduzir o bug.

LangGraph faz a escolha oposta: complexidade explícita. Mais trabalho pra montar. Mas quando seu agente de produção começa a ter comportamentos inesperados às 3 da manhã, você consegue abrir o LangSmith, encontrar o trace exato, ver qual nó tomou a decisão errada, entender o estado que levou a essa decisão, e corrigir. Isso vale ouro.

Se você está construindo agentes para produção — especialmente em ambientes onde erros custam dinheiro ou afetam pessoas reais — LangGraph é a escolha sóbria. Não é a mais sexy. Não é a que dá mais likes no Twitter. Mas é a que vai te deixar dormir tranquilo.

Precisa de ajuda implementando agentes stateful com LangGraph no seu produto ou empresa? Consultorias de arquitetura e implementação de agentes em ft.ia.br.