Agente da orquestração falhou no meio: como retomar sem refazer tudo

Fala aí, beleza? Orquestração longa que nunca falha no meio não existe, o que existe é orquestração que sabe voltar

O cenário é sempre o mesmo: você dispara o fluxo, vários agentes rodando em paralelo, vinte minutos de trabalho acumulado… e uma etapa morre

Aí vem a pergunta que dói: refaz tudo?

A resposta honesta é que falha de agente no meio é rotina, não exceção, e o conserto vem em três camadas: retentativa pro erro passageiro, estado salvo por etapa e retomada só do que faltou

Bora destrinchar cada uma 🙂

Qual falha você teve? 529, 429, erro no stream ou etapa quebrada

Antes de mexer em configuração, triagem

O conserto muda COMPLETAMENTE conforme a causa, e a maioria das pessoas configura retentativa em cima de um erro que nunca vai passar por repetição

• 529: é o overloaded_error da API da Anthropic, ou seja, a API está temporariamente sobrecarregada. Aqui retentar faz sentido, é literalmente o caso de uso
• 429: é rate_limit_error, o limite da SUA conta. Repetir rápido não resolve, o que resolve é espaçar as chamadas
• overloaded_error dentro do stream: quando a resposta vem por streaming, a sobrecarga chega como um evento de erro no meio do stream, equivalente ao 529 do modo não streaming
• erro determinístico: ValueError, TypeError, SyntaxError e companhia. Isso não é sobrecarga, é bug. Repetir dez vezes dá o mesmo resultado dez vezes

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

Essa distinção não é teórica: a política padrão de retentativa do LangGraph repete erro de conexão e HTTP 5xx, e NÃO repete ValueError, TypeError, SyntaxError e similares

Ou seja, o próprio framework já assume que retentativa é remédio pra erro transitório, não pra código quebrado

E o 429 tem um detalhe prático: se você usa n8n, o campo que segura o limite é o tempo de espera entre tentativas, e ele precisa ser MAIOR que a janela do limite. Pra um limite de 1 requisição por segundo, isso significa 1000 ms de espera

Como prevenir: trate a etapa como retomável desde o início

O erro clássico aqui é descobrir que o fluxo não é retomável na hora em que ele quebra

Aí já era: o trabalho estava só na memória do processo

Prevenir é decidir ANTES onde o estado é gravado, mesmo que a primeira versão do fluxo nunca falhe. É o mesmo raciocínio de segurar o agente antes da edição: você paga um custo pequeno de planejamento pra não pagar um custo grande de retrabalho

E não confie só na camada do SDK. Existe uma issue aberta no repositório do Claude Code relatando exatamente isso: erros 529 transitórios abortando tarefas longas sem recuperação automática

Sinal claro de que a camada de aplicação também precisa da própria rede de proteção

O que você precisa antes de configurar a retomada

Checklist curto, e honesto no que ele não resolve:

1. Etapas com fronteira clara

Uma unidade de trabalho por nó, por agente, por passo

Se uma etapa faz três coisas diferentes, você só consegue retomar as três juntas. Retomada boa nasce de granularidade boa, e granularidade nasce de saber a diferença entre subagentes e comandos na hora de fatiar o fluxo

2. Um lugar pra gravar estado

Sem isso não existe retomada, existe só recomeço

• LangGraph: um checkpointer
• Claude Agent SDK: a sessão gravada em disco automaticamente
• OpenAI Agents SDK: o protocolo Session (a implementação padrão em Python usa SQLite)

3. A decisão de durabilidade

Essa é a que quase ninguém toma conscientemente

O LangGraph tem três modos que definem QUANDO o estado é gravado:

Não existe escolha certa universal aqui

Existe a pergunta: perder um passo dói mais que o custo de gravar antes de cada passo? Se dói, sync

Passo a passo: da retentativa automática à retomada do que faltou

1. Deixe o SDK cuidar do transitório

Os SDKs oficiais da Anthropic já refazem sozinhos as falhas transitórias (erro de conexão, rate limit e erros 5xx) com backoff exponencial, duas vezes por padrão, e respeitando o header retry-after quando ele vem na resposta

O erro comum deste passo: empilhar retry em cima de retry

Você põe a sua retentativa por fora, o SDK já tem a dele por dentro, e o número real de tentativas vira uma multiplicação que você não controla. Antes de escrever qualquer loop, saiba o que a camada de baixo já faz

2. Política de retentativa por etapa, não global

No LangGraph a retentativa é configurada POR NÓ, no add_node:

builder.add_node("call_api", call_api, retry_policy=RetryPolicy(max_attempts=3))

Os padrões do RetryPolicy são estes:

initial_interval = 0.5s
backoff_factor   = 2.0
max_interval     = 128.0s
max_attempts     = 3

Repare no detalhe: max_attempts conta a PRIMEIRA tentativa

Então 3 não é "uma chamada mais três repetições", é três chamadas no total. Já vi gente dimensionar orçamento de chamada errado por causa disso

O erro comum deste passo: esperar que a política repita erro determinístico

Ela não repete, e isso é uma decisão de projeto, não uma limitação. Se o seu nó estoura ValueError, o conserto é no nó

3. Ligue o checkpointer e organize por thread

Com um checkpointer, o LangGraph salva o estado do grafo a cada superstep e organiza as execuções por thread

É isso que permite voltar do último ponto salvo em vez de voltar do início

E é aqui que a decisão de durabilidade do bloco anterior encosta na realidade: se você ficou no exit, não existe ponto salvo no meio pra voltar. O checkpoint só existe onde você mandou gravar

