LangGraph: quando usar grafos de estado em agentes de IA

LangGraph: quando usar grafos de estado em agentes de IA

LangGraph é uma biblioteca para construir agentes de IA como um grafo com estado: etapas (nós) leem e atualizam um estado compartilhado, e regras (arestas) decidem qual etapa vem depois. Vale considerar quando o fluxo tem ramificações, repetições, pausas para aprovação humana e a necessidade de retomar exatamente de onde parou. Se o processo é uma sequência curta e previsível, um fluxo simples, com código comum ou uma ferramenta de automação, costuma ser suficiente e mais fácil de manter.

Principais pontos

• Um grafo com estado tem três peças: o estado (os dados que viajam pelo fluxo), os nós (as etapas) e as arestas (as regras de caminho, fixas ou condicionais).
• A persistência permite pausar, retomar e auditar uma execução, o que importa quando uma aprovação humana pode levar horas ou dias.
• Aprovação humana de verdade é uma pausa do fluxo com o estado guardado, não apenas um aviso enviado a alguém.
• Fluxo simples basta quando o caminho é linear, curto, sem espera longa e sem decisões que dependam do que aconteceu antes.
• A escolha deve partir do problema do processo, não da ferramenta: comece simples, meça onde o fluxo quebra e só então adote o grafo.

O que é um grafo com estado, sem jargão?

Imagine um processo de atendimento desenhado em um quadro: caixas para as etapas e setas para os caminhos possíveis. Em um grafo com estado, esse desenho vira código. Cada caixa é uma função que recebe o estado atual, faz algo (chama um modelo, consulta um sistema, valida um dado) e devolve o que mudou. Cada seta diz para onde ir em seguida, às vezes sempre o mesmo lugar, às vezes dependendo do conteúdo do estado.

O estado é o ponto central. Em vez de cada etapa receber apenas a saída da anterior, todas trabalham sobre um registro comum: a mensagem do cliente, os dados já coletados, o rascunho de resposta, quantas tentativas foram feitas, se houve aprovação. Isso torna explícito o que o agente sabe em cada momento, e facilita responder à pergunta que todo gestor acaba fazendo: por que o agente fez isso?

A documentação oficial do LangGraph descreve esse modelo com nós, arestas e arestas condicionais, e permite ciclos, ou seja, voltar a uma etapa anterior. Os nomes exatos das funções e dos módulos mudam entre versões, então confirme sempre na documentação da versão que você for usar.

Quando um fluxo simples é suficiente?

A própria Anthropic, no texto sobre como construir agentes eficazes, recomenda começar pela solução mais simples e aumentar a complexidade só quando houver necessidade demonstrada. O mesmo texto separa workflows (caminhos definidos em código) de agentes (o modelo decide dinamicamente os passos) e alerta que frameworks podem adicionar camadas que escondem prompts e respostas, dificultando a depuração.

Na prática, um fluxo simples costuma bastar quando:

• as etapas são sempre as mesmas, na mesma ordem (por exemplo, receber a mensagem, classificar, responder);
• o fluxo termina em poucos segundos, sem esperar por pessoa nenhuma;
• se algo falha, repetir tudo desde o início é barato e seguro;
• não há laços do tipo tentar, verificar, corrigir, tentar de novo;
• uma ferramenta de automação como o n8n já cobre as integrações, e você só precisa de uma chamada ao modelo no meio.

Se esse é o seu caso, vale olhar o artigo sobre erros e retentativas no n8n, que trata de como manter um fluxo determinístico estável sem introduzir um framework de agentes.

Quando o grafo passa a compensar?

O grafo começa a pagar o custo de aprendizado quando o fluxo deixa de ser uma linha. Use o guia abaixo como lista de verificação: quanto mais itens forem verdadeiros no seu processo, maior a chance de o grafo ser a ferramenta certa.

• Há ramificações reais: o próximo passo depende do que foi descoberto no passo anterior, e os caminhos são vários.
• Há laços: o agente precisa tentar, checar o resultado e tentar de novo, com um limite claro de tentativas.
• Há esperas longas: o fluxo precisa parar por horas ou dias aguardando uma pessoa, um cliente ou um sistema externo.
• Há aprovação humana em pontos específicos, e a pessoa pode aprovar, rejeitar ou editar antes de o fluxo continuar.
• Há necessidade de retomar após uma falha sem refazer etapas caras ou repetir ações com efeito externo.
• Há necessidade de auditoria: saber o que o agente sabia e decidiu em cada etapa.
• Há várias partes do trabalho com responsabilidades distintas, mas ainda sob um estado comum.

