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

说明与用途

AI 代理在规划逻辑动作时生成幂等键并持久化，所有重试使用相同键，防止重复支付等副作用。

问题

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.

结果

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.

工作流

• 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.

证据

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.

来源

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

来源

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

来源

Every attempt reads the key, never creates it.

来源

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

来源

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.

来源