Ações idempotentes em agentes de IA: evite faturas e reservas duplicadas

Uma ação idempotente é uma escrita que produz o mesmo resultado, não importa quantas vezes o mesmo pedido seja enviado. Para tornar um agente de IA seguro para repetir uma operação, dê a cada escrita uma chave estável ligada ao evento de negócio, consulte um registro antes de agir e grave o resultado antes de informar sucesso. É isso que impede um timeout ou uma chamada repetida de ferramenta de criar uma segunda reserva, fatura ou mensagem.

Principais pontos

• Novas tentativas são normais. Um timeout não informa ao agente se a escrita aconteceu, então ele será tentado a repetir.
• Monte cada chave a partir do evento de negócio (cliente, período do serviço, horário, pedido), e não de um identificador aleatório gerado a cada tentativa.
• Grave um registro pendente antes da chamada e um registro de resultado depois. Consulte esse registro antes de qualquer escrita.
• Use o recurso de idempotência do fornecedor quando ele existir, e crie sua própria checagem quando não existir.
• Trate mensagens, pagamentos e reservas como os casos mais rígidos, porque uma segunda tentativa fica visível para o cliente ou movimenta dinheiro.

Por que as novas tentativas geram duplicidades

Um agente não vive a escrita como uma pessoa. Ele envia um pedido, espera e recebe um resultado, um erro ou nada. Se a conexão cai depois que o sistema de faturamento já salvou a fatura, o agente vê um timeout. Do ponto de vista dele, a ação falhou, então o passo razoável é chamar a ferramenta de novo.

O mesmo acontece em outros pontos. Um webhook pode ser entregue duas vezes. Uma fila pode reenviar um job depois que um worker reinicia. Um usuário pode escrever “tenta de novo” no chat porque nada visível mudou. Cada um desses casos produz um segundo pedido que parece uma nova instrução. A menos que o sistema lembre do primeiro pedido, o segundo cria um segundo registro. Limites de taxa e regras de backoff decidem quando as novas tentativas acontecem, mas não decidem se uma nova tentativa é segura. Para isso, veja Limites de taxa para agentes de IA: regras de retry, backoff e fila.

Como desenhar a chave de idempotência?

A chave precisa responder a uma pergunta: “esta é a mesma ação de negócio de antes?” Um identificador aleatório gerado a cada chamada de ferramenta não consegue responder isso, porque cada tentativa recebe um novo. Uma chave construída a partir do evento de negócio consegue.

Chaves úteis combinam os campos que definem a ação. Alguns exemplos:

• Fatura: identificador do cliente, período do serviço e identificador do pedido original na conversa.
• Reserva: identificador do recurso, horário de início e cliente solicitante.
• Mensagem: destinatário, identificador do modelo e identificador do evento que disparou o envio.
• Atualização de pedido: identificador do pedido, o campo que será alterado e a versão que você espera substituir.

Mantenha a chave estável entre as tentativas e única entre ações diferentes. Guarde-a junto com o pedido, e não apenas no contexto do modelo, porque o contexto pode ser cortado ou perdido entre uma tentativa e outra.

Cenário ilustrativo: um cliente pede no chat para ser faturado pelos serviços de março. O agente chama a ferramenta de faturamento, o pedido expira depois que a fatura foi criada, e o agente tenta de novo. Sem chave, o cliente recebe duas faturas. Com uma chave construída a partir do cliente, do período do serviço e do identificador do pedido na conversa, a segunda chamada devolve a fatura que já existe.

Use primeiro o recurso de idempotência do fornecedor

