Ações idempotentes em agentes de IA: como evitar reembolsos duplicados

Ações idempotentes são operações de escrita desenhadas para que repetir o mesmo pedido deixe o resultado inalterado. Um agente que emite um reembolso, reserva um horário ou envia uma confirmação deve associar uma chave de operação estável a cada efeito pretendido, registrar essa chave antes de o efeito acontecer e devolver o resultado original quando a mesma chave chegar de novo. Sem essa proteção, um timeout, um worker reiniciado ou um webhook reenviado podem transformar uma única decisão em dois pagamentos, duas reservas ou dois e-mails.

Principais pontos

• Toda ação de escrita precisa de uma chave de operação estável, criada uma vez no momento da decisão e reutilizada em cada tentativa.
• Registre a intenção e a chave antes de chamar o sistema externo, para que uma falha no meio do caminho não apague o que foi tentado.
• Deixe o sistema de destino impor unicidade sempre que puder, e mantenha seu próprio registro como a versão do que o agente acredita que aconteceu.
• Trate resultado desconhecido como um estado próprio: verifique antes de tentar de novo e escale quando a verificação for inconclusiva.
• Reproduza casos duplicados de propósito em ambiente de teste antes de o agente ter autoridade real.

Por que tentativas criam reembolsos e mensagens duplicadas

Novas tentativas são normais. Redes perdem respostas, chamadas ao modelo estouram o tempo limite, workers reiniciam e camadas de orquestração reenviam trabalhos que nunca retornaram. Do lado do agente, um pedido que deu timeout parece igual a um pedido que falhou antes de chegar ao sistema. Em uma leitura, tentar de novo é inofensivo. Em uma escrita, tentar de novo sem uma proteção pode executar a ação duas vezes.

Agentes aumentam esse risco porque decidem o que fazer a partir de texto, e a mesma decisão pode ser alcançada mais de uma vez. Uma mensagem de cliente que diz “fui cobrado duas vezes, por favor estornem a segunda cobrança” pode gerar um pedido de reembolso, depois um segundo pedido após um timeout, e um terceiro numa nova execução do resumo da conversa. Cada pedido parece razoável isoladamente. Juntos, eles são um reembolso duplicado, e o dono do negócio descobre isso no extrato bancário.

Dê a cada escrita uma chave de operação estável

A chave de operação identifica um efeito pretendido, não uma chamada HTTP. Monte a chave a partir do objeto de negócio, do tipo de ação e do identificador da decisão. Por exemplo: o identificador do pedido, mais “reembolso-total”, mais o ID da decisão que aprovou o reembolso. Assim, cada nova tentativa daquela decisão carrega a mesma chave. Uma chave gerada do zero a cada tentativa anula o objetivo, porque o sistema receptor trata cada tentativa como trabalho novo.

Crie a chave no momento da decisão, guarde-a junto com a decisão e passe-a por todas as camadas. Se o agente executa um laço de chamadas de ferramentas, a chave precisa sobreviver entre as iterações. Não a gere dentro do wrapper da ferramenta, pois cada nova tentativa do wrapper produziria uma chave diferente.

Quando o provedor externo oferece idempotência nativa, use-a. O Stripe, por exemplo, aceita uma chave de idempotência em requisições POST e devolve o resultado guardado quando a mesma chave é reutilizada com os mesmos parâmetros. Verifique cada sistema conectado em busca de recurso equivalente antes de desenhar um esquema próprio, e mantenha seu registro como segunda fonte mesmo quando o provedor oferecer a proteção. Tome cuidado com uma chave reutilizada com parâmetros diferentes: o comportamento correto é rejeitar o segundo pedido, não uni-lo silenciosamente.

Registre a intenção antes do efeito e verifique antes de cada escrita

