O que é LangGraph? Guia Completo para Criar Agentes de IA Stateful

A maioria do código de agente começa de forma simples e depois colapsa sob suas próprias tentativas e erros. Você conecta um LLM, dá a ele algumas ferramentas e, no momento em que o fluxo de trabalho precisa fazer um loop, ramificar ou pausar para um humano, o script linear desmorona. LangGraph é o framework construído exatamente para essa confusão: ele modela um agente como um grafo com estado compartilhado, de modo que loops e ramificações se tornam uma estrutura de primeira classe em vez de emaranhados de declarações if. Este guia explica o que é LangGraph, o problema que ele resolve e onde o teste de API se encaixa quando seu agente chama serviços reais.

O que é LangGraph

LangGraph é um framework de orquestração e tempo de execução de baixo nível para construir agentes de longa duração e com estado. Ele é construído pela LangChain Inc, a equipe por trás do LangChain, mas é uma biblioteca separada com seu próprio foco. Você o instala por conta própria com pip install -U langgraph, e pode usá-lo sem o resto do ecossistema LangChain.

A ideia central é pequena. Você descreve seu agente como um grafo. Os nós realizam trabalho (chamam um modelo, executam uma ferramenta, transformam dados). As arestas decidem o que será executado em seguida. Um objeto de estado compartilhado flui por cada nó, e cada nó pode lê-lo e escrever de volta nele. Como as arestas podem apontar para trás, o grafo pode ciclar. Essa é a parte que uma cadeia simples não consegue fazer bem.

Se você usou a antiga abstração Chain do LangChain, a diferença é a forma do fluxo de controle. Uma cadeia é um pipeline: passo um, passo dois, passo três, pronto. Um grafo permite que um nó inspecione o estado atual e, em seguida, salte para um ramo diferente, volte para tentar novamente ou se ramifique para vários nós que são executados em paralelo e mesclam seus resultados. Agentes reais precisam disso, porque "raciocinar, agir, observar, raciocinar novamente" é um loop, não uma linha.

O problema que LangGraph resolve

Fluxos de trabalho agentivos são cíclicos por natureza. Um agente chama uma ferramenta, olha o resultado, decide se terminou e, se não, tenta novamente. Modelar isso com condicionais aninhadas torna-se ilegível rapidamente, e piora quando você adiciona as coisas que os agentes de produção realmente precisam:

• Loops com uma condição de parada. Continue chamando ferramentas até que a tarefa esteja completa, sem girar infinitamente.
• Ramificação baseada no estado. Roteie para um nó diferente dependendo do que o modelo retornou.
• Persistência. Sobreviva a uma falha, um tempo limite ou uma reinicialização e retome do último ponto válido.
• Human-in-the-loop. Pause, permita que uma pessoa inspecione ou edite o estado e, em seguida, continue.
• Streaming. Emita tokens e etapas intermediárias à medida que acontecem, não apenas no final.

LangGraph transforma cada um desses recursos em uma capacidade embutida, em vez de algo que você cria manualmente. Você obtém uma máquina de estado com execução durável, de modo que um agente pode ser executado por minutos ou horas e retomar de onde parou.

Conceitos centrais: grafo, estado, nós, arestas

Quatro primitivos carregam a maior parte do framework. Veja como eles se encaixam.

Estado é um objeto tipado compartilhado em toda a execução. Você define sua forma com um esquema, frequentemente um TypedDict, e LangGraph mescla as atualizações de cada nó nele. Um ponto de partida comum é MessagesState, um esquema pré-construído que mantém uma lista contínua de mensagens de chat.

Nós são funções. Cada um deles recebe o estado atual e retorna uma atualização parcial. Você os registra com add_node().

Arestas conectam nós. Uma aresta normal com add_edge() sempre vai de A para B. Uma aresta condicional com add_conditional_edges() executa uma função de roteamento que lê o estado e retorna o nome do próximo nó, que é como você expressa "se o modelo pediu uma ferramenta, vá executá-la; caso contrário, finalize".

START e END são marcadores especiais para onde a execução começa e para.

Aqui está a forma de um grafo mínimo. É um nível de pseudocódigo, mas os nomes das APIs são reais.

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

def call_model(state: MessagesState):
    response = model.invoke(state["messages"])
    return {"messages": [response]}

