Como evitar gravações duplicadas na API quando agentes de IA repetem solicitações

Agentes de IA cometem erros de retry mais rápido do que as pessoas. Quando vê um timeout, uma pessoa pode parar, verificar a fila de chamados e decidir o que aconteceu. Um agente costuma ver uma exceção, seguir uma instrução para tentar novamente e enviar uma segunda gravação antes que a primeira solicitação tenha terminado em algum ponto além da fronteira da rede.

Esse comportamento cria chamados duplicados, tentativas repetidas de pagamento, convites duplicados para usuários e duas implantações da mesma alteração. A solução não é dizer ao agente para ter cuidado. Você precisa de um contrato de API que preserve a identidade de uma única ação pretendida entre retries, detecte alterações escondidas atrás de um identificador reutilizado e peça uma nova confirmação humana quando a consequência justificar isso.

Retries são normais, efeitos duplicados são opcionais

Um timeout não significa que o servidor não fez nada. O servidor pode ter criado o chamado e perdido a resposta no caminho de volta. Também pode ainda estar processando a solicitação. Um balanceador de carga pode ter aceitado a conexão enquanto o serviço upstream nunca recebeu os bytes. O cliente não pode deduzir o resultado a partir de um erro de socket.

Por isso, a instrução comum para agentes, «tente novamente em caso de erros de rede», é incompleta. Ela trata todo resultado incerto como uma ação malsucedida. Para endpoints de gravação, um resultado incerto tem três estados possíveis:

• o servidor não recebeu a solicitação
• o servidor aceitou a solicitação e concluiu o trabalho
• o servidor aceitou a solicitação, mas ainda não a concluiu

O mesmo retry deve ser seguro nos três estados. Se ele criar um segundo efeito no estado concluído, o endpoint tem uma fronteira de retry insegura.

O HTTP não resolve isso por você. A RFC 9110 define métodos idempotentes como aqueles cujo efeito pretendido permanece igual depois de uma ou mais solicitações idênticas. Ela cita PUT, DELETE e os métodos seguros. A RFC também diz que um cliente pode repetir uma solicitação idempotente depois de uma falha de comunicação. Isso é útil, mas não torna seguro todo endpoint que usa uma rota PUT. Um servidor pode associar entrega de e-mail, emissão de crédito ou acionamento de uma implantação a um handler PUT e repetir esse efeito colateral se não tiver sido projetado para evitá-lo.

O POST precisa de um acordo explícito. Muitas APIs usam POST para ações porque o servidor atribui identificadores aos recursos ou porque a solicitação significa «execute esta operação de negócio». Um agente só pode repetir essa solicitação quando a API explica como identificar uma única operação entre várias tentativas.

Separe retries de transporte de retries de negócio. Um retry de transporte reenvia a mesma operação porque o resultado continua desconhecido. Um retry de negócio inicia outra operação porque a primeira chegou a uma falha terminal conhecida. Confundir os dois produz o relatório clássico de incidente: o agente repetiu com sucesso, duas vezes.

Um token de idempotência identifica uma única ação pretendida

Um token de idempotência é um identificador opaco gerado pelo cliente que significa «todas as solicitações com este valor são tentativas de executar esta ação». O agente o cria antes da primeira solicitação, persiste o valor junto ao estado da tarefa e envia exatamente o mesmo token em cada retry.

O token deve pertencer à ação lógica, não a uma tentativa HTTP. Se um agente cria um chamado de suporte, perde a resposta e faz outra solicitação com um token novo, a API não tem como reconhecer um retry. Ela deve criar um segundo chamado, porque o chamador informou que essa era uma segunda operação.

Use um valor aleatório com alta entropia. Um UUID é comum, mas qualquer formato funciona se os chamadores não puderem adivinhar os valores e o servidor tratar o token como opaco. Coloque-o em um cabeçalho Idempotency-Key ou em um campo documentado da solicitação. Um cabeçalho mantém a identidade da operação separada do conteúdo de negócio e facilita seu transporte por middleware, logs e rastreamento.

Uma solicitação prática é assim:

