Ações idempotentes em agentes de IA: evite reservas e faturas duplicadas
Veja como chaves de idempotência impedem que uma nova tentativa do agente de IA crie reserva, fatura ou registro duplicado, com plano passo a passo.

Uma ação idempotente é uma escrita que produz o mesmo resultado de negócio, não importa quantas vezes a mesma solicitação chegue ao sistema. Para impedir que uma nova tentativa crie uma reserva, fatura ou registro duplicado, o agente envia uma chave de idempotência estável junto com cada intenção de negócio. O sistema que recebe a escrita guarda essa chave ao lado do resultado e devolve o resultado guardado para qualquer repetição. Assim, as novas tentativas viram consultas seguras, e não segundas escritas.
Principais pontos
- Novas tentativas são normais. Timeouts, conexões interrompidas e respostas pouco claras vão acontecer, então o agente precisa ser desenhado para reenviar com segurança.
- A chave de idempotência pertence à intenção de negócio, não a uma tentativa isolada. A mesma solicitação de reserva mantém a mesma chave do primeiro envio até a última repetição.
- A checagem precisa acontecer no sistema que guarda o registro, porque só ele consegue dizer se uma escrita já existe.
- Registre a chave, o resultado e o responsável por cada escrita, para que uma duplicidade seja encontrada e revertida rapidamente.
- Dê às respostas incertas um caminho de revisão humana, em vez de deixar o agente adivinhar se a primeira tentativa funcionou.
Por que as novas tentativas criam duplicidades
Agentes chamam ferramentas por redes, e redes não são confiáveis. O agente envia uma requisição para criar uma reserva, o sistema de agendamento salva a reserva, e a resposta se perde no caminho de volta. Do lado do agente, o resultado é desconhecido. Um agente cuidadoso vai tentar de novo, e um agente ingênuo pode criar uma segunda reserva. Os dois comportamentos fazem sentido dentro do ciclo do agente, e é por isso que duplicidades são um problema de desenho, e não um problema do modelo.
O mesmo padrão aparece com faturas, pedidos de compra, cadastros de clientes, chamados de suporte e reembolsos. Qualquer ferramenta que cria algo novo está exposta. Ferramentas que apenas leem dados, ou que definem um campo com um valor fixo, são bem menos arriscadas, porque repeti-las não altera nada que importe para o negócio.
Novas tentativas também vêm de outras fontes além da rede. Um processo de trabalho pode reiniciar no meio de uma tarefa. Uma pessoa pode reexecutar um fluxo a partir de um painel. Uma fila pode reentregar uma mensagem que não tinha certeza de ter sido confirmada. Um desenho idempotente deve partir do princípio de que qualquer escrita pode chegar duas vezes, por qualquer uma dessas fontes.
Para a pergunta mais ampla sobre quando um agente deve tentar de novo, leia Política de repetição para agentes de IA sem duplicidades. Este artigo trata do problema mais estreito de tornar a própria escrita segura para repetir.
Como escolher a chave de idempotência?
A chave deve identificar o que o negócio quer que aconteça, não o momento em que a solicitação foi enviada. Um erro comum é gerar um identificador aleatório a cada tentativa. Isso dá a cada repetição uma chave nova, e o sistema que recebe trata cada repetição como um pedido novo. A proteção desaparece.
Uma chave viável é derivada dos campos que definem a intenção. Em uma reserva, por exemplo, pode ser a combinação do identificador do cliente, do recurso, do horário de início e da solicitação que originou a reserva, reunidos em um valor estável. O agente gera a chave uma vez, quando decide agir, guarda a chave no estado da tarefa e a reutiliza em cada nova tentativa dessa decisão.
Mantenha a chave estável mesmo quando o modelo, o prompt ou a versão da ferramenta mudarem. Se o agente for atualizado no meio de uma tarefa, a repetição ainda deve carregar a chave original. Caso contrário, uma mudança de versão pode criar silenciosamente uma duplicidade que a chave antiga teria bloqueado.
Guarde a chave no registro da tarefa antes da primeira chamada. Se o agente cair depois de enviar a escrita, mas antes de salvar a chave, ele não encontra a tentativa anterior ao reiniciar. A mesma disciplina vale para qualquer tarefa longa, como descrito em Checkpoints em tarefas longas de agente de IA: retomar sem refazer.
Onde a checagem de duplicidade deve acontecer?
O agente não pode ser o único ponto onde duplicidades são evitadas. Ele sabe apenas o que lembra, e sua memória pode estar incompleta depois de um reinício ou de um reset de contexto. A checagem pertence ao sistema que é dono do registro, porque ele mantém a lista oficial do que já foi escrito.
Muitas plataformas de pagamento e de APIs já funcionam assim. A Stripe, por exemplo, documenta um mecanismo de idempotência em que o cliente envia uma chave única junto com a requisição, e a plataforma devolve o resultado da primeira requisição para qualquer repetição enviada com a mesma chave dentro de um intervalo definido. O princípio vale para ferramentas internas. Se o seu sistema de reservas, cobrança ou clientes aceita uma chave, use-a. Se não aceita, a escrita precisa de uma consulta antes da criação, feita sobre os mesmos campos de negócio que formaram a chave.
Quando o sistema de destino não tem suporte nativo, construa uma camada intermediária fina entre o agente e a escrita. Essa camada registra cada chave, uma impressão digital da requisição e o identificador do registro resultante, em um armazenamento próprio. Uma repetição com a mesma chave devolve o identificador guardado. Uma repetição com a mesma chave, mas conteúdo diferente, é rejeitada e escalada, porque essa combinação costuma indicar um erro na forma como a chave ou a requisição foram montadas.
A camada intermediária também aplica permissões. Ela deve autenticar o agente e limitar quais tipos de registro o agente pode criar. O guia da OWASP sobre autorização é um checklist prático para essa camada, e deve ser revisado sempre que o escopo do agente mudar.
Plano passo a passo para uma ação de escrita
Use esta sequência para qualquer ação do agente que crie ou altere um registro de negócio.
- Defina a intenção em uma frase que um gestor aprovaria, como a reserva solicitada por um cliente para um horário específico.
- Derive a chave de idempotência dos campos que definem essa intenção e gere a chave uma única vez.
- Grave a chave e a ação planejada no registro da tarefa antes de chamar a ferramenta.
- Envie a escrita com a chave, e nunca deixe a chave existir apenas nos logs.
- Em caso de sucesso, guarde o identificador retornado associado à chave e marque o passo como concluído.
- Em caso de timeout ou erro sem resultado claro, tente de novo com a mesma chave, nunca com uma nova.
- Se a mesma chave devolver um resultado que não corresponde à intenção guardada, pare e escale em vez de tentar outra vez.
- Quando as tentativas se esgotarem, entregue a decisão a uma pessoa com a chave, a intenção e o resultado da consulta, seguindo a abordagem de Escalonamento humano em IA: entregue a decisão necessária.
Cenário ilustrativo: uma reserva que expirou
O cenário a seguir é ilustrativo e não descreve um cliente real. Um agente de agendamento de uma clínica recebe o pedido para marcar uma consulta de retorno para um paciente em uma terça-feira de manhã. Ele monta a chave a partir do identificador do paciente, do tipo de consulta e do horário solicitado, e então chama a API de agendamento. A requisição chega ao sistema e o horário é salvo, mas a resposta expira antes de o agente receber a confirmação.
Sem chave, o agente vê o timeout e tenta de novo, e a segunda chamada cria um segundo agendamento no mesmo horário. A equipe só percebe quando o paciente chega e encontra duas marcações. Com a chave, a repetição carrega o mesmo valor, o sistema de agendamento encontra o registro existente e devolve o identificador dele. O agente marca o passo como concluído e envia a confirmação. Nada foi escrito duas vezes.
O cenário tem um segundo ramo que vale planejar. Se o agente tivesse sido atualizado entre a primeira tentativa e a repetição, a nova versão poderia montar a chave de forma diferente da guardada. A regra é reutilizar a chave salva no registro da tarefa e nunca reconstruí-la do zero. Um revisor que lesse o log veria uma chave, uma reserva e uma repetição marcada como reprocessamento.
O que registrar e quem revisa?
A idempotência só funciona se alguém conseguir vê-la funcionando. Para cada escrita, registre a chave, a intenção em linguagem simples, o resultado, se o resultado foi novo ou um reprocessamento, e o identificador do registro criado. Esses campos permitem que o responsável responda a pergunta mais importante depois de um incidente: marcamos isso uma vez ou duas?
Defina uma regra de revisão para reprocessamentos e conflitos. Um reprocessamento é normal e precisa aparecer apenas como contagem no resumo regular. Um conflito, em que a mesma chave chega com conteúdo diferente, deve chegar no mesmo dia à pessoa responsável por aquele processo. Ela decide se o agente ou os dados de origem estão errados. Os logs de monitoramento que capturam esses campos são descritos em Observabilidade de agentes de IA: o que registrar?, e o vocabulário de traces e eventos está resumido no material introdutório de observabilidade do OpenTelemetry.
Mantenha a regra visível para a equipe que usa o agente. Se a recepção vê um sinal de reprocessamento em uma reserva, ela consegue explicar uma segunda mensagem de confirmação sem abrir um chamado. Um registro simples do que mudou e por quê também ajuda, como mostra Agentes de IA precisam de um registro de mudanças que o dono entenda.
Como a Be Human trata isso na operação gerenciada
A Be Human trata a idempotência como parte do contexto operacional do agente e a configura antes de o agente receber permissão de escrita. O trabalho começa listando quais ferramentas criam registros, quais apenas leem e quais campos definem cada intenção de negócio. As permissões do agente são limitadas aos tipos de registro de que ele precisa. Chaves, regras de repetição e escalonamentos de conflito são escritos no runbook do agente. Na operação gerenciada, as contagens de reprocessamentos e conflitos são revisadas em uma rotina recorrente, e as permissões são verificadas de novo sempre que uma ferramenta, um modelo ou um fluxo mudar. Quando uma escrita incerta precisa de uma pessoa, o escalonamento leva a chave, a intenção e o resultado da consulta, para que o responsável decida sem reconstruir a tarefa.
Se você não tem certeza de quais ações do seu agente podem ser repetidas com segurança hoje, faça o diagnóstico gratuito de IA da Be Human para encontrar a primeira tarefa que vale entregar a um agente.
Perguntas frequentes
Uma chave de idempotência impede todas as duplicidades? Não. A chave impede duplicidades que vêm de repetições da mesma intenção, mas não consegue impedir duas intenções separadas que uma pessoa ou um processo envia de propósito. Esses casos precisam de regras de negócio, como uma verificação de reserva existente no mesmo horário, e de um caminho de revisão para qualquer coisa que pareça um segundo pedido.
O agente pode gerar uma chave nova a cada nova tentativa? Não deveria. Uma chave nova em cada tentativa impede que o sistema reconheça a repetição como o mesmo pedido, e a proteção se perde. A chave deve ser criada uma vez para a intenção, guardada no registro da tarefa e reutilizada em todas as repetições.
E se o sistema de destino não tiver suporte a idempotência? Construa uma camada intermediária que guarde cada chave, uma impressão digital da requisição e o identificador do registro resultante. Faça as escritas do agente passarem por essa camada, para que toda repetição seja checada antes de qualquer criação. Limite também o que o agente pode criar nessa mesma camada, já que ela é o lugar natural para as verificações de permissão.
Toda ação do agente precisa ser idempotente? Ações de leitura geralmente não precisam, porque repeti-las não altera nada. Comece pelas escritas que criam compromissos ou movimentam dinheiro, como reservas, faturas, reembolsos e registros que outras equipes utilizam, e estenda o padrão a outras escritas conforme o escopo do agente crescer.
Seu próximo passo
Descubra primeiro onde um agente de IA cabe na sua empresa.
Faça o diagnóstico gratuito de IA da Be Human. Algumas perguntas sobre o seu trabalho mostram qual tarefa entregar primeiro a um agente, o que ele precisa saber e onde uma pessoa aprova.
Orientação editorial Be Human. Exemplos são ilustrativos, salvo atribuição explícita. Fontes oferecem contexto; a implementação depende do seu processo.


