Idempotência em agentes de IA: evite ações duplicadas

Idempotência significa que repetir um pedido produz o mesmo efeito pretendido de executá-lo uma vez. Em agentes de IA, ajuda a evitar mensagens, registros ou pagamentos duplicados quando um fluxo tenta novamente após uma interrupção. Ela exige suporte na execução; pedir ao modelo que não se repita não basta.

Comece pelo timeout ambíguo

Imagine um agente criando uma tarefa de cliente. O destino salva, mas a resposta se perde. O agente recebe timeout e tenta novamente. Sem proteção, aparecem duas tarefas embora a pessoa tenha pedido uma.

A recuperação segura depende do destino. Algumas APIs aceitam chave de idempotência. Outras exigem consulta por um identificador estável antes de decidir se a ação deve ser repetida.

Identifique cada ação pretendida

• Gere um código estável para a ação de negócio específica.
• Persista esse código antes de tentar a escrita externa.
• Associe destino, conteúdo e estado ao pedido.
• Reconcilie resultados desconhecidos com recibos ou leitura no destino.
• Reutilize a chave apenas conforme as regras documentadas do provedor.

Não use a mesma chave para conteúdo alterado. Uma segunda ação legítima precisa de identidade própria; uma repetição da original deve continuar ligada ao registro original.

Teste uma resposta perdida

Em ambiente controlado, simule uma escrita bem-sucedida seguida de erro de transporte. Confirme que a próxima execução encontra ou reconcilia o primeiro resultado em vez de criar outro. Teste pedidos duplicados concorrentes, pois dois executores podem receber o mesmo evento quase simultaneamente.

Uma marcação local pode falhar em concorrência se a operação de armazenamento não for atômica.

Informe o desconhecido com honestidade

Quando não for possível estabelecer se a ação ocorreu, preserve a incerteza e encaminhe ao responsável pela recuperação. Não marque como sucesso nem como falha certa. Um estado explicitamente desconhecido é mais útil que uma conclusão confiante que leva o time a repetir uma ação com consequências reais.

Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.