Guide

AI Agent Idempotency: Prevent Duplicate Business Actions

Separate a business action from its delivery attempts so a timeout or repeated tool call does not create another order or shipment.

Warehouse supervisor reviewing repeated request paths merging into one confirmed shipping action

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.

States the caller must distinguish
Recorded stateMeaningNext step
Not acceptedNo operation was recorded for this identitySubmit under the existing action contract
In progressThe action is known but not yet resolvedWait or query status without starting another action
CompletedThe intended effect has a stored resultReturn that result on a repeated request
UncertainThe downstream outcome cannot yet be confirmedReconcile 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.

Have a workflow or customer experience to improve?

Tell us where work gets stuck and what a better result would look like. We'll help you define a practical next step.