Sobre o último ponto, cuidado: dividir em vários agentes não é objetivo em si. O artigo sobre sistema multiagente e quando um único agente basta ajuda a testar se a divisão resolve um problema real antes de complicar a arquitetura.

Um laço também exige trava. Todo ciclo no grafo precisa de limite de passos, de tempo e de gasto, caso contrário o agente pode ficar tentando indefinidamente. O texto sobre agente de IA em loop e limites de passos detalha como definir essas travas.

Como funcionam os pontos de aprovação humana?

O erro mais comum é tratar aprovação humana como uma notificação: o agente executa a ação e avisa alguém. Isso é informação, não aprovação. Aprovação de verdade significa que o fluxo para antes da ação, guarda tudo o que sabe, espera uma resposta e só então continua.

Segundo a documentação do LangGraph, isso é feito com um mecanismo de interrupção: o nó pausa a execução, o estado é salvo por um checkpointer, e o fluxo é retomado depois com a decisão da pessoa, identificando a execução por um identificador de conversa (thread). Para que funcione, o grafo precisa ser compilado com um mecanismo de persistência. Sem ele, não há onde guardar o estado durante a pausa.

Um desenho útil de ponto de aprovação tem quatro elementos:

• o que será feito, descrito em linguagem clara (enviar esta proposta, reembolsar este valor, alterar este cadastro);
• os dados que sustentam a ação, para a pessoa não decidir às cegas;
• as opções disponíveis: aprovar, rejeitar com motivo ou editar antes de seguir;
• um prazo e um responsável, com regra para o que acontece se ninguém responder.

Quais ações exigem esse ponto é uma decisão de negócio, não técnica. Ações irreversíveis, que movimentam dinheiro, que alteram dados de clientes ou que comunicam compromissos em nome da empresa são candidatas naturais. Quando a decisão afeta diretamente uma pessoa, vale conferir também o direito de revisão previsto na LGPD para decisões automatizadas.

O que a persistência guarda e que cuidados ela exige?

Persistência significa que o estado do fluxo é gravado em pontos da execução (checkpoints) em um armazenamento que você escolhe. Os benefícios são concretos: retomar após uma queda, pausar por tempo indeterminado, inspecionar o que aconteceu e, conforme a documentação, até voltar a um ponto anterior para reexecutar a partir dali.

Mas persistir também cria obrigações. Três cuidados merecem atenção desde o início:

• Dados pessoais no estado: se o estado carrega nome, telefone, endereço ou conteúdo de conversa, ele passa a ser uma base de dados sob a LGPD. Guarde apenas o necessário, defina por quanto tempo, controle quem acessa e verifique onde o armazenamento fica. Se houver provedores fora do Brasil, veja o artigo sobre transferência internacional de dados com IA.
• Efeitos repetidos: ao retomar, o nó que estava pausado pode ser executado de novo desde o início (confirme esse comportamento na versão que você usar). Se esse nó envia uma mensagem ou cria um pedido antes da pausa, o resultado pode ser duplicado. Separe a decisão da ação, coloque a ação depois da aprovação e use chaves de idempotência quando o sistema de destino aceitar, como descreve a documentação da Stripe sobre requisições idempotentes.
• Mudança de versão: um fluxo pausado hoje pode ser retomado depois de uma alteração no grafo. Decida de antemão como tratar execuções antigas: concluir com a versão anterior, migrar ou descartar.

Observação e persistência são coisas diferentes. Checkpoints servem para retomar o fluxo, e logs e rastros servem para entender o comportamento. Para essa segunda parte, o primer de observabilidade do OpenTelemetry explica os conceitos de traces, métricas e logs que você vai querer ter também.

Cenário ilustrativo: proposta com aprovação antes do envio

Este é um cenário ilustrativo, sem relação com nenhuma empresa real. Uma empresa de serviços recebe pedidos de orçamento por WhatsApp. O agente precisa coletar informações, consultar a tabela interna, montar um rascunho de proposta e enviá-la, mas nenhuma proposta pode sair sem revisão de uma pessoa da equipe comercial.

Como grafo, o fluxo ficaria assim:

