Execução durável para agentes de IA: fila ou workflow?

A recuperação de um agente não começa no modelo. Começa no lugar onde o sistema grava o progresso, reconhece o que já aconteceu e decide se uma etapa pode ser repetida. Sem essa camada, um reinício transforma trabalho concluído em contexto perdido e uma chamada externa parcialmente aplicada em risco de duplicação.

Execução durável é o contrato que permite a um agente pausar, falhar, esperar aprovação e continuar a partir de um estado confirmado. Um checkpoint, uma fila e um workflow ajudam a cumprir esse contrato, mas não são a mesma coisa. A escolha depende da unidade de trabalho, do tipo de efeito externo e da recuperação que a equipe precisa operar.

Decisão rápida

• Use apenas um loop em processo para trabalho curto, reversível e que pode começar de novo sem consequência.
• Adicione checkpoint e fila quando cada unidade de trabalho tiver identificador, estado persistido e uma etapa que possa ser retomada.
• Use uma máquina de estados ou um workflow quando houver espera, sinais, compensação, fan-out, replay ou auditoria da execução.
• Trate cada escrita externa como potencialmente aplicada até que o sistema confirme o contrário.

O que a execução durável precisa garantir?

Execução durável significa que o progresso de uma tarefa sobrevive ao processo que a iniciou. A documentação do Temporal Workflow descreve esse princípio com histórico de eventos e replay: o workflow reconstrói seu estado a partir do que já foi registrado, enquanto chamadas externas ficam em Activities e não são refeitas durante o replay.

Para um agente, esse contrato precisa responder a algumas perguntas práticas. Qual é o estado confirmado? Qual etapa está em andamento? O que pode ser repetido sem duplicar efeito? Qual evidência permite continuar ou pedir ajuda humana? A conversa com o modelo pode fazer parte do estado, mas não deve ser o único lugar onde essas respostas existem.

Uma execução recuperável não é apenas uma sessão que conserva mensagens. Ela também registra decisões, resultados de ferramentas, transições, tentativas e efeitos externos. Se o processo cai depois de enviar uma solicitação, o sistema precisa descobrir se deve consultar o estado, aguardar uma confirmação ou executar uma ação compensatória.

Esse desenho muda o papel do agente. O modelo sugere a próxima ação e pode explicar um resultado. O runtime confirma a transição, aplica limites de retry e decide se a tarefa está done, failed ou needs-human.

Checkpoint, fila ou workflow: qual camada resolve o problema?

As três camadas resolvem falhas em níveis diferentes. Checkpoint persiste progresso. Fila entrega trabalho a um consumidor e permite que o processo seja substituído. Workflow organiza transições, espera, sinais, retries e histórico de uma execução que pode durar mais que um processo.

O erro é escolher pelo nome da ferramenta. Comece pelo que precisa ser provado. Se a tarefa só precisa lembrar que o passo de leitura terminou, um checkpoint pode ser suficiente. Se várias tarefas chegam de forma independente, uma fila cria uma fronteira operacional clara. Se o agente precisa esperar uma aprovação e continuar no ponto certo sem perder os efeitos anteriores, o estado do fluxo precisa ser explícito.

Quando uma fila com checkpoint é suficiente?

Uma fila com checkpoint atende bem um agente que processa tarefas independentes, com etapas curtas e um estado que cabe em um registro. O worker recebe um taskId, carrega a última etapa confirmada, executa uma ação, grava o resultado e libera a tarefa. Outro worker pode continuar depois de uma queda.

O contrato mínimo pode ser pequeno e tipado:

type RunState = "queued" | "running" | "waiting" | "done" | "failed" | "needs-human";

type AgentRun = {
  id: string;
  state: RunState;
  step: string;
  checkpoint: string | null;
  lastEvidence: string | null;
  idempotencyKey: string;
};

type RunStore = {
  load(id: string): Promise<AgentRun>;
  save(run: AgentRun): Promise<void>;
};

O ponto importante não é o tipo em si. É fazer a transição ser uma operação persistente, observável e condicionada ao estado anterior. Um worker não deve trocar running por done apenas porque o modelo respondeu. Deve salvar a evidência que confirma o resultado esperado.

O lease da fila também precisa ter uma política. Se o worker desaparece, outro pode assumir a tarefa depois de um timeout. Se o primeiro ainda estiver vivo, os dois podem tentar a mesma etapa. Por isso, o armazenamento deve aceitar a atualização apenas quando o lease e o checkpoint esperados ainda forem válidos.

Esse padrão é adequado para consumidores de fila, jobs de avaliação, processamento de arquivos e tarefas de coding agents que produzem um artefato isolado. Ele fica mais difícil de manter quando cada etapa dispara sinais, espera respostas externas, cria subagentes ou exige compensação em mais de um sistema.

Quando uma máquina de estados torna o agente mais seguro?

