Key takeaways
- One approved business action needs a stable identity across attempts.
- Enforce duplicate handling where the change is committed.
- Resolve uncertain outcomes before asking the agent to try again.
AI agent idempotency makes repeated attempts at one logical action produce one intended business effect. It matters whenever an agent creates a shipment, updates a record or triggers another consequential operation. A timeout means the caller did not receive a timely answer; it does not establish that the operation failed. Retrying without that distinction can repeat work already completed.
Consider a hypothetical fulfilment assistant requesting a shipping label. The shipping service accepts the request, but its response is lost. The assistant sees a timeout and calls the tool again. The right result is the original shipment reference, or a clear pending state, rather than a second shipment. The application needs to recognize the same action across those delivery attempts.
Define AI agent idempotency around business intent
Separate the action from the attempt. The action is an approved shipment for a particular order and package. The attempts are requests made to complete that action. A new network request, conversation turn or model run should not automatically create a new action identity. Store the identity in durable workflow state outside the model’s memory.
At the same time, two legitimate actions must remain distinguishable. A customer can order two similar items or request a second shipment after an approved replacement. Hashing visible text alone can collapse different intentions. Tie the identifier to the workflow record and explicit action being approved, including the relevant actor and business scope.
Create an enforceable key contract
Idempotency keys for agents should be generated and persisted by the application. Reuse the same key for retries of the same action. Have the receiving service associate the key with the accepted parameters and recorded outcome. If a caller presents the same key with materially different parameters, reject the mismatch instead of silently changing the operation.
Amazon’s Builders’ Library discussion of idempotent APIs explains the role of caller-provided request identifiers in safe retries. Apply the principle at the service that commits the business change. A promise in a tool description does not enforce it.
| Recorded state | Meaning | Next step |
|---|---|---|
| Not accepted | No operation was recorded for this identity | Submit under the existing action contract |
| In progress | The action is known but not yet resolved | Wait or query status without starting another action |
| Completed | The intended effect has a stored result | Return that result on a repeated request |
| Uncertain | The downstream outcome cannot yet be confirmed | Reconcile before permitting another write |
Handle concurrent duplicate tool calls
An agent can produce duplicate tool calls before the first response arrives. Two workers can also resume the same queued task. A check-then-write sequence is insufficient if both workers observe that no result exists and then both create the shipment. Use a uniqueness constraint, atomic claim or another transaction design that makes one worker own the action.
Define what the second caller receives while the first operation is running. It may receive a pending response and a status reference. Avoid making every duplicate wait indefinitely, and avoid interpreting a busy response as permission to generate a fresh key. Keep the user-facing progress consistent with the recorded state.
Design agent retry safety across service boundaries
If the downstream provider supports idempotency, propagate a stable identity according to its documented contract. Check key scope, retention and parameter-mismatch behavior. If it does not, an intermediary can record requests, but cannot magically make a remote side effect atomic with its own database write. That gap needs explicit reconciliation or a less autonomous workflow.
Decide how long duplicate recognition must remain effective. A record that expires before a delayed retry arrives can allow another effect. Retention should account for queue delays, operator retries and recovery procedures. Do not claim exactly-once delivery across all failures merely because an idempotency field exists.
Test the uncertain moments
- Repeat the same request after the service commits but before the caller receives its result.
- Submit two concurrent requests with the same action identity.
- Send the same key with a changed destination or quantity.
- Resume a queued task after a worker restart.
- Reconcile a delayed response after an operator has already investigated the task.
Inspect business records as well as responses. One reassuring answer is not proof that only one shipment exists. The MCP integration contract should specify retry semantics for every write tool. Include these cases in the engineering acceptance criteria, and bring an example timeout sequence to a delivery discussion if the current recovery path is unclear.
Frequently asked questions
Can the model generate the idempotency key?
The application should control and persist the action identity. A model-generated value may change across retries or become disconnected from the approved business intent.
Does idempotency undo an incorrect action?
No. It prevents repeated attempts from causing repeated effects under a defined contract. Correcting an incorrect action requires a separate authorized compensation or reversal process.



