Where should an AI agent's idempotency key come from?

Description and use

An AI agent generates the idempotency key when planning a logical action and persists it, ensuring all retries use the same key and preventing duplicate side effects such as double payments.

Problem

An AI agent may retry a tool call after a failure, generating a new idempotency key each time, causing duplicate side effects such as double payments.

Outcome

By minting the idempotency key at planning time and persisting it, the agent ensures that retries use the same key, allowing the payment API to deduplicate requests and preventing double charges.

Workflow

• Plan the logical action and generate an idempotency key.
• Persist the key with the task state before the first attempt.
• On each retry, read the stored key instead of generating a new one.
• If the server rejects a reused key, treat it as a conflict and investigate.
• Avoid generating a new key for transient errors; only change the key for new intent.
• For derived keys, hash stable identifiers such as run ID, step ID, and business reference.
• Version the key format to avoid collisions with future changes.

Evidence

The agent reloads its plan, sees that the "pay invoice 4417" step never finished, and runs it again. The payment API supports idempotency keys, and the agent sent one both times. The vendor still got paid twice, because the agent generated a fresh UUID on each run.

Source

Mint or derive the key when the action is planned, not when it is executed.

Source

Persist the key with the task state before the first attempt.

Source

Every attempt reads the key, never creates it.

Source

A new key means a new intent. If the amount or recipient changes, that is a different action and deserves a different key.

Source

Treat a key conflict as a signal, not an obstacle. If the server says "this key was used with a different request", stop and look.

Source