Pular para o conteúdo principal

Idempotência

Toda tool de escrita aceita um argumento opcional idempotency_key. Ele é enviado ao endpoint como o cabeçalho X-Idempotency-Key que a API REST já honra.

{ "name": "dunning_charges_create",
  "arguments": {
    "person_id": "…",
    "original_amount": 1500.0,
    "issue_date": "2026-10-01",
    "due_date": "2026-11-10",
    "idempotency_key": "8c0f5d6e-3f8b-4cb5-9a47-d8f5b15e9b21"
  } }
FormatoString opaca, de 1 a 255 caracteres. Um UUID é a escolha usual.
Repetição com o mesmo corpoDevolve a resposta gravada, sem rodar a operação de novo.
Repetição com corpo diferenteConflito: IDEMPOTENCY_KEY_REUSED.
Repetição enquanto a primeira ainda rodaConflito: IDEMPOTENCY_REQUEST_IN_PROGRESS — espere um instante e repita a mesma chamada.

A chave é escopada à organização e expira depois de 24 horas; os detalhes — o que entra na impressão digital, quando o resultado não é gravado — estão na página de idempotência da API. As tools que despacham para um DELETE aceitam o argumento, mas a API o ignora: apagar já é idempotente por definição.

Por que um agente precisa disto mais que o seu backend​

Um cliente MCP que dá timeout e tenta de novo, ou um modelo que decide "não tenho certeza se aquilo funcionou, vou refazer", é exatamente o padrão que cria a segunda cobrança, o segundo acordo e a segunda mensagem ao devedor. Seu backend tem um laço de retry que você escreveu; o agente tem um julgamento.

Mande uma chave sempre que a operação criar algo ou falar com alguém. Leituras são naturalmente idempotentes e não pedem chave.

:::warning As que falam com o mundo Algumas tools produzem um efeito fora da Régua de Cobrança que nenhuma outra tool desfaz: uma mensagem que chega ao devedor, uma negativação no bureau, um protesto no cartório, uma entrega de webhook. São dunning_charges_notify, dunning_notifications_create, dunning_notifications_resend, dunning_negativations_create, dunning_protests_create, dunning_webhook_endpoints_test e dunning_webhook_deliveries_retry. As de notificação e de webhook trazem idempotentHint: false justamente porque repeti-las envia de novo. Mande idempotency_key nessas mesmo quando você acha que não vai repetir. :::

Idempotência e confirmação​

Nas tools destrutivas, a confirmação e a idempotency_key resolvem problemas diferentes. A confirmação garante que uma pessoa autorizou aquela chamada, uma vez; a chave garante que uma chamada repetida pelo cliente — depois de um timeout, por exemplo — não executa duas vezes. Uma confirmação reaproveitada volta confirmation_replayed; para refazer a ação de propósito, chame a tool de novo, confirme outra vez e use uma chave nova.