Retentativas em agentes de IA: como configurar

Repetir uma chamada pode recuperar o trabalho ou ampliar a falha

Um agente consulta o CRM, chama um modelo e tenta registrar a próxima ação. A API demora, a conexão expira e a execução recebe um erro. Tentar novamente parece a resposta óbvia.

Talvez seja. Se a falha foi temporária e nenhuma ação ocorreu, outra tentativa pode concluir o trabalho. Se a credencial está inválida, repetir apenas consome capacidade. Se o CRM gravou a alteração e perdeu a confirmação, a nova tentativa pode criar uma tarefa duplicada.

Retentativa é uma política de recuperação para falhas que podem desaparecer em pouco tempo. Ela precisa definir quais erros permitem repetição, quanto esperar, quantas tentativas cabem no prazo e para onde a unidade segue quando a recuperação não acontece.

Essa política deve ficar no orquestrador, adaptador ou cliente da integração. Pedir ao modelo para "tentar de novo se der erro" não oferece controle sobre concorrência, custo, efeito externo ou tempo total.

Quando uma retentativa faz sentido

Uma nova tentativa só tem valor quando existe uma chance razoável de a condição mudar sem intervenção.

Casos comuns incluem:

falha de conexão antes do envio;
resposta temporária de indisponibilidade;
limite de taxa com uma janela conhecida de reposição;
timeout de uma consulta sem efeito externo;
bloqueio transitório de banco;
concorrência momentânea em uma fila;
serviço em recuperação dentro do prazo da tarefa.

A classificação precisa considerar a operação, e não apenas o código técnico. Uma resposta 429 costuma pedir espera. Uma resposta 500 pode ser temporária ou esconder um erro recorrente do endpoint. Um timeout de leitura é diferente de um timeout depois de solicitar uma cobrança.

A política segura combina três perguntas:

a causa pode desaparecer sozinha?
o efeito anterior é conhecido?
ainda existe tempo para concluir o trabalho com utilidade?

Se uma dessas respostas for negativa ou incerta, o fluxo precisa de outro tratamento.

Erros que devem parar cedo

Algumas falhas exigem correção, decisão ou bloqueio. Repetir não altera a causa.

Entrada inválida

Campo obrigatório ausente, arquivo corrompido, identificador inexistente e valor fora da regra precisam voltar à origem ou seguir para uma fila de exceção.

Identidade, credencial ou permissão

Token vencido, conta bloqueada e acesso insuficiente pedem renovação ou ajuste de autorização. Uma única causa pode afetar muitas tarefas. Continuar tentando multiplica ruído e pode acionar mecanismos de proteção do fornecedor.

Regra de negócio recusada

Um pedido cancelado, uma oportunidade encerrada ou um limite financeiro ultrapassado não se torna válido depois de alguns segundos. A unidade deve reler o estado oficial ou solicitar decisão do responsável.

Violação de política

Tentativa de acessar dado proibido, executar ação fora da alçada ou usar uma ferramenta não autorizada deve ser bloqueada. A repetição nunca pode funcionar como caminho para contornar uma barreira.

Saída incompatível recorrente

Uma resposta fora do esquema pode admitir uma correção limitada. Se o agente continua omitindo campos ou contrariando critérios, a unidade precisa sair do ciclo. O caso pode alimentar avaliação, ajuste da versão ou revisão humana.

Resultado externo incerto

Quando uma chamada pode ter produzido efeito, o próximo passo é reconciliar. A página sobre idempotência em agentes de IA mostra como preservar uma chave estável, consultar o destino e evitar duplicidade.

Classifique a falha antes de consumir outra tentativa

A decisão de repetir deve usar sinais determinísticos sempre que eles existirem. Código de resposta, etapa, tipo de operação, confirmação do destino, cabeçalho de espera e validade da tarefa oferecem uma base melhor do que a interpretação livre do modelo.

Uma taxonomia simples pode separar:

temporaria_sem_efeito: repetição permitida dentro do orçamento;
limite_de_capacidade: aguardar o sinal do fornecedor e respeitar a fila;
permanente: bloquear e encaminhar correção;
efeito_incerto: reconciliar antes de qualquer nova escrita;
politica: encerrar e registrar a barreira aplicada;
prazo_expirado: cancelar ou pedir nova decisão;
causa_desconhecida: interromper cedo e preservar evidência.

"Erro desconhecido" não deveria receber uma sequência longa por padrão. Sem classificação, a arquitetura aposta capacidade em uma condição que não consegue explicar.

