Como recuperar agentes de IA após uma falha sem duplicar efeitos
Imagem gerada pela Equipa Editorial da Inferama
01

Uma falha nem sempre significa que a ação não aconteceu

Um agente de IA pode ser interrompido depois de enviar uma solicitação a uma ferramenta e antes de salvar a resposta. Nesse intervalo, o sistema externo talvez já tenha criado um chamado, enviado uma mensagem ou alterado um registro. Perder a resposta não prova que o efeito falhou. Se o agente reiniciado repetir a ação sem verificá-la, poderá duplicar a alteração.

Por isso, convém distinguir o estado do processo do estado da operação externa. Uma falha de infraestrutura pode interromper a comunicação; uma falha de lógica pode produzir uma decisão inadequada; e uma ferramenta pode rejeitar uma entrada ou responder com atraso. São causas diferentes e não justificam automaticamente a mesma forma de recuperação.

O histórico da conversa e os registros de execução ajudam a reconstruir o que aconteceu, mas não necessariamente comprovam que o sistema de destino aplicou — ou deixou de aplicar — uma alteração. O identificador da operação devolvido por esse sistema, uma consulta de estado confiável ou um comprovante persistido oferecem uma base melhor para decidir se o fluxo pode continuar.

Uma execução durável conserva, fora do processo, a intenção, as etapas confirmadas e os resultados necessários para retomar o fluxo. Se o processo morrer, um novo worker poderá partir do último checkpoint confirmado, em vez de pedir ao modelo que escolha o plano novamente. Retomar é continuar a partir de um estado conhecido; tentar de novo é repetir uma operação específica.

02

Que estado preservar e como classificá-lo

Salve o necessário para recuperar a execução sem depender da memória temporária do worker. No mínimo, registre o identificador da execução, a versão do fluxo, a decisão que originou a chamada, os argumentos normalizados, a identidade estável da operação e o resultado ou comprovante do provedor. Se o sistema externo devolver um identificador, preserve também esse dado.

A decisão do modelo deve ser persistida antes da execução da ferramenta. Depois, cada resultado deve ser salvo antes do início da etapa seguinte. Assim, uma reinicialização não precisa gerar o plano novamente e pode distinguir uma chamada pendente de uma operação confirmada. Um checkpoint registra estado durável, mas não garante que uma API externa tenha aplicado suas alterações de forma atômica.

O estado `unknown` é útil quando a resposta se perdeu ou o processo caiu entre o efeito externo e o registro local. Ele não equivale a `failed`: indica que ainda é preciso descobrir o que aconteceu. Uma consulta ao provedor pode confirmar ou negar a operação; se não houver uma consulta confiável e uma nova tentativa trouxer risco, o caso deve continuar pendente de reconciliação.

A compatibilidade também importa. Um checkpoint antigo pode perder o sentido se a definição das ferramentas ou as regras do fluxo mudarem. Associe cada execução a uma versão compatível e rejeite gravações atrasadas por meio de controle de concorrência. Em implantações com workers concorrentes, um lease e um mecanismo de fencing podem ajudar a impedir que dois processos avancem o mesmo estado, mas precisam de suporte correto no armazenamento.

Estados úteis para a recuperação

Estado observadoO que é possível concluirPróxima etapa
A ferramenta ainda não foi chamadaNão há indicação de que o efeito tenha sido solicitadoEnviar a operação com a identidade já persistida
A solicitação foi enviada, mas não houve respostaO efeito pode ter acontecidoConsultar o destino ou procurar o comprovante
O efeito externo ocorreu, mas falta o checkpoint localO journal está desatualizadoReconciliar usando a mesma chave e salvar o resultado recuperado
O comprovante foi persistidoA etapa está confirmada no journalReutilizar o resultado e avançar
Não há consulta confiável e repetir pode causar danoO resultado continua sem resoluçãoMarcar como desconhecido e pausar para revisão
03

Tentativas com limites e condições claras

Uma nova tentativa é razoável quando a falha parece transitória e é seguro repetir a operação. Um serviço ocupado ou uma interrupção antes do envio da solicitação pode permitir outra tentativa; uma autorização negada, argumentos inválidos ou uma chave em conflito normalmente exigem corrigir a causa, não insistir. Classifique o erro antes de aplicar uma política de novas tentativas.