Uma máquina de estados deixa explícito o que o agente pode fazer em cada fase. O modelo pode classificar um evento ou sugerir uma ação, mas o código decide se a transição é permitida. Isso evita que uma resposta plausível pule a autorização, marque uma tarefa como concluída antes da verificação ou repita uma escrita já confirmada.

Um fluxo simples pode separar proposta, autorização, execução, confirmação e verificação:

const transitions: Record<RunState, RunState[]> = {
  queued: ["running"],
  running: ["waiting", "done", "failed", "needs-human"],
  waiting: ["running", "failed", "needs-human"],
  done: [],
  failed: ["queued", "needs-human"],
  "needs-human": ["queued", "failed"],
};

function canMove(from: RunState, to: RunState) {
  return transitions[from].includes(to);
}

O exemplo não executa o agente. Ele limita o espaço de decisões do runtime. A implementação ainda precisa persistir a mudança, conferir concorrência e registrar a razão da transição. Uma state machine sem armazenamento durável continua perdendo o lugar quando o processo cai.

Essa camada é especialmente útil para agentes que acessam APIs com permissão, alteram dados, esperam aprovação humana ou coordenam subagentes. O post sobre orquestração multiagente com TypeScript explora supervisor, dependências e recuperação; aqui, a pergunta é qual contrato mantém o fluxo inteiro recuperável.

O que muda em um coding agent?

Imagine um coding agent que recebe uma issue, inspeciona o repositório, altera arquivos e executa a verificação do patch. Se o worker cai depois de escrever o diff, a retomada não deve começar pela leitura de toda a codebase. Ela deve carregar o estado da tarefa, o commit de referência, os arquivos alterados e o último comando confirmado.

Se a verificação ainda não terminou, o runtime pode iniciar essa etapa de novo. Se o commit já foi criado, a etapa de escrita não deve ser repetida sem conferir o estado do repositório. Se o teste falhou, o agente pode receber o log e a hipótese de correção, mas o sistema continua marcando a execução como incompleta até uma nova prova passar.

Esse desenho conecta execução durável ao loop que devolve falhas do CI para o agente. O agente corrige uma hipótese por vez; o runtime conserva o histórico e limita o caminho de recuperação. Assim, uma sessão interrompida não apaga o trabalho confirmado nem transforma a conversa em fonte única de verdade.

Quando um workflow dedicado compensa?

Um workflow dedicado compensa quando o sistema precisa tratar a execução como uma entidade de longa duração. A tarefa pode esperar um sinal, retomar depois de uma implantação, executar branches em paralelo, aplicar compensação ou manter um histórico que outra pessoa consiga inspecionar.

O AWS Step Functions modela workflows como máquinas de estados com transições, estados de espera, escolhas, mapas e branches paralelos. A documentação de tratamento de erros separa Retry de Catch, o que ajuda a tornar a recuperação uma propriedade declarada do fluxo.

O Temporal usa histórico de eventos e replay para reconstruir o estado do workflow. Sua documentação de Retry Policy recomenda concentrar falhas de operações externas em Activities, onde a política de retry pode distinguir falhas temporárias de erros que não devem ser repetidos.

O LangGraph documenta checkpoints como snapshots do estado do grafo e preserva pending writes quando um nó falha enquanto outros completam. A documentação de persistência também alerta que armazenamento apenas em memória perde checkpoints depois de um restart e que histórico sem retenção pode crescer sem limite.

Essas ferramentas não eliminam as decisões de domínio. Um workflow pode repetir uma Activity, mas não sabe sozinho se uma cobrança foi aplicada antes do timeout. Um checkpoint pode restaurar o estado do grafo, mas não autoriza uma ferramenta. A camada durável guarda o que o sistema sabe; o código de negócio decide o que pode acontecer depois.

Retry não é retomada

Retry significa tentar novamente uma operação que falhou. Retomada significa continuar uma execução a partir do último estado confirmado. Às vezes as duas coisas coincidem. Muitas vezes, não.

Uma leitura idempotente pode ser repetida com baixo risco. Uma escrita externa precisa de uma chave de idempotência, de uma consulta de confirmação ou de uma operação de compensação. Imagine que o timeout aconteça depois que o provedor recebeu a requisição. O erro local não prova que nada foi aplicado.

O fluxo deve guardar a fronteira entre intenção e efeito. Antes da execução, registre a intenção e a chave. Depois, registre a resposta ou o estado observado. Na retomada, consulte essa evidência antes de chamar a ferramenta outra vez. O agente pode ajudar a interpretar a resposta, mas não deve inventar a confirmação.

O mesmo princípio vale para uma chamada de modelo. Se uma etapa gera um plano e falha ao gravar o resultado, repetir a chamada pode produzir outra saída. Decida se o plano é um artefato que precisa de deduplicação, se pode ser regenerado ou se deve voltar para revisão humana.

Como verificar que a arquitetura realmente retoma?

O teste mais útil interrompe o sistema nos pontos em que uma demonstração costuma esconder o risco. Não basta iniciar o worker e observar uma resposta final. A prova precisa verificar a história da execução.

