O agente solicita a criação de um pedido. A conexão demora, o tempo limite termina e a aplicação tenta novamente. Segundos depois, aparecem dois pedidos. A primeira chamada havia sido concluída; apenas a confirmação não chegou a quem a enviou. Esse tipo de incerteza precisa ser tratado antes de automatizar ações com efeitos externos.
Idempotência é a propriedade que permite repetir uma mesma operação sem produzir novamente o efeito já realizado, conforme o contrato do sistema. Em um agente de IA, a proteção deve estar na integração e no armazenamento de estado. Uma instrução como “não duplique pedidos” não substitui esses mecanismos.
Resumo rápido
- Timeout indica que a aplicação deixou de esperar; não comprova que a ação deixou de acontecer.
- Uma operação mantém a mesma identidade nas tentativas seguintes, com os mesmos parâmetros.
- Quando o resultado é desconhecido, consulte e reconcilie antes de autorizar outra execução.
Identifique a operação antes de chamar a ferramenta
Gere um identificador interno quando a tarefa for criada e persista-o antes de enviar a solicitação. Associe a ele empresa, tipo de ação, destino, versão dos parâmetros e estado. A identidade precisa sobreviver a reinícios, novas tentativas e mudanças de modelo.
Separe pedido de negócio e tentativa de comunicação. Um pedido aprovado é uma operação; três tentativas para transmiti-lo continuam pertencendo à mesma operação. Já uma nova compra autorizada pelo cliente merece outra identidade, mesmo que produto e quantidade coincidam.
A Stripe documenta chaves de idempotência para reconhecer repetições. Na API v1, guarda o código e o corpo do resultado iniciado, inclusive erros 500, e compara os parâmetros quando a chave reaparece. O prazo de retenção importa: após a remoção da chave, seu reaproveitamento pode criar uma nova solicitação.
Esse comportamento é um exemplo concreto, não uma regra universal para todas as APIs. Verifique no destino suporte, escopo, duração e tratamento de concorrência. Não copie o nome de um cabeçalho esperando que um serviço sem suporte passe a reconhecer repetições.
Evite colocar nome, telefone ou e-mail na chave. Prefira uma identidade opaca, ligada internamente ao registro autorizado. Se os parâmetros mudarem, interrompa a repetição e avalie se existe uma nova operação.
Registre o estado e impeça disputas entre execuções
Um desenho inicial pode usar estados como pendente, em_execucao, confirmada, falhou e resultado_desconhecido. A última opção é essencial: ela impede que uma ausência de confirmação seja interpretada automaticamente como autorização para repetir.
Antes de trabalhar, o executor tenta assumir a operação de forma atômica. No banco, a combinação de empresa e identificador deve ser única e obrigatória. As restrições UNIQUE e de chave primária do PostgreSQL oferecem mecanismos para impedir registros duplicados; a chave primária também exige valores não nulos.
Essa proteção local evita que dois trabalhadores criem registros equivalentes, mas não resolve sozinha a chamada externa. Existe um intervalo entre o destino concluir a ação e o seu sistema gravar a confirmação. Para fechar essa lacuna, use a idempotência do destino quando disponível e salve o identificador retornado para conciliação.
Se uma execução parar em em_execucao, não a libere apenas porque passou algum tempo. Investigue se ainda existe trabalho ativo e se a ação externa ocorreu. Um bloqueio expirado não é prova de que o pedido não foi criado.
Exemplo hipotético: uma mensagem com confirmação perdida
Uma empresa aprova o envio de uma atualização ao cliente. A automação registra a operação op_742, o destinatário autorizado e o texto final. Depois chama o serviço de mensagens, mas a conexão termina antes de receber a confirmação.
O registro passa para resultado_desconhecido. Se houver um identificador externo disponível, o processo de conciliação tenta localizar seu estado. A documentação oficial de mensagens da Meta informa que IDs únicos permitem acompanhar estados por webhooks. Isso ajuda quando a correlação foi preservada; não recupera automaticamente uma identidade que nunca chegou à aplicação.
Se o serviço oferecer uma chave de idempotência adequada, a repetição pode reutilizar a identidade original, obedecendo ao contrato documentado. Sem esse recurso e sem evidência para conciliar, recomendamos manter o caso pendente para revisão. Prometer “envio exatamente uma vez” nessa situação seria ignorar a incerteza.
O mesmo raciocínio vale para pedidos, agendamentos e alterações cadastrais. A orientação da AWS sobre timeouts e retries ressalta que uma falha de comunicação não significa ausência de efeitos e que repetições podem ampliar sobrecarga. Portanto, combine tentativas limitadas com espera progressiva e consulta de estado.
Para definir o prazo total do trabalho, complemente com o guia sobre timeouts e limites de execução em agentes de IA.
Checklist de teste e recuperação
- Executar duas tentativas simultâneas com a mesma identidade e conferir o resultado.
- Interromper a conexão após o destino receber a solicitação.
- Reiniciar o trabalhador antes de salvar a confirmação externa.
- Reenviar a mesma identidade com parâmetros diferentes e exigir tratamento explícito.
- Testar uma operação retomada depois do prazo de retenção da chave no destino.
- Confirmar que a revisão manual encontra parâmetros, tentativas, estado e evidências disponíveis.
Conte efeitos produzidos no destino, e não apenas execuções marcadas como concluídas. Registre também quantos casos ficaram desconhecidos e quanto tempo levaram para ser conciliados. Essa visibilidade permite ajustar o fluxo sem esconder falhas.
Trate separadamente a duplicação de entrada: receber o mesmo webhook duas vezes não deve iniciar duas operações. O artigo sobre assinaturas e processamento duplicado de webhooks complementa essa etapa.
Perguntas frequentes
Posso gerar outra chave quando houver erro?
Para repetir a mesma operação, preserve a identidade. Uma chave nova pode fazer o destino entender que recebeu uma nova solicitação.
Idempotência garante que a operação dará certo?
Não. Ela controla o efeito de repetições dentro do contrato implementado. Validação, autorização, disponibilidade e recuperação de resultados desconhecidos continuam necessárias.
