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.
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 observado | O que é possível concluir | Próxima etapa |
|---|---|---|
| A ferramenta ainda não foi chamada | Não há indicação de que o efeito tenha sido solicitado | Enviar a operação com a identidade já persistida |
| A solicitação foi enviada, mas não houve resposta | O efeito pode ter acontecido | Consultar o destino ou procurar o comprovante |
| O efeito externo ocorreu, mas falta o checkpoint local | O journal está desatualizado | Reconciliar usando a mesma chave e salvar o resultado recuperado |
| O comprovante foi persistido | A etapa está confirmada no journal | Reutilizar o resultado e avançar |
| Não há consulta confiável e repetir pode causar dano | O resultado continua sem resolução | Marcar como desconhecido e pausar para revisão |
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ção | Decisão prudente | Condição |
|---|---|---|
| Falha transitória antes do envio | Tentar novamente com espera limitada | A operação ainda não foi solicitada |
| Timeout após enviar uma gravação | Reconciliar antes de tentar novamente | Consultar pela chave ou pelo estado no destino |
| Entrada inválida ou autorização negada | Parar e corrigir a causa | Não tentar resolver aumentando o número de tentativas |
| Mesma intenção e provedor idempotente | Repetir com a mesma chave | Confirmar o prazo e a semântica do provedor |
| Resultado desconhecido e efeito de alto risco | Pausar e escalar | Não existe verificação confiável |
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.
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.
- 01Identifique a execução, a etapa e a versão do fluxo.
- 02Resuma o que foi enviado, quantas tentativas ocorreram e o que a ferramenta respondeu.
- 03Separe os resultados confirmados dos estados desconhecidos.
- 04Indique qual consulta ou aprovação falta e quais efeitos uma nova tentativa pode causar.
- 05Registre a decisão humana e devolva o controle ao fluxo somente quando o estado estiver resolvido.
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
| Sinal | Pergunta que ajuda a responder |
|---|---|
| Transições de estado | Em que etapa ocorreu a interrupção e qual foi o último checkpoint confirmado? |
| Erro e ferramenta | Foi uma rejeição, indisponibilidade, timeout ou falha de lógica? |
| Tentativas e esperas | Quantas 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 escalonamento | Quanto tempo levou a reconciliação e quem resolveu o caso? |
| Versão do fluxo | O checkpoint é compatível com o código que o recupera? |
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.
Continue a explorar
Fontes consultadas
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