Quando algo falha

Uma etapa pode falhar. O que acontece depois é escolha sua, e há três mecanismos.

1. Tentativas

Etapas que suportam repetição podem tentar de novo automaticamente.

Ajuste	O que faz
Número de tentativas	De 1 a 10. O padrão é uma — sem repetição
Espera entre tentativas	Cresce a cada tentativa, com variação, para não repetir todas no mesmo instante

Nem toda falha é repetida: só as transitórias — o motor indisponível, um tempo limite, uma credencial expirada. Falhas de configuração não são repetidas, porque tentar de novo daria o mesmo resultado.

Etapas determinísticas — Preparar dados, Condição — não oferecem repetição pelo mesmo motivo. E Gerar com um modelo não repete sozinha porque uma resposta ambígua pode já ter sido cobrada.

Enquanto espera para tentar de novo, a execução libera recursos e volta sozinha.

2. Caminho de erro

Etapas que suportam podem ter uma saída em caso de falha, ligada a outra parte do fluxo.

Com caminho de erro:

• a etapa continua marcada como falha — ela falhou mesmo;
• a execução segue pelo desvio;
• o desvio recebe o motivo da falha: código, mensagem, se era transitória e em qual tentativa aconteceu.

O caminho de erro só é tomado depois de esgotadas as tentativas. E ele é uma etapa como qualquer outra: se o tratamento falhar, a execução falha.

Sem caminho de erro, a execução termina como falha e as etapas seguintes são canceladas.

3. Degradação declarada

Quando um erro é tratado por um desvio, o resultado final do agente declara isso: ele carrega a lista das etapas que quebraram e o motivo.

Tratado não é "não aconteceu". Um fluxo que trata erros e entrega sucesso limpo esconde exatamente o que alguém precisaria saber para confiar no número recebido.

O que a mensagem de erro contém

Toda mensagem passa por uma limpeza antes de ser gravada: credenciais, tokens e endereços de banco são cortados. O que sobra é o suficiente para diagnosticar, e nada que não deva circular.

Tempo limite

Existem quatro prazos, e eles se somam ao longo da execução:

Prazo	Onde
Da execução	Declarado no agente. Estourou, a execução termina como expirada
Da etapa	Opcional, por etapa. Precisa caber no prazo da execução
Da aprovação	Opcional, na etapa de aprovação
Interno da plataforma	Recuperação de execuções interrompidas

Cancelamento

Uma execução pode ser cancelada a qualquer momento. O cancelamento é cooperativo: ele é verificado entre etapas, nunca no meio de uma chamada em andamento — interromper no meio deixaria a operação do outro lado sem desfecho conhecido.

Execuções filhas são canceladas junto.

Padrões úteis

Objetivo	Como montar
Continuar mesmo se um sistema estiver fora	Caminho de erro → Preparar dados com valor padrão → segue
Avisar alguém quando falhar	Caminho de erro → Tarefa com IA ou automação de notificação
Exigir todas as origens de uma junção	Combinar resultados com "falhar" quando faltar origem
Tolerar item ruim numa lista	Para cada item com "seguir e registrar"

Erros comuns

Sintoma	Causa	O que fazer
A execução falha sem tentar de novo	O padrão é uma tentativa	Configure as tentativas na etapa
A etapa repete e falha igual	A falha não é transitória	Corrija a configuração; repetir não resolve
O resultado diz sucesso, mas algo quebrou	Um erro foi tratado por desvio	Veja as etapas com falha tratada no resultado
A execução termina como expirada	O prazo total acabou	Aumente o tempo limite ou reduza o trabalho

Próximos passos

• Erros de execução
• Acompanhar execuções
• Testar antes de publicar