LangGraph aprende a sobreviver a falhas: retentativas, timeouts e tratadores de erro para agentes em produção

A LangChain publicou um guia detalhado sobre os três primitivos de tolerância a falhas embutidos no LangGraph. Sem eles, qualquer agente em produção inevitavelmente quebra justamente onde o protótipo funcionava como um relógio.

Por que protótipos quebram em produção

No laboratório, um agente LangGraph parece confiável: os dados de entrada são fixos, as APIs externas respondem rápido e o usuário está sempre disponível. Na operação real, o quadro é outro. Serviços externos travam ou retornam 503 sob carga. Provedores de LLM atrasam respostas por minutos nos picos de demanda. Em cenários human-in-the-loop, uma pessoa pode demorar horas para responder. Sem tratamento específico, cada um desses casos vira um agente travado ou derrubado.

A solução clássica é envolver cada chamada em try/except, escrever timers e adicionar lógica de retentativa manualmente. Funciona, mas o código defensivo cresce, se mistura à lógica de negócio e vira ele próprio fonte de erros. O LangGraph propõe outra abordagem: três primitivos embutidos no motor, com funcionamento declarativo.

RetryPolicy: retentativas automáticas

O RetryPolicy configura retentativas automáticas com backoff exponencial. Os parâmetros ajustáveis são o número máximo de tentativas, o atraso inicial, o atraso máximo e o fator de crescimento entre as tentativas.

A política pode ser definida de forma pontual, para um nó específico que chama uma API externa instável, ou aplicada a todo o grafo como padrão global. A segunda opção é conveniente quando toda a interação com serviços externos deve seguir as mesmas regras de recuperação.

TimeoutPolicy: limites de tempo

O TimeoutPolicy resolve outro problema: limita o tempo que um nó pode ocupar. Há suporte a dois tipos de limite:

• `wall_clock_timeout`: o tempo máximo de execução de um nó, em tempo real, do início ao fim
• `idle_timeout`: o tempo máximo de inatividade. É especialmente importante em cenários human-in-the-loop: se o usuário não respondeu em N minutos, o agente deve seguir por um ramo alternativo ou terminar com erro
• Os dois limites podem ser combinados na mesma política, e vale o que ocorrer primeiro
• Ao exceder o limite, o motor lança uma exceção automaticamente
• A política pode ser aplicada a um nó, a um subgrafo ou a todo o grafo

A principal vantagem dos dois primitivos é que eles vivem dentro do motor e enxergam o contexto completo do estado do grafo. Decoradores e wrappers externos não conseguem isso.

error_handler e o padrão SAGA

O error_handler é o terceiro primitivo e é acionado depois que todas as retentativas se esgotam. É o ponto final de recuperação: desfazer ações já executadas, enviar notificações, salvar diagnósticos e levar o agente a um estado seguro.

Para agentes de várias etapas com efeitos colaterais reais, como reservar recursos, debitar valores ou criar registros em sistemas externos, a LangChain recomenda o padrão SAGA. A ideia é que cada etapa do agente venha acompanhada de uma operação compensatória que desfaz o seu efeito. Se a etapa N falhar depois de as etapas de 1 a N-1 terem sido concluídas com sucesso, as operações compensatórias rodam em ordem inversa, e o sistema volta a um estado consistente. O LangGraph permite embutir o SAGA diretamente no grafo: as compensações ficam guardadas junto aos nós, e o error_handler dispara a cadeia delas em caso de falha.

"Ter políticas de tolerância a falhas dentro do motor, e não fora dele, é uma diferença fundamental: a lógica de recuperação recebe o contexto completo do estado do grafo", diz o blog da

LangChain.

O que isso significa

O LangGraph oferece ferramentas maduras para levar agentes de IA do protótipo à operação real. Retentativas, timeouts e transações compensatórias estão embutidos no motor e não exigem envolver cada nó manualmente. Para equipes que constroem agentes para cargas de produção, isso reduz o volume de código defensivo e torna o comportamento diante de falhas previsível e controlável.