• Nó de coleta: o agente pergunta o que falta e atualiza o estado. Se faltar informação, volta a perguntar, com limite de tentativas.
• Nó de consulta: busca os valores de referência nos sistemas internos e registra a origem de cada dado no estado.
• Nó de rascunho: gera a proposta e as premissas usadas.
• Ponto de aprovação: o fluxo pausa. A pessoa do comercial vê o rascunho e os dados, e escolhe aprovar, editar ou rejeitar com motivo.
• Nó de envio: só executa após aprovação, com chave de idempotência para não enviar duas vezes.
• Nó de registro: grava a decisão, quem decidiu e quando.

A pausa pode durar a noite inteira ou o fim de semana. Sem persistência, o processo precisaria manter tudo em memória ou reconstruir o contexto a cada vez. Com o estado salvo, a retomada continua exatamente do ponto de aprovação. Se, em vez disso, o fluxo fosse apenas responder com uma tabela fixa de valores, um fluxo simples bastaria. Para exemplos de processos parecidos em setores específicos, veja como a mesma lógica aparece em IA para empresas de energia solar, com propostas e pós-venda.

Como aplicar o método: mapear, limitar, pilotar, transferir

O método que usamos para projetos de IA se encaixa bem na decisão sobre o grafo, e ajuda a evitar adotar a ferramenta antes de entender o processo.

• Mapear: desenhe o processo atual, com as exceções reais, e registre uma linha de base (tempo de ciclo, retrabalho, quem decide o quê). Se o desenho for uma linha reta, você provavelmente não precisa de grafo.
• Limitar: defina quais dados o agente vê, quais ações pode executar sozinho e quais exigem aprovação. O desenho dos pontos de aprovação nasce aqui.
• Pilotar: implemente um único fluxo real, com logs e uma métrica de sucesso combinada de antemão. Se o piloto mostrar que o caminho é quase sempre linear, simplifique.
• Transferir: entregue com documentação, acessos e critérios claros para decidir se vale expandir, ajustar ou parar.

Tudo isso separa três tipos de afirmação: o que está na documentação oficial, o que vem de experiência de implementação e o que ainda é hipótese a ser testada no seu piloto. Este artigo trata o comportamento de interrupção e persistência como documentação, e a recomendação de começar simples como orientação de fontes primárias que você deve validar no seu contexto.

Que riscos o grafo não resolve sozinho?

Um grafo organiza o fluxo, mas não torna o agente seguro por si só. Três riscos continuam com você.

• Permissões: cada nó deve ter acesso mínimo às ferramentas e aos dados. O grafo não decide isso, a sua configuração decide.
• Conteúdo hostil: texto vindo de clientes ou de documentos pode tentar manipular o agente. Veja o artigo sobre prompt injection em agente de IA para as defesas básicas.
• Qualidade das respostas: um fluxo bem desenhado ainda pode produzir respostas ruins. Avalie com casos reais e revise amostras com regularidade.

A Anthropic também publica material sobre agentes de longa duração, que lida justamente com o desafio de manter progresso e contexto entre várias sessões de trabalho. Vale a leitura para quem pretende operar fluxos que se estendem no tempo.

Perguntas frequentes

LangGraph serve só para quem usa LangChain? A documentação apresenta o LangGraph como uma biblioteca de orquestração de agentes com estado, e é comum vê-lo junto de outros componentes do ecossistema. Antes de decidir, confirme na documentação da versão atual quais dependências são necessárias e quais modelos e provedores você pode usar.

Preciso de LangGraph para ter aprovação humana no agente? Não necessariamente. Você pode implementar aprovação com código próprio, uma fila e um banco de dados, ou com uma ferramenta de automação que tenha etapa de espera. O grafo ajuda quando a pausa precisa preservar um estado complexo e o fluxo pode ter vários pontos de aprovação e ramificações.

Quando devo migrar de um fluxo simples para um grafo? Migre quando o fluxo simples começar a acumular remendos: contornos para repetições, tabelas improvisadas de status, dificuldade de retomar após falhas e dúvidas sobre o que o agente sabia em cada decisão. Se esses sintomas não aparecem, a migração só adiciona custo de manutenção.

Quem deve manter o grafo depois da entrega? Defina isso no início do projeto. Alguém da empresa ou um parceiro precisa ser responsável por atualizar versões, revisar logs, ajustar pontos de aprovação e decidir quando expandir. Sem responsável claro, o fluxo envelhece e as aprovações viram formalidade.

Fontes

• Anthropic: Building effective agents
• Anthropic: Effective harnesses for long-running agents
• OpenTelemetry: observability concepts
• Stripe: an example of provider-defined idempotency