O backoff exponencial aumenta o intervalo entre tentativas sucessivas e pode incluir jitter para evitar que muitos workers voltem a chamar o mesmo serviço ao mesmo tempo. Essa técnica controla quando tentar novamente; não garante que o serviço estará disponível nem que a ação será correta. Defina um número máximo de tentativas e um limite de tempo total, e registre o motivo de cada espera.

Uma chave de idempotência estável vincula tentativas da mesma intenção quando o provedor reconhece a chave e aplica o contrato correspondente. Mantenha a chave entre as tentativas da mesma operação. Gerar uma nova chave após um timeout pode transformar a repetição em uma segunda operação. Se os argumentos mudarem, não reutilize silenciosamente uma chave associada a outro conteúdo.

Quando o provedor não oferece idempotência, procure uma consulta de estado ou uma referência de negócio que permita reconciliar o resultado. Se nenhuma opção for confiável, parar pode ser mais seguro do que tentar novamente. Repetir uma chamada de leitura e repetir uma chamada que envia dinheiro, e-mail ou alterações de permissões não apresentam o mesmo risco.

Decisão antes de tentar novamente

SituaçãoDecisão prudenteCondição
Falha transitória antes do envioTentar novamente com espera limitadaA operação ainda não foi solicitada
Timeout após enviar uma gravaçãoReconciliar antes de tentar novamenteConsultar pela chave ou pelo estado no destino
Entrada inválida ou autorização negadaParar e corrigir a causaNão tentar resolver aumentando o número de tentativas
Mesma intenção e provedor idempotenteRepetir com a mesma chaveConfirmar o prazo e a semântica do provedor
Resultado desconhecido e efeito de alto riscoPausar e escalarNão existe verificação confiável
04

Efeitos externos: idempotência não é rollback

Idempotência e rollback resolvem problemas diferentes. A idempotência busca impedir que várias tentativas da mesma operação produzam efeitos de negócio duplicados, se o executor e o provedor respeitarem esse contrato. O rollback tenta desfazer um efeito que já foi aplicado. Repetir de forma idempotente não desfaz uma alteração.

Nem todas as ações são reversíveis. Uma reserva pode ser liberada; um pagamento talvez exija um reembolso separado; um e-mail enviado não pode ser retirado da caixa de entrada de quem o recebeu. Em muitos casos, a alternativa é uma ação compensatória explícita, que constitui uma nova operação e pode falhar ou exigir aprovação.

Antes de automatizar uma gravação, identifique seu efeito, como verificá-lo e qual compensação pode ser possível. Se uma ação não puder ser desfeita de forma confiável, limite seu alcance, exija aprovação quando apropriado ou interrompa o fluxo diante de uma ambiguidade. Não apresente uma restauração ampla de dados como rollback seletivo: recuperar uma cópia pode afetar alterações válidas realizadas depois.

Um padrão de teste local pode simular uma queda entre a execução de um efeito e o salvamento do comprovante. A simulação permite verificar se o runtime retoma o plano e consulta o registro externo antes de duplicar a operação. Isso, por si só, não demonstra que um provedor real oferece idempotência, que existe atomicidade distribuída ou que dois workers concorrentes estão coordenados.

05

Escalonamento para uma pessoa com contexto útil

O escalonamento humano não deve consistir em encaminhar uma exceção sem explicação. A pessoa que recebe o caso precisa saber o que foi tentado, qual resultado foi confirmado, o que ainda não se sabe e qual é o risco de continuar. Inclua o estado recuperável e a decisão pendente, não apenas o texto da pessoa usuária.

Um pacote prático para transferência pode conter o identificador da execução, a etapa interrompida, a ferramenta e sua versão, as tentativas realizadas, o erro classificado, a chave da operação, os comprovantes disponíveis e as consultas de reconciliação efetuadas. Inclua as aprovações vigentes e qualquer condição de segurança ou orçamento que possa impedir a continuação.

Oculte argumentos sensíveis e limite o acesso aos registros de acordo com as regras aplicáveis. O agente deve expressar a incerteza de forma concreta, por exemplo: “a solicitação foi enviada, mas o resultado não está confirmado”. Não deve afirmar que a alteração ocorreu ou não ocorreu se o estado continuar sem resolução.

A pessoa responsável pela revisão precisa de uma próxima ação clara: consultar o sistema de destino, autorizar uma compensação, corrigir a entrada ou encerrar o caso. Se a revisão decidir repetir a operação, registre quem tomou a decisão, com base em quais dados e qual chave foi usada. Assim, a rastreabilidade é preservada sem delegar ao modelo autoridade para resolver uma operação de risco.

