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](https://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

```bash
pip install -U langgraph langchain-openai
```

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

```bash
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.

```python
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:

```python
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.

```python
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.

```python
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`.

```python
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:

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

```bash
# Deploy no LangSmith
pip install langgraph-cli
langgraph deploy
```

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

```bash
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](https://docs.langchain.com/langgraph)
- **Tutoriais interativos**: [academy.langchain.com](https://academy.langchain.com)
- **GitHub**: [github.com/langchain-ai/langgraph](https://github.com/langchain-ai/langgraph) (34k+ ⭐)
- **Exemplos prontos**: [github.com/langchain-ai/langgraph/tree/main/examples](https://github.com/langchain-ai/langgraph/tree/main/examples)
- **LangSmith (rastreamento)**: [smith.langchain.com](https://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.