4. Retome

No Claude Agent SDK a sessão inteira (prompt, chamadas de ferramenta, resultados e respostas) é persistida em disco automaticamente, e o query() tem os campos de opção continue e resume pra voltar nela

// opções do query()
{ resume: sessionId, forkSession: true }

O forkSession (ou fork_session, no Python) é o irmão esperto do resume: em vez de continuar a mesma linha, ele cria um NOVO id de sessão partindo do estado retomado, com cópia do histórico

Muito massa pra quando você quer testar dois caminhos a partir do mesmo ponto de falha, sem destruir o original

No n8n, o caminho é outro: a retentativa mora dentro do painel Settings do próprio nó, com Retry On Fail ligado e os campos Max Tries e Wait Between Tries (em ms)

O erro comum do passo de retomada: no OpenAI Agents SDK, Sessions não pode ser combinada com conversation_id, previous_response_id ou auto_previous_response_id no mesmo run

São dois modelos de persistência mutuamente exclusivos, e misturar os dois não te dá o dobro de segurança, te dá um conflito

Como cada orquestrador retoma na prática (e onde cada um corta)

Retomar é fácil de prometer

O que separa as ferramentas é quanto trabalho volta de graça, e onde exatamente o cache para

Claude Code dynamic workflows

Um run parado pode ser retomado, e os agentes já concluídos costumam devolver o resultado em cache enquanto o resto roda ao vivo

A retomada é feita pela tela /workflows: você seleciona o run e aperta p, ou simplesmente pede pro Claude relançar o workflow com o mesmo script

Só que essa retomada tem UMA condição que você precisa saber antes de contar com ela: ela vale dentro da MESMA sessão. Se você sair do Claude Code com um workflow rodando, a próxima sessão começa o workflow do zero

Ou seja, o /workflows te devolve o run enquanto a sessão está de pé, não pra sempre

Agora se liga na regra de corte, porque ela é o detalhe que muda tudo:

• agente que ainda estava RODANDO quando você parou não é salvo e recomeça
• o cache para no primeiro agente que não terminou
• todo agente iniciado depois dele roda de novo, mesmo tendo concluído

Ou seja: não é "tudo que terminou volta do cache", é "tudo que terminou ANTES do primeiro incompleto volta do cache"

Existe também uma issue aberta relatando re-execução de agentes concluídos em vez do uso do cache do journal, então vale acompanhar antes de apostar todas as fichas no reaproveitamento

Claude Agent SDK

Aqui o modelo é de sessão, não de grafo

A sessão é gravada em disco automaticamente e você volta nela com continue ou resume, ou bifurca com forkSession / fork_session pra criar um novo id partindo do mesmo estado

Simples e previsível: o que a sessão registrou é o que você recupera

LangGraph

Checkpoint a cada superstep, organizado por thread

O detalhe legal é que esse mesmo mecanismo não serve só pra recuperação de falha: ele é a base do histórico de estado e do human-in-the-loop

Faz sentido, né? Pausar pra um humano decidir e pausar porque a API caiu são o mesmo problema técnico visto de dois ângulos

OpenAI Agents SDK

Três caminhos distintos de persistência entre execuções:

1. gestão manual, com RunResult.to_input_list()
2. persistência automática, via protocolo Session
3. estado no servidor, via conversation_id / previous_response_id

A implementação padrão de sessão em Python usa SQLite, e aqui mora uma pegadinha: em memória, o histórico morre quando o processo termina. Em arquivo, ele persiste

Se você configurou em memória e reiniciou o processo pra tentar de novo, não tem retomada nenhuma pra fazer

Na versão TypeScript dá pra retomar a partir de um RunState interrompido, e o novo turno é anexado ao mesmo registro de memória. Em execuções locais com sessão, a SDK faz um rollback best-effort dos itens recém-persistidos pra reduzir entradas duplicadas depois de um retry

Repare no "best-effort": é redução de duplicata, não garantia

n8n

O que a documentação do n8n cobre nesse ponto é a retentativa POR NÓ, e ela mora no painel Settings do próprio nó

Você liga o Retry On Fail e define Max Tries e Wait Between Tries (em ms)

E lembra do 429 lá do começo? É aqui que ele volta: o Wait Between Tries precisa ser MAIOR que a janela do limite, senão você só repete o mesmo estouro mais rápido. Pra 1 requisição por segundo, 1000 ms

Temporal

O modelo de execução durável é o mais radical dos cinco

No replay, chamadas de LLM e invocações de ferramenta já concluídas não são re-executadas: os resultados voltam do histórico de eventos

É a diferença entre "eu guardei o resultado da etapa" e "eu guardei a linha do tempo inteira da execução"

Conclusão

Resumindo o que faz o quê, porque cada camada resolve um problema diferente e trocar uma pela outra é o erro mais caro aqui:

• retentativa resolve o transitório (529, conexão, 5xx)
• checkpoint resolve o processo que cai
• retomada só compensa de verdade se você souber a regra de corte do SEU orquestrador

E essa última é a que mais engana: dá pra ter checkpoint configurado, retomar o run e mesmo assim ver metade dos agentes rodando de novo, porque o corte do cache não era onde você imaginava

Próximo passo concreto pra fechar: identifique a etapa mais cara do seu fluxo, aquela que gasta mais tempo e mais token

Grave o estado ANTES dela

E faça uma parada proposital, de propósito mesmo, só pra ver com os próprios olhos quanto volta do cache e quanto roda de novo

Melhor descobrir isso num teste do que às 2h da manhã com o fluxo de produção pela metade 😀

até o próximo post!