Alguns sistemas de negócio já suportam idempotência. A Stripe, por exemplo, documenta requisições idempotentes: o cliente envia uma chave de idempotência junto com a escrita e, se a mesma requisição for repetida com essa chave, a API devolve o resultado guardado em vez de executar a ação de novo. O fornecedor armazena o resultado vinculado à chave, então a nova tentativa fica inofensiva. Leia a documentação do fornecedor para três pontos: se o recurso existe para o endpoint exato que você usa, por quanto tempo as chaves são respeitadas e se uma nova tentativa com a mesma chave, mas parâmetros diferentes, é recusada. Não presuma que o recurso exista para todos os endpoints de uma plataforma.

Muitos sistemas de negócio não têm esse recurso, ou o oferecem só para algumas operações. Essa verificação faz parte do planejamento. Se você não sabe o que um sistema expõe, comece por Como saber se meu sistema tem API: checagem rápida antes da IA. Quando o fornecedor oferece uma chave, passe a sua chave de negócio por ela. Quando não oferece, o seu próprio registro precisa fazer o trabalho.

Uma nova tentativa só é segura quando o sistema consegue reconhecer a primeira tentativa.

Crie um registro que o agente precisa consultar antes de cada escrita

Um registro é uma tabela simples ou um armazenamento de documentos que guarda cada tentativa de escrita, sua chave, seu status e o identificador externo devolvido pelo sistema de destino. Ele não precisa ser complicado. Precisa ser lido antes de cada escrita e gravado nos momentos certos.

Uma sequência prática para cada escrita:

• Passo 1: calcule a chave de negócio a partir dos dados do evento, antes de chamar qualquer ferramenta.
• Passo 2: procure a chave no registro.
• Passo 3: se o status for concluído, devolva o resultado guardado e não chame a ferramenta de novo.
• Passo 4: se o status for pendente ou desconhecido, não chame a ferramenta. Passe para a conciliação.
• Passo 5: se não existir registro, grave um registro pendente com a chave, o horário e o evento solicitante, e então chame a ferramenta.
• Passo 6: em caso de sucesso, guarde o identificador externo e marque o registro como concluído.
• Passo 7: diante de um erro claro e definitivo, marque o registro como falho para que uma nova tentativa corrigida seja permitida.

Registre cada passo. Logs que mostram qual chave foi usada, o que a ferramenta devolveu e quanto tempo a chamada levou tornam as tentativas duplicadas visíveis para quem revisa o sistema. O material de observabilidade da OpenTelemetry descreve a ideia geral de traces, logs e métricas que tornam o comportamento distribuído inspecionável, exatamente o que você precisa quando as novas tentativas do agente são a questão.

O que fazer quando o resultado é desconhecido

O caso mais difícil não é um sucesso claro nem uma falha clara. É um timeout, uma conexão caída ou uma resposta que não pode ser interpretada. O sistema pode ter feito ou não a escrita. A regra deve ser simples: desconhecido significa verificar, não repetir.

A conciliação funciona assim. Procure no sistema de destino pela chave, se o fornecedor a armazena, ou pelos campos de negócio que definem a ação: o cliente, o período, o horário. Se encontrar um registro correspondente, guarde o identificador e marque a tentativa como concluída. Se não encontrar nada após uma checagem definida, marque como falha e permita a nova tentativa. Se a própria busca falhar, mantenha o registro como desconhecido e encaminhe para uma pessoa. Um agente que não consegue acessar o sistema de destino não deve adivinhar. Para o padrão de recuperação mais amplo, incluindo o que o agente deve fazer quando o acesso em si expirou, leia O que um agente deve fazer quando uma conexão expira?.

Proteja mensagens, pagamentos e reservas de forma diferente

As três ações duplicadas mais comuns têm consequências diferentes, então precisam de controles diferentes.