A maior parte das duplicatas acontece na lacuna entre “a chamada foi enviada” e “a chamada foi confirmada”. Feche essa lacuna com uma entrada de registro gravada antes da chamada externa. Uma entrada útil contém a chave da operação, o tipo de ação, o objeto alvo, o valor ou um hash do conteúdo, quem ou o que solicitou, o horário e um status pendente. Depois da chamada, o status passa a sucesso, falha ou desconhecido, com a referência externa quando existir. Um registro que guarda apenas sucessos não impede duplicatas, porque o estado perigoso é o pendente: é ele que avisa a próxima tentativa de que algo pode já ter acontecido.

O registro faz seu trabalho por meio de uma regra de unicidade sobre a chave da operação. Uma segunda inserção com a mesma chave falha, e o wrapper lê a linha existente em vez de agir. Antes de qualquer escrita, o wrapper da ferramenta deve seguir quatro caminhos:

• Não existe registro: insira como pendente, execute a chamada e depois atualize o status com o resultado.
• Registro com sucesso: devolva o resultado guardado e não chame o sistema de novo.
• Registro pendente ou desconhecido: não chame às cegas. Consulte o sistema externo pelo efeito, por exemplo se existe um reembolso com aquela referência, e resolva o estado primeiro.
• Registro com falha de motivo não repetível: pare e informe o motivo ao responsável pelo fluxo de trabalho.

Mantenha os endpoints de escrita fora do alcance direto do agente. Ele deve chamar uma única ferramenta que aplique esses caminhos, para que não exista atalho que contorne o registro.

Para os campos da entrada de registro e como mantê-los úteis para revisões posteriores, veja Trilha de auditoria de agente de IA: campos que cada ação precisa ter.

Decida o que acontece quando o resultado é desconhecido

Um resultado desconhecido não é uma falha. Significa que o agente não consegue provar se o efeito aconteceu. Tentar de novo um reembolso desconhecido porque a primeira chamada provavelmente não chegou aceita o risco de pagar duas vezes, por isso o padrão deve ser verificação, não repetição. O guia de decisão abaixo é simples o bastante para um líder de operações aprovar uma vez e revisar depois:

• Se o sistema externo pode ser consultado pela chave da operação ou pela referência externa, o agente consulta e age de acordo com a resposta.
• Se o sistema não pode ser consultado, o agente não tenta de novo. Ele abre um item de revisão contendo a decisão, a chave, a entrada de registro e as evidências disponíveis.
• Se o valor, o destinatário ou o escopo estiver acima de um limite definido pelo dono do negócio, o item vai para uma pessoa, mesmo quando a consulta for conclusiva.
• Se o mesmo cliente ou objeto tiver outra ação pendente, as duas ficam retidas até que uma delas seja resolvida.

Cenário ilustrativo: um agente de atendimento recebe um pedido para reembolsar uma cobrança duplicada. A chamada ao provedor de pagamento devolve um timeout, e o registro mostra o reembolso como desconhecido. O agente consulta o provedor por um reembolso associado à chave da operação, encontra um criado pela primeira tentativa, registra essa referência e informa ao cliente que o reembolso já foi emitido. Uma nova tentativa ingênua teria emitido um segundo reembolso para o mesmo cartão.

Depois, o agente escala apenas o que não consegue resolver. Para uma forma limpa de entregar a decisão, e não o registro bruto, veja Escalonamento humano em IA: entregue a decisão necessária.

Cubra mensagens, reservas e webhooks, não só pagamentos

E-mails, SMS, mensagens de WhatsApp, convites de agenda e pedidos de compra duplicados exigem a mesma disciplina. O dinheiro tem um saldo que o financeiro consegue conciliar, mas um cliente que recebe duas confirmações percebe na hora, e isso corrói a confiança mais rápido do que a maioria dos erros de retaguarda. Use uma chave de operação por destinatário, por tipo de mensagem e por decisão, e permita que o wrapper envie aquela mensagem apenas uma vez por chave, mesmo quando a chamada for repetida.

Os webhooks merecem uma regra própria. Plataformas de pagamento e de agendamento podem entregar o mesmo evento mais de uma vez, e um receptor que age a cada entrega vai repetir trabalho. O Stripe documenta como os eventos de webhook são entregues e como o receptor deve verificá-los. Guarde o identificador de cada evento processado no registro, verifique a assinatura antes de agir e ignore eventos já marcados como processados. Trate o identificador do evento como a chave da operação para o trabalho que ele dispara.

