Construa um AI Agent com o LangGraph: Tutorial Passo a Passo

O LangGraph é o framework de baixo nível da LangChain para construir AI agents com estado, na forma de um grafo explícito de nós e arestas, dando a você controle direto sobre como um agent se ramifica, faz pausas e persiste o estado ao longo de uma tarefa de longa duração. É o caminho via código a que as equipes recorrem quando um trabalho exige lógica condicional, fluxos de aprovação em várias etapas ou uma memória que dure dias, e não apenas uma conversa. Este guia aborda o que o LangGraph realmente é, como instalá-lo, um passo a passo completo de construção com dois exemplos funcionais e quando ele é a plataforma certa em comparação com as alternativas.

O Que o LangGraph Realmente É

O LangGraph é um framework de orquestração de baixo nível e um runtime para construir, gerenciar e implantar agents com estado e de longa duração. Ele é separado das abstrações de nível mais alto do LangChain: o LangChain oferece modelos, ferramentas e padrões de agents prontos; o LangGraph oferece o runtime baseado em grafos que fica por baixo, no qual você define nós como etapas de computação, arestas como os caminhos entre eles e um objeto de estado compartilhado que flui por toda a execução. É uma escolha de design deliberada: padrões razoáveis quando você não precisa de muito controle, um grafo explícito quando precisa.

O uso real em produção sustenta a proposta. O texto da própria LangChain sobre o LangGraph em produção cita como usuários em produção a Uber (migrações de código em larga escala na sua plataforma de desenvolvedores), o LinkedIn (um recrutador com AI que automatiza a busca e o envio de mensagens a candidatos), o Replit (um sistema multiagente com revisão por um humano) e a Elastic (orquestrando uma rede de agents para detecção de ameaças em tempo real). O copilot de gestão de imóveis da AppFolio, também construído sobre o LangGraph, economizou mais de 10 horas por semana dos seus gestores de imóveis e dobrou a precisão das decisões deles, um resultado concreto, e não uma vaga afirmação de adoção.

Esse tipo de implantação está se tornando a norma, não a exceção. O Gartner projeta que 40% dos aplicativos corporativos terão AI agents específicos para tarefas até o final de 2026, contra menos de 5% em 2025, e uma parte significativa dessa mudança acontece em frameworks criados especificamente para sistemas multiagente, como o LangGraph, em que um grafo pode modelar um orquestrador entregando o trabalho a vários nós especializados, em vez de um único modelo fazer tudo de uma só vez.

O Vocabulário do LangGraph, Mapeado para os 6 Blocos de Construção

Se você leu como construir um AI agent, conhece os seis blocos de que todo agent precisa: Papel, Ferramentas, Regras, Manual de cenários, Lógica de decisão e Barreiras de proteção. O LangGraph dá a cada um deles um lugar concreto no código.

Nada disso é exclusivo do LangGraph do ponto de vista conceitual. O que o LangGraph acrescenta é um grafo explícito e inspecionável em vez de um loop de caixa-preta, exatamente o tipo de controle que no-code vs código em AI agents diz que você deve buscar quando a lógica de um trabalho se torna realmente personalizada.

Instalando o LangGraph

pip install -U langgraph langchain

O langgraph é a biblioteca principal de grafos e o runtime. O langchain acrescenta o create_agent, o ponto de entrada de alto nível atual para um agent padrão que chama ferramentas, e que roda por baixo dos panos sobre o LangGraph. Defina uma chave de API do seu provedor de modelos como variável de ambiente e você estará pronto para construir.

O Caminho Rápido: create_agent

Para um único agent que só precisa de um modelo, algumas ferramentas e um system prompt, você não precisa mexer diretamente no grafo:

from langchain.agents import create_agent

def get_account_status(company: str) -> str:
    """Look up a customer account's status by company name."""
    return f"{company}: active, plan tier Growth, renewal in 45 days."

agent = create_agent(
    model="claude-sonnet-4-6",
    tools=[get_account_status],
    system_prompt="You are a support assistant. Answer only from tool results, never guess.",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What's the status of Acme Corp's account?"}]}
)
print(result["messages"][-1].content)

É a mesma mecânica de como os AI agents usam ferramentas em que toda plataforma se apoia: descrever uma função, deixar o modelo decidir quando chamá-la e devolver o resultado a ele. O create_agent substituiu o antigo helper create_react_agent do LangGraph como ponto de partida recomendado: mesma ideia, API mais limpa.

Descendo de Nível: Um Grafo Personalizado com Roteamento Condicional

O caminho rápido cobre bastante coisa, mas não consegue expressar "faça X e depois siga para uma etapa de revisão humana apenas se houver um risco sinalizado". Para isso, você constrói o grafo diretamente. Aqui está um fluxo simplificado de revisão de contratos, próximo do blueprint do AI Contract Review Agent: analisar um contrato e depois encaminhar para um revisor humano ou aprovar automaticamente, conforme o que a análise encontrar.

from typing import TypedDict
from langgraph.graph import StateGraph, START, END
from langgraph.checkpoint.memory import InMemorySaver

class ReviewState(TypedDict):
    contract_text: str
    risk_flagged: bool
    summary: str

def analyze_contract(state: ReviewState) -> dict:
    # call the model here to extract terms and set risk_flagged
    return {"risk_flagged": True, "summary": "Non-standard liability cap on page 4."}

def route_on_risk(state: ReviewState) -> str:
    return "human_review" if state["risk_flagged"] else "auto_approve"

def human_review(state: ReviewState) -> dict:
    return {"summary": state["summary"] + " Routed to legal for review."}