def should_continue(state: MessagesState) -> str:
    last = state["messages"][-1]
    return "tools" if last.tool_calls else END

builder = StateGraph(MessagesState)
builder.add_node("model", call_model)
builder.add_node("tools", tool_node)
builder.add_edge(START, "model")
builder.add_conditional_edges("model", should_continue)
builder.add_edge("tools", "model")   # loop back

graph = builder.compile()

A linha add_edge("tools", "model") é o ciclo. Depois que as ferramentas são executadas, o controle volta para o modelo, que pode chamar mais ferramentas ou parar. Esse loop é a razão pela qual LangGraph existe.

Persistência e Human-in-the-loop

Compile um grafo com um checkpointer e ele salva um instantâneo do estado após cada etapa. Passe um thread_id na configuração e LangGraph restaurará o checkpoint mais recente para aquele thread na próxima chamada. Seus nós não mudam; o tempo de execução lida com o salvamento e a restauração.

from langgraph.checkpoint.memory import InMemorySaver

graph = builder.compile(checkpointer=InMemorySaver())
config = {"configurable": {"thread_id": "user-42"}}
graph.invoke({"messages": [user_message]}, config)

InMemorySaver é bom para desenvolvimento. Para algo que sobreviva a reinicializações, LangGraph oferece salvadores baseados em banco de dados (SQLite para um único servidor, Postgres para escala multi-instância). Como o estado é durável, você também obtém human-in-the-loop quase de graça. Você pode interromper o grafo em um ponto escolhido, exibir o estado atual para uma pessoa inspecionar ou editar e, em seguida, retomar daquele checkpoint exato. Portões de aprovação, correções manuais e etapas de "você tem certeza?" são todos construídos sobre isso.

O streaming completa o quadro. LangGraph pode transmitir tokens do modelo e atualizações no nível do nó à medida que a execução avança, de modo que uma interface de usuário pode mostrar o agente pensando em vez de ficar olhando para um spinner.

Como LangGraph se relaciona com LangChain

Isso confunde as pessoas, então vamos ser diretos. LangChain é o kit de ferramentas mais amplo: wrappers de modelo, templates de prompt, retrievers, carregadores de documentos e integrações com centenas de provedores. LangGraph é a camada de orquestração subjacente às partes do agente desse kit de ferramentas.

Você não precisa de LangChain para usar LangGraph. Você pode definir seu estado, nós e arestas, e chamar qualquer cliente de modelo que desejar dentro de um nó. Muitas equipes combinam os dois, porque as abstrações de modelo e ferramenta do LangChain são convenientes, e o auxiliar create_react_agent pré-construído do LangGraph (em langgraph.prebuilt) oferece um agente de chamada de ferramenta funcional em algumas linhas quando você não precisa de um grafo personalizado.

Uma observação para os usuários atuais: a linha LangGraph v1.0 (estável desde o final de 2025) tem movido o auxiliar de agente pré-construído para langchain.agents.create_agent, então verifique sua versão instalada e a referência oficial para o caminho de importação exato antes de copiar trechos mais antigos. Construir agentes personalizados do zero é uma habilidade útil aqui também; veja nosso passo a passo sobre a construção de um agente de IA personalizado para uma visão mais ampla.

LangGraph Platform e Studio

A biblioteca de código aberto é o núcleo, mas dois produtos adjacentes importam uma vez que você entra em produção.

LangGraph Studio é um IDE visual de agente. Ele renderiza seu grafo, permite que você o execute e mostra o estado em cada nó para que você possa observar a execução passo a passo através de seus nós e arestas. Para qualquer coisa com ciclos e roteamento condicional, ver o caminho que o agente realmente percorreu é melhor do que ler linhas de log.

LangGraph Platform é o lado da implantação gerenciada: endpoints de API para seus agentes, persistência embutida para execuções de longa duração e opções de hospedagem que variam de auto-hospedado a totalmente gerenciado na nuvem. Você não precisa dele para usar a biblioteca; ele está lá quando você precisa de infraestrutura para agentes em produção, em vez de executá-los por conta própria.

Quando usar LangGraph

Recorra ao LangGraph quando seu agente tiver um fluxo de controle real. Bons sinais:

