LangGraph: Guia Completo para Construir Agentes com Python em 2026

O que é LangGraph e por que importa

LangGraph é o runtime de orquestração de agentes do ecossistema LangChain. Enquanto o LangChain fornece as abstrações para modelos, ferramentas e cadeias de raciocínio, o LangGraph resolve um problema diferente e mais difícil: como você controla o fluxo de execução de um agente ao longo do tempo?

A resposta do LangGraph é elegante: modele seu agente como um grafo dirigido com estado compartilhado. Cada nó do grafo é uma função Python. Cada aresta é uma transição de estado. O estado persiste entre os nós e pode ser inspecionado, modificado ou interrompido em qualquer ponto.

Referência oficial: docs.langchain.com/langgraph

Por que não usar apenas LangChain Agents?

Os agentes “clássicos” do LangChain funcionam bem para tarefas simples: chame uma ferramenta, processe o resultado, decida se terminou. Mas eles têm limitações estruturais:

• Sem persistência nativa: cada execução começa do zero
• Sem controle de fluxo granular: você não controla os ciclos
• Difícil de debugar: o estado interno não é visível
• Sem human-in-the-loop estruturado: interrupções são gambiarras

LangGraph foi criado para resolver exatamente isso. Em produção, a diferença é enorme.

---

Instalação e configuração

pip install -U langgraph langchain-openai

Para rastreamento em produção (altamente recomendado):

pip install langsmith
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=sua_chave_aqui
export OPENAI_API_KEY=sua_chave_openai

---

Conceitos fundamentais

StateGraph — o coração do LangGraph

O StateGraph define o estado compartilhado que todos os nós leem e escrevem. Pense nele como a memória de trabalho do agente.

from langgraph.graph import StateGraph, MessagesState, START, END
from langchain_openai import ChatOpenAI

# MessagesState é um estado pré-definido com lista de mensagens
# Você pode criar estados customizados com TypedDict

llm = ChatOpenAI(model="gpt-4o")

def agent_node(state: MessagesState):
    """Nó principal: chama o LLM com o histórico de mensagens."""
    response = llm.invoke(state["messages"])
    return {"messages": [response]}

# Montando o grafo
graph = StateGraph(MessagesState)
graph.add_node("agent", agent_node)
graph.add_edge(START, "agent")
graph.add_edge("agent", END)

# Compilando — isso valida a estrutura
app = graph.compile()

# Invocando
result = app.invoke({
    "messages": [{"role": "user", "content": "Qual é a capital do Brasil?"}]
})

print(result["messages"][-1].content)
# → "A capital do Brasil é Brasília."

Estado customizado

Para agentes mais complexos, defina seu próprio estado:

from typing import TypedDict, Annotated, List
from langgraph.graph import StateGraph, START, END
import operator

class AgentState(TypedDict):
    messages: Annotated[List, operator.add]  # lista acumulativa
    task: str                                 # tarefa atual
    step_count: int                           # contador de passos
    final_answer: str                         # resposta final

def planner(state: AgentState):
    """Planeja os próximos passos."""
    # ...
    return {"step_count": state["step_count"] + 1}

---

Construindo um agente com ferramentas

O padrão mais comum: um agente que chama ferramentas, processa resultados e decide quando parar.

from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.prebuilt import ToolNode

# 1. Definindo ferramentas
@tool
def buscar_preco_produto(nome_produto: str) -> str:
    """Busca o preço atual de um produto no sistema."""
    # Em produção: chamada real à API/banco de dados
    precos = {"notebook": "R$ 3.500", "mouse": "R$ 150", "teclado": "R$ 280"}
    return precos.get(nome_produto.lower(), "Produto não encontrado")

@tool
def calcular_desconto(preco: str, percentual: float) -> str:
    """Calcula o preço com desconto aplicado."""
    valor = float(preco.replace("R$ ", "").replace(".", "").replace(",", "."))
    desconto = valor * (percentual / 100)
    return f"R$ {valor - desconto:.2f}"

ferramentas = [buscar_preco_produto, calcular_desconto]

# 2. LLM com ferramentas vinculadas
llm_com_tools = ChatOpenAI(model="gpt-4o").bind_tools(ferramentas)

# 3. Nó do agente
def agente(state: MessagesState):
    return {"messages": [llm_com_tools.invoke(state["messages"])]}

# 4. Roteador: decide se executa ferramenta ou termina
def deve_continuar(state: MessagesState):
    ultima_msg = state["messages"][-1]
    if ultima_msg.tool_calls:
        return "tools"  # ir para o nó de ferramentas
    return END          # terminar

# 5. Montando o grafo
graph = StateGraph(MessagesState)
graph.add_node("agente", agente)
graph.add_node("tools", ToolNode(ferramentas))

graph.add_edge(START, "agente")
graph.add_conditional_edges("agente", deve_continuar)
graph.add_edge("tools", "agente")  # volta ao agente após ferramenta