def auto_approve(state: ReviewState) -> dict:
    return {"summary": state["summary"] + " Auto-approved, no flags."}

graph = StateGraph(ReviewState)
graph.add_node("analyze", analyze_contract)
graph.add_node("human_review", human_review)
graph.add_node("auto_approve", auto_approve)

graph.add_edge(START, "analyze")
graph.add_conditional_edges("analyze", route_on_risk, {
    "human_review": "human_review",
    "auto_approve": "auto_approve",
})
graph.add_edge("human_review", END)
graph.add_edge("auto_approve", END)

app = graph.compile(checkpointer=InMemorySaver())

O add_conditional_edges é o bloco de lógica de decisão tornado literal: depois que o analyze é executado, o route_on_risk inspeciona o estado e envia a execução por um de dois caminhos nomeados. É uma ramificação que um loop linear único de chamada de ferramentas não consegue expressar com clareza, e é o motivo pelo qual as equipes recorrem ao LangGraph quando sistemas multiagente ou fluxos de aprovação em várias etapas entram em cena.

Persistência e Memória

O argumento checkpointer em compile() é o que torna um grafo retomável, em vez de sem estado. O InMemorySaver, mostrado acima, serve para testes locais, mas desaparece quando o processo é reiniciado. Os grafos em produção usam um backend persistente: os checkpoint savers de SQLite ou Postgres vêm como pacotes instaláveis separados, indexados por um thread_id, de modo que o estado de uma execução específica possa ser recarregado e continuado dias depois. É a mesma distinção entre memória de trabalho e memória persistente abordada de forma geral em memória de AI agents: um checkpointer é a resposta concreta do LangGraph para a memória persistente.

Intervenção Humana com Interrupções

A função interrupt() do LangGraph pausa a execução do grafo em um ponto específico e aguarda uma entrada externa antes de retomar, exatamente o que o nó human_review acima precisa em uma implementação real, no lugar da lógica provisória mostrada. Uma pessoa (ou outro sistema) revisa o estado pausado e responde, e o grafo retoma exatamente desse ponto, usando o estado salvo no checkpoint em vez de recomeçar. Esse é o mecanismo concreto por trás dos portões de aprovação abordados de forma geral em intervenção humana em AI agents: o grafo não adivinha quando um humano deve entrar em cena, você incorpora essa decisão diretamente na lógica de roteamento.

Barreiras de Proteção e Testes Antes de Entrar no Ar

Uma aresta condicional é tão boa quanto a lógica que decide para onde rotear, então valide essa lógica antes que ela toque em contratos, tickets ou registros reais. Adicione verificações explícitas dentro de um nó (rejeite ou tente de novo uma saída que falhe em uma regra que você definir), em vez de confiar apenas no julgamento do modelo, a disciplina abordada em barreiras de proteção para AI agents. E não considere um grafo pronto após um único teste bem-sucedido. Como avaliar e testar AI agents mostra como montar um conjunto de testes de verdade a partir de casos históricos, incluindo os confusos que devem ser encaminhados para revisão humana, antes que qualquer agent do LangGraph toque em volume de produção.

Custo e Limites

O LangGraph em si é gratuito e open source. O que você paga é o uso da API do LLM, e um grafo com mais nós e mais ramificações faz mais chamadas ao modelo do que um único agent bem delimitado fazendo o mesmo trabalho, o mesmo trade-off abordado em sistemas multiagente. Se você prefere não hospedar e monitorar o grafo por conta própria, a LangChain também oferece o LangGraph Platform, uma opção paga de implantação hospedada, com persistência e observabilidade integradas; executá-lo por conta própria não custa nada além da sua própria infraestrutura e das chamadas ao modelo.

O limite real não é o preço: é que o LangGraph não oferece construtor visual nem conectores de aplicativos prontos. Cada integração, cada política de novas tentativas, cada tratamento de erro é código que você escreve, a troca direta pelo controle que um grafo oferece em relação à lógica limitada de uma plataforma no-code.

Quando Escolher o LangGraph e Quando Escolher as Alternativas

Fatos Principais

• O LangGraph é um framework de orquestração e runtime de baixo nível e open source para agents com estado, separado das abstrações de nível mais alto do LangChain, mas complementar a elas.
• Entre os usuários em produção documentados estão Uber, LinkedIn, Replit e Elastic; o copilot da AppFolio, construído com o LangGraph, economizou mais de 10 horas por semana dos gestores de imóveis e dobrou a precisão das decisões.
• O create_agent, do pacote langchain, é o ponto de entrada de alto nível recomendado atualmente, substituindo o antigo helper create_react_agent, e roda sobre o LangGraph.
• O StateGraph com add_conditional_edges é o que permite a um agent se ramificar com base na própria saída, a mecânica por trás dos fluxos de aprovação e da lógica de decisão em várias etapas.
• Um checkpointer (em memória para testes, SQLite ou Postgres para produção) torna um grafo retomável entre sessões, indexado por thread_id.

Para Onde Ir a Seguir

O LangGraph é um caminho via código para um agent funcional, não o único. Construa um AI agent com o CrewAI aborda um framework mais baseado em papéis para trabalhos multiagente, e se você ainda está decidindo entre escrever código e usar um construtor visual, como escolher uma plataforma de AI agents percorre essa decisão diretamente, entre opções no-code, frameworks e serviços gerenciados. Quando um grafo funcionar de forma confiável nos testes, implantando AI agents em produção aborda o lançamento e o plano de rollback antes de ele tocar em volume real. O panorama de ferramentas para desenvolvedores e o guia de compra de assistentes de código com AI são boas próximas paradas para escrever e manter o próprio código mais rápido.