curl -X POST https://api.example.test/v1/tickets \\
  -H 'Authorization: Bearer $TOKEN' \\
  -H 'Content-Type: application/json' \\
  -H 'Idempotency-Key: 81b59b1a-9e75-4de7-a53b-1bb50969c83c' \\
  -d '{"project":"ops","title":"Rotate staging certificate","priority":"high"}'

Na primeira chamada aceita, o servidor registra o token, uma impressão digital canônica da solicitação, o estado da operação e, por fim, a resposta que será repetida. Se uma solicitação posterior trouxer o mesmo token e a mesma impressão digital, o servidor devolverá o resultado anterior em vez de criar outro chamado.

O cliente precisa de um local durável para guardar o token. Um agente que o armazena apenas no prompt atual ou na memória do processo perde a identidade da operação depois de uma reinicialização. Guarde-o junto ao registro da tarefa, do trabalho ou do checkpoint do fluxo. Se uma pessoa pedir ao agente que crie um segundo chamado, deliberadamente separado, com o mesmo texto, o agente deve gerar um token novo, porque a pessoa expressou uma nova intenção.

Não faça o token ser igual ao nome mutável de uma tarefa, a um timestamp ou a uma solicitação em linguagem natural. Esses valores podem colidir, mudar entre retries ou expor informações nos logs. Identificadores opacos são sem graça. É exatamente por isso que funcionam.

Uma impressão digital detecta retries alterados

O token indica se o chamador afirma que duas solicitações são uma única operação. A impressão digital da solicitação indica se elas realmente significam a mesma coisa. Você precisa dos dois.

Suponha que um agente peça primeiro a uma API de implantação para enviar o commit a1b2c3 para staging. A solicitação sofre timeout, o agente lê uma nota de tarefa mais recente e repete a chamada com o mesmo token, mas com o commit d4e5f6. Se o servidor repetir cegamente a primeira resposta, esconderá um erro do agente. Se executar o segundo corpo, permitirá que um identificador de operação autorize duas implantações diferentes.

Normalize as partes relevantes da solicitação e faça hash do resultado. A maioria das APIs inclui o método HTTP, uma rota normalizada, a conta ou o tenant autenticado e o corpo JSON canônico. Algumas incluem determinados cabeçalhos quando eles alteram o efeito de negócio. Exclua cabeçalhos variáveis de rastreamento, metadados de conexão e o próprio cabeçalho de idempotência.

JSON exige cuidado. Hashes dos bytes brutos falham quando um JSON equivalente usa outra ordem de propriedades ou espaços diferentes. Uma representação canônica ordena as propriedades dos objetos, preserva a ordem dos arrays, usa um formato numérico definido e omite campos atribuídos pelo servidor. Melhor ainda é criar a impressão digital do objeto de comando validado depois que a API analisa os valores padrão e rejeita campos desconhecidos. Assim, ela corresponde à operação que o servidor executará, não a uma codificação de entrada arbitrária.

Por exemplo, este pseudocódigo registra um resumo depois da validação:

command = validate_create_ticket(request.body)
canonical = canonical_json({
  "method": "POST",
  "route": "/v1/tickets",
  "account_id": authenticated_account.id,
  "command": command
})
fingerprint = sha256(canonical)

Quando um token já existir, compare as impressões digitais antes de devolver ou aguardar qualquer resultado anterior. Se forem diferentes, rejeite a solicitação com uma resposta de conflito. Inclua o identificador e o estado da operação armazenados, mas não repita detalhes protegidos da solicitação para um chamador não autorizado.

Uma impressão digital, sozinha, não detecta duplicatas. Duas pessoas podem abrir legitimamente dois chamados idênticos. Um serviço de folha de pagamento pode emitir legitimamente pagamentos iguais para dois funcionários. Fazer hash de um conteúdo e eliminar toda correspondência descarta silenciosamente trabalhos válidos. Limite a deduplicação ao token de idempotência e use regras de unicidade específicas do negócio quando o domínio realmente exigir isso.