• Mensagens: uma segunda mensagem fica visível para o destinatário e não pode ser desfeita. Guarde um registro de envio para cada mensagem de saída e exija revisão humana antes de qualquer reenvio.
• Pagamentos: um pagamento duplicado é um erro financeiro. Defina um limite rígido de valor que o agente pode iniciar, exija aprovação acima dele e mantenha as escritas de pagamento fora da saída livre do modelo. Os limites a definir primeiro estão em Agente de IA pode fazer pagamentos? Limites seguros para definir.
• Reservas: reserve o horário no registro antes de escrever na agenda, para que dois pedidos para o mesmo horário não possam ser aceitos juntos.
• Alterações de registro: use verificação de versão, para que uma atualização só seja aceita se o registro ainda tiver a versão que o agente leu. Uma nova tentativa atrasada então falha, em vez de sobrescrever dados mais recentes.

Para cada um desses casos, decida antes se o agente pode agir sozinho, se pode preparar a ação para aprovação ou se apenas pode relatar o que encontrou. Regras de nova tentativa e regras de aprovação devem ser escritas juntas, e não em documentos separados.

Teste as novas tentativas antes de confiar nelas

Idempotência é uma afirmação sobre o comportamento sob falha, então teste os casos de falha. Testes úteis incluem enviar a mesma requisição três vezes seguidas e confirmar que existe um único registro. Simule um timeout depois que o sistema de destino já salvou a escrita e confirme que a conciliação a encontra, sem criar outra. Altere um único campo, como o período do serviço, e confirme que uma nova chave é gerada. Rode os mesmos testes em um ambiente de sandbox antes de conectar sistemas de produção. Avaliações recorrentes são uma forma padrão de manter esses testes relevantes ao longo do tempo; a abordagem é descrita nas orientações da Anthropic sobre avaliações para agentes de IA.

A Be Human desenha e opera esse tipo de controle como parte de um serviço gerenciado. Em uma primeira etapa, a equipe define quais escritas precisam de chaves de negócio e registros, estabelece os limites de aprovação para mensagens e pagamentos e combina um critério de sucesso observável, como zero registros duplicados em um conjunto de testes definido. Na operação contínua, o monitoramento observa chaves repetidas e estados desconhecidos, as permissões são revisadas conforme os sistemas mudam e os incidentes são tratados com um registro escrito de conciliação. O serviço é remoto, em inglês e em português, e não depende de o cliente montar antes uma equipe interna de plataforma.

O primeiro passo útil é listar todas as escritas que seus agentes poderiam executar e marcar quais delas poderiam ser repetidas por acidente. O diagnóstico gratuito de IA da Be Human pode ajudar a encontrar a primeira tarefa que vale entregar a um agente, e as regras de segurança contra duplicidade acima devem fazer parte dessa decisão desde o início.

Perguntas frequentes

Idempotência significa que o agente nunca pode errar? Não. A idempotência evita uma falha específica, que é executar a mesma escrita duas vezes porque uma nova tentativa foi enviada. Ela não verifica se a escrita era a correta, se o valor está certo ou se o cliente queria aquilo. Essas perguntas exigem limites de aprovação, validação de entradas e revisão.

E se o sistema de destino não suportar chaves de idempotência? Construa a verificação no seu próprio registro. Guarde a chave de negócio e o identificador externo devolvido pelo sistema, e consulte o registro antes de cada escrita. Quando o sistema puder ser pesquisado pelos campos de negócio, use essa busca na conciliação antes de qualquer nova tentativa.

Posso simplesmente pedir ao modelo que não repita a ação? Instruções ajudam, mas não são um controle. Um modelo pode perder o rastro das tentativas anteriores, um timeout pode acontecer fora da visão dele e um framework pode repetir automaticamente. A segurança precisa estar na camada de ferramentas, onde a checagem de registro e de chave roda independentemente do que o modelo decidir.

Por quanto tempo um registro deve guardar as informações? Mantenha-as pelo tempo que suas necessidades de conciliação, auditoria e contestação exigirem, e defina esse período junto com os responsáveis por finanças e operações. O objetivo é que uma nova tentativa, dias depois, ainda possa ser reconhecida. O acesso a esses registros deve seguir as mesmas regras de menor privilégio do restante dos dados do agente.

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