Transferência de uma execução incerta

Use o mesmo contexto para que a equipe possa investigar e decidir sem reconstruir o histórico do zero.

  1. 01Identifique a execução, a etapa e a versão do fluxo.
  2. 02Resuma o que foi enviado, quantas tentativas ocorreram e o que a ferramenta respondeu.
  3. 03Separe os resultados confirmados dos estados desconhecidos.
  4. 04Indique qual consulta ou aprovação falta e quais efeitos uma nova tentativa pode causar.
  5. 05Registre a decisão humana e devolva o controle ao fluxo somente quando o estado estiver resolvido.
06

Observabilidade e testes de recuperação

A observabilidade deve permitir reconstruir uma execução e distinguir falhas do modelo, da ferramenta e da infraestrutura. Registre transições de estado, início e resultado de cada chamada, latência, erros classificados, tentativas, checkpoints e escalonamentos. Relacione esses eventos a um identificador de execução e à versão do fluxo, sem armazenar indiscriminadamente dados sensíveis.

Não existe uma métrica universal que, sozinha, resuma a resiliência de todos os agentes. Uma equipe pode observar quantas execuções são recuperadas, quanto tempo os estados desconhecidos levam para ser resolvidos, quantos casos exigem intervenção e quantos efeitos duplicados são detectados. Defina cada indicador com seu denominador e intervalo de tempo; sem essa definição, uma taxa de recuperação pode ser difícil de interpretar.

Teste os caminhos de falha, não apenas a saída final do modelo. Simule uma queda antes do envio, uma resposta perdida após a aceitação, um erro transitório, uma chave reutilizada com argumentos diferentes e dois workers disputando a mesma execução. Verifique se uma etapa confirmada não é repetida e se um estado desconhecido não é apresentado como sucesso ou falha confirmada.

Testes com arquivos locais ou provedores falsos verificam as decisões do código nas condições simuladas. Eles não validam automaticamente a semântica de um provedor em produção, a durabilidade do banco de dados nem a eficácia de um mecanismo de coordenação distribuída. Confira as garantias relevantes na documentação do serviço e teste a configuração específica que o agente usará.

O que observar em cada execução

SinalPergunta que ajuda a responder
Transições de estadoEm que etapa ocorreu a interrupção e qual foi o último checkpoint confirmado?
Erro e ferramentaFoi uma rejeição, indisponibilidade, timeout ou falha de lógica?
Tentativas e esperasQuantas vezes a operação foi repetida e com qual limite?
Comprovante ou identificador externoÉ possível verificar o efeito no sistema de destino?
Estado desconhecido e escalonamentoQuanto tempo levou a reconciliação e quem resolveu o caso?
Versão do fluxoO checkpoint é compatível com o código que o recupera?
07

Um protocolo de recuperação aplicável

Um protocolo claro organiza a recuperação: carregue o último checkpoint confirmado, verifique a compatibilidade da versão, identifique a operação interrompida e classifique o resultado. Se a operação ainda não foi enviada, ela pode ser executada com a identidade persistida. Se foi enviada e não houve resposta, consulte o destino ou o comprovante antes de decidir. Se estiver confirmada, salve o resultado e continue a partir da etapa seguinte.

A política deve estabelecer quando novas tentativas são permitidas, quais são seus limites e quais erros exigem uma interrupção. Também deve definir quem pode resolver um estado desconhecido e quando é necessária uma aprovação adicional. Uma regra explícita de parada protege contra ciclos e impede que um modelo transforme a ausência de resposta em permissão para tentar novamente.

Teste o protocolo com um fixture controlado antes de conectá-lo a ações reais. Depois, valide separadamente o comportamento do provedor, as condições de concorrência, a retenção de checkpoints e os procedimentos de escalonamento. Uma arquitetura durável pode assumir parte do journal e do replay, mas não torna automaticamente uma API externa atômica ou exatamente uma vez.

Uma recuperação confiável não significa que toda falha possa ser reparada automaticamente. Significa que o sistema preserva o que foi confirmado, representa honestamente o que é desconhecido e limita a próxima etapa ao que pode justificar. Quando não há uma forma confiável de conhecer o efeito e tentar novamente pode causar dano, pausar e reconciliar fazem parte do funcionamento correto.

08

Continue a explorar

Fontes consultadas

03

Correções e transparência

Se encontrar informação incorreta ou desatualizada, envie-nos a página e a fonte que devemos rever.

Propor uma correção