Defina um orçamento de tentativas

Contar somente o número de repetições deixa parte do risco invisível. Uma tarefa pode fazer poucas chamadas muito caras ou permanecer presa por horas entre esperas.

O orçamento deveria considerar:

máximo de tentativas por etapa;
máximo de tentativas por unidade de trabalho;
tempo total desde a entrada;
prazo operacional;
custo acumulado;
chamadas já consumidas em subtarefas;
concorrência disponível;
tentativas feitas por outro worker;
validade do dado usado;
risco do efeito externo.

A unidade precisa carregar o contador entre reinícios, filas e mudanças de worker. Zerar o número porque o processo reiniciou converte um teto conhecido em repetição indefinida.

Também vale separar tentativa técnica de nova decisão. Consultar novamente uma API pode ser recuperação. Pedir ao modelo que refaça todo o plano cria outra interpretação, outros custos e possivelmente outras ações. Essa mudança deve aparecer no estado da execução.

Use backoff para aliviar a dependência

Repetir imediatamente mantém pressão sobre um serviço que acabou de falhar. Backoff aumenta o intervalo entre tentativas para dar tempo de recuperação.

A política pode usar intervalo fixo em um caso simples e de baixo volume. Em sistemas concorrentes, o backoff exponencial costuma ser mais adequado: cada falha aumenta a espera até um teto definido.

Os valores dependem do processo. Uma consulta interativa tolera menos espera do que um lote noturno. Uma atualização comercial pode perder validade antes de uma análise interna. O intervalo deve respeitar o tempo útil da unidade, não apenas uma fórmula técnica.

Quando o fornecedor devolve Retry-After ou outro sinal de reposição, a aplicação deve considerar essa informação dentro dos próprios limites. O cabeçalho indica quando a dependência espera receber nova chamada. Ele não decide se o trabalho ainda merece continuar.

Acrescente jitter para evitar um novo pico

Imagine cem execuções falhando no mesmo segundo. Se todas esperarem o mesmo intervalo, voltarão juntas. A dependência recebe outro pico e pode falhar novamente.

Jitter adiciona uma pequena variação ao tempo de espera de cada unidade. Isso distribui a retomada sem remover o limite geral.

A variação precisa permanecer dentro do prazo e da prioridade do trabalho. Um caso crítico não deveria aguardar indefinidamente por sorteio. Uma tarefa de rotina também não deveria ocupar a faixa reservada para urgências.

O guia de rate limit para agentes de IA explica como combinar taxa, concorrência, fila, prioridade e capacidade reservada. Backoff organiza o retorno de uma unidade. Rate limit governa o consumo compartilhado.

Timeout e retentativa precisam ser desenhados juntos

Um timeout curto demais cria falhas artificiais. Um timeout longo demais prende conexões, workers e orçamento em chamadas que já perderam valor.

Defina o limite por operação. Ler um registro, gerar uma análise extensa e aguardar aprovação humana possuem durações diferentes. Um timeout global raramente representa todas elas.

O orçamento completo deve incluir:

tempo da chamada + espera do backoff + tempo das próximas tentativas

Esse total precisa caber no prazo da unidade. Se um atendimento exige resposta em dez minutos, uma política que pode permanecer vinte minutos tentando está errada mesmo quando termina com sucesso técnico.

Também registre em qual ponto o timeout ocorreu:

antes de abrir conexão;
antes de enviar o comando;
durante o processamento remoto;
depois de enviar uma escrita;
enquanto aguardava confirmação;
durante a consulta de reconciliação.

A posição muda o risco. Depois do envio, o efeito pode existir e a repetição automática deve permanecer bloqueada até confirmação.

Preserve estado e evidência em cada passagem

Uma retentativa precisa continuar a mesma unidade, não criar outra tarefa sem histórico.

Registre pelo menos:

identificador da unidade;
etapa e operação;
dependência chamada;
horário de cada tentativa;
versão do agente e do fluxo;
entrada usada;
classe de erro;
código e resposta resumida;
estado externo conhecido;
intervalo aplicado;
contador atual;
custo acumulado;
prazo e validade;
próxima tentativa prevista;
destino depois do esgotamento.

Evite copiar dados sensíveis para logs. Preserve referências e evidências suficientes para investigar, seguindo a política de retenção e acesso da empresa.

O monitoramento de agentes em produção deve mostrar tentativas por unidade, tempo perdido, causas recorrentes e impacto no prazo do processo.

Coordene retentativas entre camadas