Hashes criptográficos tornam colisões acidentais impraticáveis quando você usa uma função moderna, como SHA-256. Eles não comprovam a intenção do chamador. O token carrega a intenção; a impressão digital impõe consistência. Equipes que tratam os dois como intercambiáveis costumam terminar com uma regra de deduplicação que não conseguem explicar quando ela rejeita uma solicitação legítima.

O servidor precisa reivindicar o token antes de agir

Uma tabela de idempotência que registra resultados apenas depois que o efeito colateral termina ainda tem uma condição de corrida. Dois retries simultâneos podem consultar a tabela, não encontrar nada, criar dois chamados e depois disputar o armazenamento do resultado. Já vi isso ser tratado como um problema instável do agente quando o defeito real era a ausência de uma restrição de unicidade.

O servidor precisa reivindicar o token de forma atômica antes de executar um trabalho irreversível. Coloque uma restrição de unicidade no escopo e no token, normalmente um identificador de conta junto ao token de idempotência. Em uma única transação, tente inserir uma linha com a impressão digital e o estado in_progress. A solicitação vencedora assume a execução. Todas as outras leem a linha existente.

Uma tabela simplificada pode conter estes campos:

create table idempotency_operations (
  account_id text not null,
  token text not null,
  fingerprint text not null,
  state text not null,
  response_status integer,
  response_body jsonb,
  created_at timestamptz not null,
  primary key (account_id, token)
);

A chave primária faz um trabalho real aqui. O código da aplicação que consulta primeiro e insere depois deixa uma abertura grande o suficiente para que workers concorrentes, redelivery de filas e retries impacientes passem por ela.

Depois de reivindicar o token, o handler executa a ação de negócio e grava a resposta final na linha da operação. Solicitações posteriores correspondentes recebem esse status e esse corpo salvos. Assim, os chamadores obtêm uma resposta estável, mesmo quando o handler original já teve sucesso, mas a conexão caiu antes que pudesse responder.

O caso mais difícil é uma solicitação que possui uma linha, mas morre no meio do trabalho. Não exclua a linha apenas porque um worker sofreu timeout. Outro worker pode ainda estar terminando, ou o provedor externo pode já ter aceitado a operação. Marque a operação como pendente ou desconhecida, registre dados suficientes para investigação e permita que os chamadores consultem seu status. Um trabalho de reparo só deve resolver registros antigos quando entender o estado do sistema downstream.

Para trabalhos que atravessam um banco de dados e uma API externa, use o padrão outbox ou um token de idempotência fornecido pelo provedor. Uma transação de banco não consegue desfazer um e-mail, pagamento ou implantação na nuvem depois que ele deixa o seu processo. Grave a intenção e um evento outbox em uma única transação local e, depois, faça um worker enviar o evento com um identificador estável de operação downstream. Esse desenho dá ao código de recuperação algo concreto para repetir sem inventar uma segunda ação.

A confirmação deve estar vinculada à operação exata

A confirmação humana evita outro tipo de falha: um agente pode ter permissão para agir, mas a ação proposta pode ser surpreendente, ampla demais ou repetida depois que o contexto mudou. Um botão genérico «permitir implantação» não resolve isso. Ele permite que um agente substitua uma implantação por outra usando a mesma aprovação.

Uma confirmação útil nomeia o destino, a operação, a consequência e o identificador da operação. Em uma implantação de produção, mostre o ambiente, o artefato ou a referência do commit, o serviço afetado e se a ação pode ser revertida. Em um pagamento, mostre o beneficiário, o valor, a moeda e a referência da fatura. Em um chamado, mostre o projeto de destino e o título.

O registro de confirmação deve estar vinculado à impressão digital da solicitação e expirar quando a proposta deixar de ser atual. Se o agente alterar o corpo depois que uma pessoa o aprovar, a impressão digital mudará e o sistema deverá pedir confirmação novamente. Reutilizar uma aprovação depois de uma alteração silenciosa da solicitação é uma forma de escalada de privilégios, mesmo quando ninguém pretendia isso.