Reservas têm uma falha mais sutil. Um pedido de reserva repetido após um timeout pode criar um segundo horário que a agenda aceita, porque não é uma duplicata exata. Inclua cliente, serviço e janela de horário na chave, e faça o wrapper verificar itens pendentes ou confirmados sobrepostos antes de gravar.

Reproduza duplicatas antes de dar autoridade ao agente

Antes de um agente poder executar escritas reais, teste seus wrappers com duplicatas deliberadas. Escreva com antecedência o resultado esperado para cada caso e rode os testes em um ambiente de homologação que se comporte o mais parecido possível com o provedor real. Um conjunto curto de reprodução costuma cobrir estes casos:

• O mesmo pedido enviado duas vezes em sequência, em que a segunda chamada deve devolver o resultado guardado.
• Um pedido cuja primeira chamada é simulada com timeout, em que o wrapper deve consultar antes de tentar de novo.
• O mesmo evento de webhook entregue duas vezes, em que a segunda entrega não deve fazer nada.
• Dois pedidos com a mesma chave e parâmetros diferentes, em que o segundo deve ser rejeitado.
• Dois pedidos para o mesmo objeto enviados em sequência próxima, em que apenas um deve ter sucesso.

Registre os resultados e guarde o conjunto de reprodução. Ele vira uma verificação de regressão para qualquer mudança no wrapper da ferramenta, no prompt ou no sistema conectado. Para separar ambiente de teste e de produção, veja Teste um agente de IA em modo de observação.

No modelo gerenciado da Be Human, o esquema de chaves de operação, o registro e as regras de estado desconhecido são definidos na primeira etapa do trabalho, como parte da memória, das ferramentas e dos limites de aprovação em que o agente opera. O trabalho recorrente cobre então o monitoramento de chaves duplicadas e de itens pendentes além da janela combinada, a revisão periódica das permissões dos sistemas conectados e um caminho de incidente documentado para qualquer caso em que um efeito duplo possa ter ocorrido. O negócio continua decidindo quais ações o agente pode executar por conta própria, e mudanças nessas ações passam pela mesma revisão.

Se você não tem certeza de qual fluxo de trabalho se beneficiaria primeiro dessa disciplina, o diagnóstico gratuito de IA da Be Human pode ajudar a identificar a primeira tarefa que vale entregar a um agente.

Perguntas frequentes

O modelo de linguagem consegue evitar ações duplicadas lendo o histórico da conversa? Não de forma confiável. O modelo pode resumir, reformular ou repetir um pedido após um timeout, então a mesma decisão pode chegar com texto diferente e sem identificador compartilhado. A proteção precisa ficar na camada de ferramentas, onde uma chave estável e um registro decidem se o efeito já aconteceu.

Chave de idempotência é a mesma coisa que limite de novas tentativas? Não. O limite de tentativas controla quantas vezes o agente tenta, enquanto a chave de idempotência controla se tentativas repetidas podem produzir um segundo efeito. Em geral você precisa dos dois, e a política de repetição deve consultar o registro antes de cada tentativa.

Preciso de idempotência se meu provedor já rejeita duplicatas? Na maioria dos casos, sim. As regras dos provedores costumam cobrir apenas duplicatas exatas e podem não cobrir quase-duplicatas, como duas reservas para o mesmo cliente com um horário ligeiramente diferente. Seu registro também oferece o histórico do que o agente tentou, o que o provedor não guarda para você.

O que um líder de operações deve perguntar à equipe antes de dar ao agente acesso de escrita? Pergunte como cada escrita é identificada por chave, o que é registrado antes da chamada, o que o agente faz quando o resultado é desconhecido e quem revisa os itens que não podem ser resolvidos automaticamente. Se a equipe não conseguir responder a essas perguntas com detalhes concretos, o agente ainda não está pronto para ter autoridade real.

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