• O trabalho é um loop, não uma sequência (chamar ferramentas, verificar, repetir).
• Você precisa ramificar com base no que o modelo decidiu.
• Uma execução pode ser longa, e você quer que ela sobreviva a uma falha e seja retomada.
• Um humano precisa aprovar ou editar algo no meio da execução.
• Você está coordenando múltiplos atores ou sub-agentes que compartilham estado.

Ignore-o quando uma única chamada de modelo ou uma cadeia linear curta resolve o problema. Um grafo é um custo adicional que você não precisa para "resumir este texto". Guarde a estrutura para fluxos de trabalho que realmente se ramificam e fazem loop.

Onde o teste de API e a simulação se encaixam

Aqui está a parte que afeta as equipes em desenvolvimento. Um agente LangGraph é tão confiável quanto as APIs que ele chama, e ele chama muitas delas: o endpoint do LLM, além de cada API de ferramenta (busca, um CRM, seu próprio backend). LangGraph orquestra essas chamadas; ele não as testa. Esse é um trabalho separado, e é onde o Apidog entra em cena.

Dois problemas aparecem rapidamente. Primeiro, acessar APIs reais em cada execução de teste gasta tokens e atinge limites de taxa. Você pode simular a API da qual um agente depende para que um endpoint de ferramenta retorne uma resposta determinística e instantânea enquanto você itera na lógica do grafo. Simule o endpoint do LLM da mesma forma e você para de pagar por tokens apenas para testar o roteamento.

Em segundo lugar, seus nós assumem uma forma de resposta. Se a API de uma ferramenta muda silenciosamente o nome de um campo, sua aresta condicional lê a coisa errada e o agente entra em loop ou trava. Fixar esses contratos com asserções de API detecta o desvio antes que ele atinja seu grafo. E como os agentes lidam com chaves entre ambientes de desenvolvimento e produção, gerenciá-las em ambientes mantém os segredos fora do código do seu nó. Se você quiser o fluxo de trabalho completo focado no agente, o kit de teste Apidog para agentes de IA detalha isso do início ao fim. Para ser claro, nada disso orquestra o agente; o Apidog testa e simula as APIs subjacentes a ele.

Perguntas Frequentes

LangGraph é um substituto para LangChain? Não. LangGraph é o tempo de execução de orquestração; LangChain é o conjunto mais amplo de componentes e integrações. São bibliotecas separadas da mesma equipe, e você pode executar LangGraph sem LangChain ou usá-los juntos. LangGraph lida com o fluxo de controle com estado e cíclico com o qual as cadeias simples têm dificuldade.

Preciso conhecer LangChain para começar com LangGraph? Não. Você pode definir um StateGraph, adicionar nós e arestas, e chamar qualquer cliente de modelo dentro de um nó. Os wrappers de modelo do LangChain são convenientes, mas são opcionais. Comece com os primitivos de grafo principais e adicione o restante apenas quando precisar.

Como o LangGraph lembra as coisas entre as chamadas? Através de checkpointers. Compile seu grafo com um checkpointer e passe um thread_id, e LangGraph salva um instantâneo do estado após cada etapa, então o restaura na próxima chamada para aquele thread. É assim que você obtém memória de conversa e recuperação de falhas sem alterar a lógica do seu nó.

Como testo as APIs que meu agente chama? Teste e simule-as separadamente do grafo. Simule os endpoints LLM e da ferramenta para que as execuções sejam rápidas e gratuitas durante o desenvolvimento, e faça asserções nas formas de resposta para que um campo alterado não quebre um nó. Nosso guia sobre o teste da API ChatGPT cobre autenticação, streaming e chamadas de ferramenta, que são as superfícies exatas das quais um agente depende.

Conclusão

LangGraph oferece a estrutura que faltava para agentes que fazem loops, ramificam, persistem e pausam para um humano. Modele o fluxo de trabalho como um grafo com estado compartilhado, utilize checkpointers para memória e recuperação, e use o Studio e a Plataforma quando estiver pronto para depurar e implantar. O framework lida com a orquestração. As APIs que seu agente chama ainda precisam de sua própria rede de segurança, então simule e teste-as no Apidog para manter o desenvolvimento barato e seus contratos de ferramenta honestos. Baixe o Apidog para simular um endpoint e validar suas respostas antes que seu agente o acesse de verdade.