Não obrigue uma pessoa a aprovar todo retry de baixo risco. Isso transforma um desenho correto de idempotência em fadiga de aprovação. A primeira aprovação pode autorizar a operação de uma única impressão digital, e retries correspondentes podem usar essa aprovação porque não conseguem mudar seu significado. Um conteúdo alterado precisa de uma nova decisão.

Algumas equipes dependem de uma mensagem de chat como «Prosseguir?» e chamam a resposta de aprovação. Isso falha sob pressão porque o registro frequentemente não contém os parâmetros exatos, e o agente pode interpretar uma resposta posterior como consentimento para uma solicitação anterior. Coloque o identificador da operação no registro de confirmação e exija que o executor o verifique antes de enviar a gravação.

Um payload simples de aprovação torna o vínculo visível:

{
  "operation_id": "op_3f8c",
  "idempotency_token": "81b59b1a-9e75-4de7-a53b-1bb50969c83c",
  "fingerprint": "e5c7...",
  "expires_at": "2025-06-14T15:30:00Z",
  "approved_by": "user_42"
}

Trate a confirmação como autorização para um comando específico, não como permissão para improvisar em torno de uma categoria de comandos. Essa distinção mantém um retry seguro sem dar ao agente uma aprovação em branco que ele possa reutilizar mais tarde.

Sistemas de chamados também precisam de uma verificação de duplicata no nível do negócio

Tokens de idempotência interrompem tentativas duplicadas de transporte, mas sistemas de chamados têm outra fonte de duplicação: agentes podem iniciar operações separadas que descrevem o mesmo problema. Um alerta de monitoramento chega duas vezes, duas execuções do agente leem o mesmo canal de incidentes ou um scheduler desperta depois de uma falha e repete uma tarefa sem o estado original.

Não resolva isso deduplicando pelo texto do título. Os títulos variam o bastante para deixar duplicatas passarem, e títulos idênticos podem se referir a incidentes separados. Em vez disso, decida o que significa identidade no domínio dos chamados. Pode ser um identificador de evento de alerta, um identificador de incidente, uma referência a uma issue do repositório ou um valor composto, como serviço mais impressão digital do alerta mais janela do incidente.

Torne esse identificador de negócio explícito na API:

{
  "source_event_id": "alert-7c91",
  "project": "operations",
  "title": "Certificate expiry alert",
  "description": "Alert event alert-7c91 crossed its threshold."
}

O serviço de chamados pode impor unicidade para source_event_id dentro do escopo pretendido. Uma segunda execução do agente receberá então o identificador do chamado existente em vez de adicionar outro item à fila. Isso é diferente de idempotência. As duas chamadas podem ter tokens de idempotência diferentes porque vieram de dois processos de agente distintos, mas ainda assim representar o mesmo evento upstream.

Agentes só devem pesquisar antes de criar quando o resultado da pesquisa tiver uma identidade estável em que possam confiar. Fluxos baseados em pesquisa pelo título parecem atraentes porque não exigem alterações na API. Eles quebram assim que a indexação atrasa, a classificação dos resultados muda ou um agente reformula o título. Coloque a regra de unicidade onde a gravação acontece e devolva uma resposta clara informando se a API criou ou reutilizou um chamado.

Tenha cuidado com comentários automáticos e alterações de status. Uma operação que encontra um chamado existente ainda pode acrescentar um comentário duplicado ou reabrir um incidente resolvido. Dê a cada subação relevante seu próprio identificador ou faça o comando de gravação expressar todo o estado desejado. Endpoints vagos de «atualizar este chamado» são difíceis de repetir com segurança porque ninguém consegue dizer qual parte da atualização já foi executada.

Gravações de pagamento exigem uma consulta de resultado, não otimismo

Ações de pagamento exigem um padrão mais rigoroso, porque uma cobrança duplicada prejudica o cliente mesmo que você faça o reembolso depois. A aplicação deve enviar um único token de idempotência estável ao provedor de pagamentos e manter a referência da transação do provedor junto ao registro da operação local.

Quando o cliente sofre timeout, deve tratar o pagamento como desconhecido. Deve consultar a referência do provedor, a referência do comerciante ou o token de idempotência, se o provedor oferecer essa consulta. Não deve iniciar outra tentativa de pagamento apenas porque o agente não recebeu uma resposta de sucesso.

