# LangGraph: Guia Definitivo para Agentes Stateful em 2026 > Guia completo do LangGraph em 2026: grafos de estado, checkpointing, human-in-the-loop e deploy em produção. Tutorial prático incluso. Source: https://agentify.ia.br/blog/langgraph/ > **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](/blog/agent-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=) @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", ) +, } ``` **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"][-].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"][-] 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": , }) 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: - Recebe o estado atual - Faz alguma computação (chamar LLM, executar tool, transformar dados) - 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"][-].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](/blog/harness-e-loop-arquitetura-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](/blog/multi-agente-trabalhando-em-paralelo) que complementa muito bem essa seção. --- ## Spider Chart: Avaliação em 8 Eixos Eixo Nota Justificativa Código 85 API expressiva com duas abordagens (Graph API e Functional API). TypedDict para estado é pythônico. Curva de aprendizado moderada — conceitos de grafo assustam no começo mas o modelo mental é poderoso uma vez internalizado. Contexto 90 Estado persistente é cidadão de primeira classe. Checkpointing, memory stores, threads — LangGraph foi desenhado de baixo pra cima para manter contexto rico entre invocações. Melhor gestão de contexto do ecossistema. Autonomia 70 Oferece ciclos e roteamento condicional para autonomia, mas por design incentiva controle humano. Human-in-the-loop é feature, não limitação. Não é a escolha se você quer agente “fire-and-forget” radical. Velocidade 60 Overhead de framework é real. Serialização/deserialização de estado, checkpointing a cada step. Para tarefas simples, é overkill. Para workflows complexos, o trade-off vale. Latência adicional é aceita em troca de confiabilidade. Custo-benefício 75 Framework open-source e gratuito. LangSmith tem free tier generoso. O custo real é complexidade de desenvolvimento — mais boilerplate que alternativas simplificadas. Mas paga-se uma vez e escala para sempre. Especialização 80 Projetado especificamente para agentes stateful de produção. Não tenta ser tudo — não é para RAG simples, não é para scripts lineares. Faz uma coisa e faz muito bem. Multi-agente 82 Subgrafos nativos, execução paralela de nós, state handoff entre agentes. Não é tão plug-and-play quanto CrewAI para prototipagem, mas infinitamente mais controlável em produção. Ecossistema 92 36K stars, 34.5M downloads/mês, LangSmith para observabilidade, LangGraph Platform para deploy, integrações com 100+ providers via LangChain. Documentação extensa. Comunidade ativa. O ecossistema mais maduro para agentes Python em 2026. --- ## 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](/blog/ferramentas-tools-e-mcp-servers). --- ## Comparativo rápido com alternativas Aspecto LangGraph CrewAI AutoGen (Microsoft Agent Framework) Modelo mental Grafo de estados Roles e tarefas Chat entre agentes Controle Total (explícito) Médio (abstraído) Baixo (conversacional) Produção Maduro Crescendo Maintenance mode / migração Curva aprendizado Média-alta Baixa Média Multi-agente Subgrafos nativos Role-based teams Group chat patterns Observabilidade LangSmith (integrado) Básica Azure Monitor Human-in-the-loop Nativo (interrupt) Plugin Manual 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 é: - **Monte o tutorial acima** e execute localmente. Brinque com as tools, adicione mais nós, crie branches condicionais. - **Adicione checkpointing com PostgresSaver** — transforme o agente stateless em um que sobrevive a restarts: ``` pip install langgraph-checkpoint-postgres ``` - **Implemente human-in-the-loop** em um ponto crítico. Sinta como é ter controle de aprovação no meio de um workflow autônomo. - **Conecte LangSmith** e execute 10 conversas diferentes. Observe os traces. Identifique onde o agente demora, onde erra, onde poderia ser otimizado. - **Explore subgrafos** — crie dois agentes especializados e orquestre-os. Pesquisador + Escritor é um clássico pra começar. - **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](https://docs.langchain.com/oss/python/langgraph/overview) - [LangGraph Academy](https://academy.langchain.com) — curso gratuito - [LangSmith](https://smith.langchain.com) — observabilidade - [LangGraph Platform](https://docs.langchain.com/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](https://ft.ia.br).* -->