1. Inicie uma tarefa com identificador e registre o primeiro checkpoint.
2. Interrompa o processo depois de uma ferramenta retornar, antes de a próxima transição ser salva.
3. Reinicie outro worker e confira qual estado ele carrega.
4. Verifique que a etapa confirmada não foi executada outra vez sem uma justificativa de idempotência.
5. Force uma resposta lenta, uma falha permanente e um timeout para confirmar políticas diferentes.
6. Pause a tarefa esperando aprovação e retome-a depois, sem manter o processo original vivo.
7. Inspecione a evidência final, o estado terminal e o caminho que levou até ele.

Para coding agents, acrescente o commit, o diff, os testes e o artefato produzido ao registro da execução. Um agente pode dizer que terminou uma mudança. O sistema precisa mostrar qual arquivo foi alterado, qual verificação passou e qual risco continua aberto. Observabilidade de agentes de código no CI trata dessa evidência no pipeline.

O contexto também afeta a recuperação?

Retomar não significa carregar toda a conversa antiga de volta para o prompt. O sistema deve persistir estado compacto, resultados de ferramentas e referências aos artefatos. Na retomada, ele recupera apenas o contexto necessário para a próxima transição.

Em execuções longas, o RemoteCode ajuda Claude Code e Codex a continuar fluxos agentic com menos repetição de contexto. A ferramenta é do próprio autor e aparece aqui como uma opção para reduzir contexto reenviado entre sessões. Ela não substitui checkpoint, autorização, idempotência ou verificação do resultado.

Essa separação evita dois desperdícios. O sistema não paga novamente para o modelo reler tudo o que já foi confirmado, e o agente não recebe um histórico tão grande que esconda o estado atual. O checkpoint guarda progresso; o mecanismo de recuperação monta a projeção que a próxima etapa precisa.

Erros comuns e limites da decisão

Chamar qualquer persistência de execução durável é um começo ruim. Salvar mensagens em um banco não define transições, não detecta worker abandonado e não evita que uma ferramenta seja repetida. O armazenamento precisa carregar estado suficiente para decidir o próximo passo.

Também é fácil colocar o retry dentro do loop do agente e deixar o runtime sem visibilidade. Um retry sem limite pode consumir contexto, repetir chamadas caras e esconder um erro permanente. A política precisa estar fora da decisão livre do modelo.

Escolher um workflow porque o diagrama parece mais completo cria outro problema. Se a tarefa é uma leitura curta, uma fila simples ou uma chamada síncrona pode ser mais fácil de operar. O workflow deve pagar seu custo quando espera, ramifica, compensa ou precisa de histórico confiável.

Por fim, checkpoint não é memória de longo prazo. Checkpoint mantém o estado de uma execução. Memória persistente guarda fatos que atravessam execuções. São camadas relacionadas, mas têm retenção, autorização e testes diferentes.

Perguntas frequentes sobre execução durável para agentes de IA

Todo agente de IA precisa de um workflow durável?

Não. Um agente curto, sem efeitos irreversíveis e executado dentro de uma requisição pode começar com um loop simples. A necessidade aparece quando o trabalho precisa sobreviver a restart, esperar uma pessoa, consumir uma fila, repetir uma etapa com segurança ou provar o que aconteceu. Nesse ponto, persista o estado antes de escolher o produto.

Checkpoint é a mesma coisa que retry?

Não. Checkpoint registra onde a execução está e quais resultados foram confirmados. Retry tenta novamente uma operação que falhou. Para retomar com segurança, o runtime deve carregar o checkpoint e decidir se a etapa falha, continua ou primeiro consulta um efeito externo possivelmente aplicado.

Como evitar que um retry duplique uma chamada externa?

Use uma chave de idempotência quando o provedor suportar esse mecanismo. Também registre a intenção, consulte o estado da operação antes de repetir e trate timeout como estado desconhecido até obter confirmação. O agente não deve marcar a ação como concluída apenas porque a chamada foi enviada.

Uma fila substitui Temporal, Step Functions ou LangGraph?

Às vezes. Uma fila com estado persistido pode ser suficiente para tarefas independentes e etapas curtas. Ela não entrega automaticamente sinais, replay, espera humana, transições válidas, compensação ou histórico de um workflow. Compare o contrato que você precisa operar, não a quantidade de componentes da arquitetura.

Onde o estado do agente deve ficar?

Fora da memória do processo. Use um armazenamento que registre identificador da tarefa, estado, etapa, checkpoint, evidência e chave de idempotência. A conversa e os resultados do modelo podem ser referências nesse registro, mas a aplicação deve conseguir decidir o próximo passo mesmo depois que o worker original desapareceu.

Fontes consultadas

• Temporal Workflow
• Temporal Retry Policy
• AWS Step Functions: state machines
• AWS Step Functions: error handling
• LangGraph checkpoints
• LangGraph persistence