Há duas operações que as pessoas costumam juntar em uma: criar uma intenção de pagamento e capturar os fundos. Elas podem ter comportamentos de retry diferentes. Um serviço pode criar ou recuperar com segurança um único objeto de pagamento usando um token e, depois, exigir uma ação explícita de captura quando as verificações forem concluídas. Modele abertamente os estados do negócio em vez de escondê-los atrás de um único endpoint que tenta fazer tudo em cada chamada.

Os valores precisam de um tratamento canônico antes da criação da impressão digital. Converta os valores para a menor unidade de moeda aceita ou para outra representação exata antes que a solicitação chegue à camada de deduplicação. Não faça hash de um valor de exibição em ponto flutuante esperando que cálculos equivalentes sejam comparados de modo confiável. Uma solicitação de pagamento também deve incluir uma referência de fatura ou pedido quando o domínio tiver uma, porque isso dá à equipe uma forma de identificar uma intenção duplicada além dos retries de rede.

O recurso de idempotência do provedor não elimina a responsabilidade da sua própria API. A aplicação ainda precisa impedir que duas tarefas de agente iniciem duas solicitações distintas ao provedor para o mesmo pedido. Coloque uma restrição de unicidade no estado pagável do pedido, use um registro de operação local e faça o agente consultar esse registro depois de um resultado incerto.

Reembolsos exigem o mesmo cuidado. «Repetir o reembolso» pode significar repetir a mesma solicitação de reembolso ou iniciar outro reembolso parcial. Mantenha um identificador estável para cada instrução de reembolso e registre o valor já solicitado. Se o agente precisar emitir um segundo reembolso, transforme isso em uma instrução nova e explicitamente autorizada, com um identificador novo.

Implantações precisam de referências imutáveis e um bloqueio de release

Um retry de implantação só é seguro quando nomeia o mesmo release. Nomes de branches como main e tags mutáveis como latest não atendem a esse padrão. Um retry depois de um timeout pode resolver o mesmo nome para um código diferente e aparentar sucesso enquanto implanta algo que a pessoa aprovadora nunca revisou.

Use um digest imutável de artefato, um identificador de commit ou uma versão que o sistema de releases garanta que não mudará. Inclua essa referência na impressão digital e na confirmação. Se um agente enviar o mesmo token de idempotência com uma referência de artefato alterada, rejeite a solicitação como conflito em vez de tratá-la como um retry atualizado.

Você também precisa de uma regra de concorrência para o ambiente. Duas operações distintas podem carregar legitimamente dois tokens diferentes e ainda assim entrar em conflito porque ambas têm como destino a produção. Um bloqueio de release, uma verificação otimista de versão ou uma fila de implantação pode serializar essas alterações. A idempotência não decide qual de duas implantações distintas deve vencer. Ela apenas impede que uma implantação seja executada duas vezes.

Considere esta sequência de falha. O agente inicia a implantação dep-118 para o commit a1b2c3 e o controlador de implantação a aceita. O agente perde a resposta, presume que houve falha e inicia dep-119 com o commit d4e5f6 porque um commit mais recente apareceu. Agora os dois trabalhos alteram o mesmo ambiente. Um token teria interrompido apenas um retry verdadeiro de dep-118; o bloqueio de release ou a verificação da versão esperada do ambiente interrompe o segundo plano conflitante.

A API de implantação deve expor um recurso de status da operação que informe se ela está na fila, em execução, concluída, falhou, foi cancelada ou está desconhecida. Depois de um timeout, os agentes devem consultar esse status. Não devem deduzir a conclusão pela ausência de uma resposta ou por uma linha de log sem o identificador da operação.

O rollback precisa de seu próprio identificador de operação e de aprovação. Tratar o rollback como um retry da implantação esconde uma mudança relevante de intenção. Ele pode ser automático sob uma regra de segurança documentada, mas deve deixar um registro distinto do release original.

As ferramentas do agente devem preservar a identidade da operação entre as fronteiras

