Chamadas idempotentes em agentes de IA: como evitar pedidos duplicados
Torne as chamadas de agentes de IA idempotentes com chave de requisição, resultado salvo e consulta antes de gravar. Nova tentativa não gera segundo pedido.

Uma chamada idempotente produz o mesmo resultado não importa quantas vezes a mesma requisição chegue ao seu sistema. Para um agente de IA, isso significa que uma nova tentativa após um timeout, uma instrução repetida ou um fluxo reiniciado reaproveita o resultado do primeiro pedido, fatura ou agendamento, em vez de gravar um segundo. A solução prática tem três partes: uma chave estável criada antes da primeira tentativa, um registro do que essa chave produziu e uma verificação contra esse registro antes de qualquer gravação.
Principais pontos
- Crie a chave de idempotência uma vez, antes da primeira tentativa, e reutilize-a em toda nova tentativa da mesma intenção de negócio.
- Guarde a chave ao lado do resultado no seu próprio sistema, para que uma chamada repetida devolva o resultado original em vez de gravar de novo.
- Consulte registros existentes antes de criar qualquer coisa, porque a janela de chaves de um provedor pode ser mais curta que o seu fluxo.
- Trate timeout como resultado desconhecido, não como falha. Verifique o estado antes de tentar de novo.
- Derive as chaves da ação de negócio, não da redação do modelo, para que duas formulações do mesmo pedido virem uma única gravação.
Por que novas tentativas criam pedidos duplicados
Duplicidades raramente vêm de uma decisão ruim isolada. Elas vêm da ambiguidade. Um agente envia uma chamada create_order, a resposta se perde na rede, e o harness do agente trata a ausência de resposta como falha. O pedido pode já existir do outro lado. O harness então tenta de novo, e a segunda chamada cria um segundo pedido com novo identificador. Nada nos logs parece errado, porque cada requisição era válida.
Existe um segundo caminho. O modelo pode decidir de novo, em um novo turno, que o cliente quer o pedido feito. Se a nova requisição trouxer um texto levemente diferente, outro carimbo de tempo ou itens reordenados, um sistema ingênuo enxerga uma requisição nova. Novas tentativas e recálculos são comportamentos normais de agentes, então a própria ferramenta de escrita precisa ser construída para absorvê-los.
O mesmo padrão aparece com faturas enviadas duas vezes, agendamentos que entram duas vezes na agenda e reembolsos emitidos em duplicidade. O endpoint de escrita não é o único lugar para corrigir isso. A correção pertence ao contrato da ferramenta, ao estado armazenado e às regras que o agente segue quando um resultado não está claro.
O que a chave de idempotência deve identificar
A chave deve identificar a ação de negócio, não a tentativa. Um identificador aleatório gerado a cada chamada anula o propósito, porque toda nova tentativa parece nova. Uma chave montada a partir do texto livre do modelo também é fraca, porque a redação muda de um turno para outro.
Uma boa chave combina os fatos estáveis que definem a intenção. Em um pedido, isso costuma significar o identificador do cliente, o identificador do orçamento ou carrinho, uma impressão digital dos itens e o tipo de ação. Por exemplo, uma chave formada por pedido, cliente, orçamento e uma versão pode ser construída com campos que o agente recebe do seu sistema, não da conversa. Se o mesmo orçamento for aceito duas vezes, a chave é a mesma, e a segunda chamada devolve o primeiro pedido.
A chave também deve ser armazenada junto com o conteúdo da requisição. Se a mesma chave chegar com conteúdo diferente, a ferramenta deve recusar a chamada e informar um conflito, porque alguém ou algo mudou a intenção. Devolver silenciosamente o resultado antigo nesse caso esconde um problema real.
Plano passo a passo para tornar uma ferramenta de escrita idempotente
Use esta sequência para qualquer ferramenta que crie pedido, fatura, agendamento ou registro. Cada passo é pequeno, e cada um pode ser revisado pela pessoa responsável pelo processo.
- Passo 1: liste cada ação de escrita que o agente pode executar e nomeie o objeto de negócio que cada uma cria ou altera.
- Passo 2: para cada ação, defina os campos que tornam duas requisições a mesma intenção, e registre-os como receita da chave.
- Passo 3: crie uma tabela ou armazenamento, controlado pelo seu sistema e não pelo modelo, que guarde a chave, um hash do conteúdo, o status e o identificador resultante.
- Passo 4: antes de qualquer escrita, consulte a chave. Se existir um registro concluído, devolva-o. Se existir um registro pendente, devolva status pendente e não crie nada.
- Passo 5: grave primeiro o registro pendente, chame o sistema externo com a chave, quando o provedor suportar, e depois atualize o registro para concluído ou falho, com o identificador externo.
- Passo 6: devolva a mesma resposta estruturada em uma chamada repetida, para que o agente continue sem inventar uma nova ação.
- Passo 7: registre cada tentativa duplicada e cada conflito, e revise-os na avaliação recorrente.
A ordem dos passos importa. Gravar um registro pendente antes da chamada externa significa que uma falha no meio do caminho deixa evidência. Sem isso, a próxima tentativa não tem com o que comparar.
Como tratar timeouts e resultados desconhecidos
O timeout é o caso em que a idempotência mostra seu valor. O agente não sabe se a escrita aconteceu. A regra deve ser simples: nunca repita uma escrita às cegas. Primeiro leia o estado. Consulte o seu próprio registro pela chave e, se ele estiver pendente, consulte o sistema externo por um objeto vinculado àquela chave ou ao identificador do orçamento.
A idempotência definida pelo provedor é útil, mas não basta sozinha. Provedores de pagamento como o Stripe documentam chaves de idempotência em suas APIs, de modo que uma requisição repetida com a mesma chave devolve o resultado da requisição original, em vez de criar uma nova cobrança. É um bom bloco de construção. Porém, as chaves são retidas por um período limitado, o provedor só conhece o próprio endpoint, e o seu fluxo pode atravessar vários sistemas. O registro próprio armazenado é o que permite ao agente raciocinar sobre a ação de negócio inteira.
Quando a própria consulta falha, o agente deve parar e escalar, em vez de adivinhar. Uma pessoa aprovadora pode então confirmar se o pedido existe antes que qualquer outra coisa seja gravada. Essa única regra evita a maior parte das duplicidades caras.
Um cenário ilustrativo
O cenário a seguir é ilustrativo e não descreve uma empresa específica. Uma pequena distribuidora deixa um agente converter orçamentos aceitos em pedidos de venda. Um cliente confirma o orçamento 1042 por e-mail. O agente chama create_order. A chamada sofre timeout depois que o pedido foi gravado, então o harness informa erro e o agente tenta de novo.
Sem chave, a segunda chamada cria um segundo pedido, e o armazém prepara dois envios. Com a chave montada a partir do cliente, do orçamento e de uma impressão digital das linhas, a primeira chamada deixou um registro concluído. A nova tentativa encontra esse registro e devolve o identificador original do pedido. O agente então confirma ao cliente que o pedido está confirmado, e o armazém vê um único envio. Se a primeira chamada tivesse ficado pendente, a ferramenta devolveria status pendente, e o agente pediria a uma pessoa que verificasse antes de qualquer outra escrita.
Como a Be Human trata isso em operações gerenciadas
A Be Human desenha essas regras já na primeira etapa, normalmente com um papel útil e uma ação de escrita por vez. A receita da chave, o registro armazenado e a sequência de consulta antes de gravar entram no contrato da ferramenta, para que o agente não consiga pulá-los. Os limites de aprovação definem quais escritas precisam de uma pessoa para confirmar um estado pendente ou conflitante. Em operações gerenciadas, a Be Human acompanha novas tentativas, duplicidades e conflitos, revisa esses casos em avaliações recorrentes e atualiza a receita da chave quando um processo de negócio muda. O objetivo é que uma nova tentativa seja um evento de rotina, e não um incidente.
Como testar se as novas tentativas são seguras?
Os testes devem tentar criar duplicidades de propósito. Um teste que só executa o caminho feliz não prova nada sobre novas tentativas. As verificações abaixo são simples o bastante para rodar antes de qualquer agente receber acesso de escrita, e para repetir após cada mudança na ferramenta.
- Envie a mesma requisição de criação duas vezes em sequência e confirme que existe apenas um objeto de negócio.
- Envie duas requisições idênticas quase ao mesmo tempo e confirme que a segunda espera ou se junta à primeira.
- Simule um timeout depois que a escrita externa teve sucesso e confirme que a nova tentativa devolve o identificador original.
- Envie a mesma chave com conteúdo alterado e confirme que a ferramenta devolve conflito, em vez de um sucesso silencioso.
- Altere a redação do pedido do cliente, mas não o orçamento, e confirme que a chave continua a mesma.
- Confirme que dois orçamentos diferentes do mesmo cliente geram duas chaves diferentes.
Guarde os resultados em um registro compartilhado que o responsável pelas operações consiga ler. Um resultado claro de aprovado ou reprovado é mais útil que um relatório técnico longo. Antes de alterar ferramentas em produção, vale ler o artigo sobre ações idempotentes em agentes de IA, que cobre o padrão mais amplo, e o texto sobre limites de API para agentes de IA, que explica como o tempo de novas tentativas e as filas devem conversar com as chaves. Para o próprio esquema, as notas sobre esquema de ferramentas para agentes de IA mostram como nomear e tipar os campos da chave para que o agente não envie entradas ambíguas.
Se você ainda não sabe qual das suas ações de escrita deve receber essa proteção primeiro, o diagnóstico gratuito da Be Human pode ajudar a encontrar a primeira tarefa que vale entregar a um agente.
Perguntas frequentes
A chave de idempotência impede que um agente crie o mesmo pedido duas vezes se ele redigir o pedido de outra forma? Sim, desde que a chave seja montada a partir de fatos do negócio, como cliente, orçamento e itens, e não da redação do modelo. O texto do agente é uma entrada da decisão, não a identidade da ação. A ferramenta deve derivar a chave dos campos estruturados que recebe e recusar qualquer chamada que tente reutilizar uma chave com conteúdo diferente.
O que um agente de IA deve fazer quando uma chamada de ferramenta sofre timeout? Ele não deve repetir a escrita imediatamente. Primeiro deve ler o registro armazenado da chave e, se ele estiver pendente, consultar o sistema externo por um objeto vinculado à chave ou ao documento de origem. Só quando o sistema confirmar que nada foi criado a escrita deve ser executada de novo. Se o estado continuar incerto, o agente deve parar e escalar para uma pessoa nomeada.
Posso confiar apenas no recurso de idempotência do provedor de pagamentos ou do ERP? Os recursos do provedor são valiosos, mas geralmente cobrem apenas o próprio endpoint e apenas por uma janela limitada. Seu fluxo pode envolver um e-mail, um orçamento, um registro no armazém e um lançamento contábil, e o provedor não enxerga todos eles. Mantenha um registro próprio da chave e do resultado, e use o mecanismo do provedor como camada adicional, não como a única.
Idempotência é o mesmo que limitação de taxa? Não. A limitação de taxa controla a velocidade com que as requisições são enviadas e como o sistema responde quando está ocupado. A idempotência controla o que acontece quando a mesma intenção é enviada mais de uma vez. Um agente bem projetado precisa das duas coisas: limites de taxa e tempo de novas tentativas para evitar sobrecarga, e escritas idempotentes para que uma nova tentativa seja inofensiva quando acontecer.
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.