app = graph.compile()

# Testando
for evento in app.stream({
    "messages": [{"role": "user", "content": "Qual o preço do notebook com 10% de desconto?"}]
}):
    for nó, valores in evento.items():
        if nó != "__end__":
            print(f"[{nó}]: {valores['messages'][-1].content[:100]}")

---

Persistência e memória entre sessões

Uma das capacidades mais poderosas do LangGraph é a persistência de estado. O agente pode ser interrompido e retomado, mantendo todo o contexto.

from langgraph.checkpoint.memory import MemorySaver

# MemorySaver = memória em RAM (para dev)
# SqliteSaver, PostgresSaver = para produção
checkpointer = MemorySaver()

app = graph.compile(checkpointer=checkpointer)

# Thread ID: identifica uma conversa/sessão
config = {"configurable": {"thread_id": "usuario-123"}}

# Primeira interação
app.invoke(
    {"messages": [{"role": "user", "content": "Meu nome é Carlos."}]},
    config=config
)

# Segunda interação — o agente lembra do nome!
resultado = app.invoke(
    {"messages": [{"role": "user", "content": "Qual é meu nome?"}]},
    config=config
)
print(resultado["messages"][-1].content)
# → "Seu nome é Carlos."

# Inspecionar o estado salvo
estado = app.get_state(config)
print(f"Mensagens na memória: {len(estado.values['messages'])}")

---

Human-in-the-loop: aprovação humana antes de executar

Agentes que tomam ações irreversíveis (enviar e-mail, executar código, fazer compra) precisam de aprovação humana em pontos críticos. LangGraph resolve isso com interrupts.

from langgraph.types import interrupt

def nó_critico(state: MessagesState):
    """Pede aprovação antes de executar ação sensível."""
    acao = preparar_acao(state)
    
    # PAUSA a execução e retorna ao chamador
    aprovado = interrupt({
        "pergunta": "Confirma o envio do e-mail?",
        "para": "cliente@empresa.com",
        "assunto": "Proposta Comercial",
        "preview": acao["preview"]
    })
    
    if aprovado:
        return executar_acao(acao)
    else:
        return {"messages": [{"role": "ai", "content": "Envio cancelado."}]}

# No frontend, você verifica se há interrupts pendentes:
estado = app.get_state(config)
if estado.next:
    # Há uma interrupção aguardando
    interrupt_data = estado.tasks[0].interrupts[0].value
    # Mostra para o usuário e coleta resposta...
    
    # Retoma com a resposta do usuário
    app.invoke(Command(resume=True), config=config)

---

Deploy em produção

Para produção, use LangSmith — a plataforma gerenciada do LangChain:

# langgraph.json — configuração de deploy
{
  "dependencies": ["."],
  "graphs": {
    "meu_agente": "./agente.py:app"
  },
  "env": ".env"
}

# Deploy no LangSmith
pip install langgraph-cli
langgraph deploy

Alternativamente, o LangGraph Server pode ser rodado self-hosted com Docker:

docker run -p 8123:8000 \
  -e OPENAI_API_KEY=$OPENAI_API_KEY \
  langchain/langgraph-api

---

Quando usar LangGraph (e quando não usar)

Use LangGraph quando:

• O agente precisa de múltiplos passos com lógica condicional complexa
• Você precisa de persistência entre sessões (histórico de conversa, memória)
• A tarefa exige human-in-the-loop estruturado
• Você quer debugar e rastrear cada passo do agente
• O sistema precisa retomar após falha ou timeout

Prefira alternativas quando:

• A tarefa é simples e linear (use LangChain sem grafo)
• Você não tem experiência em Python (use Flowise ou n8n)
• Precisa de deploy rápido sem infra (use Relevance AI ou Make)
• O time não tem engenheiros de software (use soluções no-code)

---

Comparativo rápido

Critério	LangGraph	CrewAI	AutoGPT
Curva de aprendizado	Alta	Média	Baixa
Controle	Total	Alto	Baixo
Multi-agente	Sim (Subgraphs)	Nativo	Sim
Persistência	Nativa	Plugin	Parcial
Community	Grande	Crescente	Enorme
Ideal para	Devs Python sênior	Times de agentes	Prototipagem

---

Recursos para aprender mais

• Documentação oficial: docs.langchain.com/langgraph
• Tutoriais interativos: academy.langchain.com
• GitHub: github.com/langchain-ai/langgraph (34k+ ⭐)
• Exemplos prontos: github.com/langchain-ai/langgraph/tree/main/examples
• LangSmith (rastreamento): smith.langchain.com

LangGraph é hoje o framework Python mais maduro para agentes em produção. A curva de aprendizado é real, mas o controle que você ganha — sobre fluxo, estado, memória e rastreamento — é insubstituível para sistemas que precisam ser confiáveis.