Uma interface de ferramenta para agentes deve tornar o comportamento seguro mais fácil que o inseguro. Dê ao agente uma única ação que aceite um identificador de operação estável, um payload e um modo de retry declarado. Devolva um resultado que informe se o serviço criou um trabalho, repetiu um resultado anterior, encontrou uma operação em andamento ou rejeitou um retry alterado.

Evite ferramentas que gerem silenciosamente um novo token de idempotência em cada chamada. Elas parecem convenientes em uma demonstração e falham no primeiro timeout real. Se a ferramenta for responsável por gerar o token, ela deverá devolvê-lo imediatamente e persistir o valor em um local que uma chamada posterior possa consultar. Na maioria dos sistemas, a camada de workflow deve ser responsável pelo token, porque entende quais chamadas pertencem a uma única ação solicitada pelo usuário.

O Sallyport pode manter as credenciais da API fora do agente enquanto o agente envia a ação HTTP pretendida pela conexão MCP. Essa separação ajuda a proteger as credenciais, mas a API downstream ainda precisa de um comportamento idempotente. Uma credencial protegida não transforma um POST ambíguo em um retry seguro.

Torne explícita a regra de retry do agente no contrato da ferramenta:

if response is a known success:
    record operation complete
if response is a timeout or connection failure:
    query operation status using the same token
    retry only with the same token if the API permits it
if response says fingerprint conflict:
    stop and request a new operation or human review
if response is a known business failure:
    do not retry until the task changes

Não deixe o agente usar backoff exponencial como substituto do estado. O backoff reduz a pressão sobre um serviço, o que é importante, mas não responde se a última gravação teve sucesso. O agente precisa preservar o identificador da operação antes de esperar.

Os logs precisam provar o que aconteceu depois de uma gravação contestada

Quando um cliente diz que foi cobrado duas vezes ou uma pessoa engenheira encontra dois chamados, você precisa responder a quatro perguntas: qual execução do agente emitiu cada solicitação, qual token ela usou, qual impressão digital o servidor calculou e qual resultado o serviço downstream devolveu. Os logs gerais de solicitações costumam omitir pelo menos uma dessas informações.

Registre uma operação na fronteira em que a API aceita a ação. Inclua a identidade autenticada, o token, a impressão digital, a rota da solicitação, as transições de estado da operação, a referência da resposta e a referência do provedor upstream quando existir. Mantenha segredos e corpos completos com dados sensíveis fora dos logs de rotina. Uma impressão digital permite comparar solicitações sem armazenar todos os campos privados em todos os sistemas de log.

Um registro de auditoria somente para acréscimo ajuda quando um agente tem autoridade para fazer gravações externas. O registro deve distinguir entre tentada, aprovada, enviada, aceita, concluída e repetida. Esses estados não são intercambiáveis. Um retry que recebe uma resposta anterior armazenada deve ser marcado como replayed, não como created, ou os operadores o contarão como uma segunda ação.

O Sallyport registra sessões de agentes e ações individuais em diários derivados de um log de auditoria criptografado e encadeado por hashes, e sp audit verify pode verificar a cadeia offline. Isso pode estabelecer o que passou pelo gateway de ações. Combine essa evidência com os registros de idempotência do serviço receptor, porque é o serviço receptor que determina se executou a ação de negócio.

Teste o caminho de uma gravação contestada antes de confiar nele. Faça o servidor concluir uma solicitação e descartar a resposta. Envie cópias concorrentes com um único token. Reinicie o agente entre as tentativas. Reutilize um token com um payload alterado. Encerre um worker depois que ele reivindicar um token, mas antes que registre a conclusão. Um desenho que sobrevive apenas a respostas de sucesso limpas ainda não resolveu as gravações duplicadas.

Comece pelo endpoint de gravação que mais causa prejuízo quando é repetido. Adicione um token estável, reivindique-o atomicamente antes de qualquer efeito colateral, vincule-o a uma impressão digital e ofereça aos chamadores uma consulta de status para resultados desconhecidos. Depois, faça o agente carregar esse identificador até conseguir provar que a operação chegou a um estado terminal.