Um problema comum aparece quando várias camadas repetem a mesma chamada. A biblioteca do provedor faz três tentativas. O workflow repete a etapa três vezes. A fila entrega a unidade novamente. O agente ainda decide refazer a tarefa.

Uma única falha pode então gerar dezenas de chamadas.

Faça um inventário dos mecanismos presentes em:

cliente HTTP;
SDK do provedor;
adaptador da ferramenta;
workflow;
fila;
orquestrador;
agente;
plataforma externa.

Escolha onde a política principal será aplicada e faça as outras camadas reportarem o que já consumiram. O contador global precisa refletir a cadeia inteira.

Quando a taxa de falha indica degradação compartilhada, o circuit breaker para agentes de IA deve suspender novas chamadas. Retentativas tratam falhas pontuais. O circuito impede que cada unidade continue descobrindo a mesma indisponibilidade.

Dê um destino para o esgotamento

A última tentativa não pode terminar em um log esquecido. Cada classe de tarefa precisa de um estado conhecido.

Possíveis destinos incluem:

fila de adiamento, quando existe uma janela posterior válida;
resultado parcial com pendência explícita;
operação em modo somente leitura;
revisão humana com contexto;
rota alternativa previamente aprovada;
cancelamento por perda de validade;
fila de erros para correção e reprocessamento;
abertura de incidente diante de risco ou falha ampla.

A fila de erros para agentes de IA organiza unidades que esgotaram tentativas seguras ou exigem intervenção. Ela deve receber a causa, o histórico e a condição necessária para reprocessar.

Teste as falhas, não apenas o fluxo feliz

Inclua cenários que pressionem a política:

conexão falha antes do envio;
429 com e sem indicação de espera;
resposta temporária do servidor;
credencial inválida;
entrada rejeitada;
timeout depois de uma escrita concluída;
destino com consistência eventual;
várias unidades falhando juntas;
worker reiniciando entre tentativas;
contador persistido incorretamente;
SDK e workflow repetindo ao mesmo tempo;
tarefa vencendo durante o backoff;
circuito abrindo no meio da sequência;
fila de erros indisponível;
intervenção manual antes da retomada.

Confirme a quantidade real de chamadas, o estado no sistema externo, a ausência de duplicidade, o tempo total e o destino final de cada unidade. O ambiente de teste para agentes de IA permite simular essas condições sem gerar efeitos em produção.

Métricas para governar a política

Acompanhe:

tentativas por unidade e por etapa;
sucesso recuperado por número de tentativa;
erros permanentes repetidos indevidamente;
tempo acumulado em espera;
custo das repetições;
unidades que perderam validade;
resultados externos incertos;
duplicidades causadas depois de timeout;
chamadas bloqueadas pelo circuito;
entradas na fila de erros;
causas mais frequentes;
diferença por versão, dependência e processo.

Uma taxa alta de recuperação na terceira tentativa pode justificar a política. Muitas recuperações depois do prazo continuam sendo falhas operacionais. O resultado precisa ser medido contra a utilidade entregue.

Checklist para configurar retentativas

[ ] As falhas temporárias estão separadas das permanentes?
[ ] O efeito externo é conhecido antes de repetir uma escrita?
[ ] Existe orçamento por etapa e por unidade?
[ ] O contador sobrevive a filas e reinícios?
[ ] Timeout, espera e tentativas cabem no prazo do processo?
[ ] O backoff reduz pressão sobre a dependência?
[ ] O jitter evita retomadas sincronizadas?
[ ] Sinais como Retry-After são respeitados dentro da política?
[ ] SDK, workflow e fila compartilham o consumo já realizado?
[ ] Idempotência protege ações externas?
[ ] Circuit breaker contém degradação compartilhada?
[ ] A última tentativa termina em um estado com dono?
[ ] Tarefas vencidas são canceladas ou reavaliadas?
[ ] Logs preservam evidência sem expor dados desnecessários?
[ ] Testes cobrem falha, incerteza, concorrência e retomada?

A repetição precisa comprar uma chance real de recuperação

Retentativas aumentam a continuidade quando a arquitetura sabe o que falhou, se algum efeito ocorreu e quanto tempo ainda existe. Sem essas respostas, repetir é apenas insistência automatizada.

Uma política madura classifica a causa, limita o consumo, distribui as esperas, preserva o estado e encaminha exceções. O agente consegue recuperar falhas breves sem transformar indisponibilidade, erro de regra ou confirmação perdida em custo, atraso e duplicidade.