AI Agent Idempotency: Build Queues That Never Repeat Expensive Actions

Every serious agent system retries. Workers crash after sending a request but before saving the response. Networks time out while a provider completes the operation. Humans approve a task as a lease expires. At-least-once delivery turns these ordinary failures into duplicated emails, purchases, tickets, or deployments.

Idempotency means the same intended effect can be requested repeatedly while being committed once. The model cannot provide that guarantee. The queue, tool gateway, and external adapter must enforce it.

Give the Intent a Stable Identity

Generate an idempotency key when the business intent is accepted, before a worker or model attempts execution. Retries must reuse that key. Do not derive it from a timestamp, attempt number, or freshly generated model text.

Useful keys bind the tenant, workflow, action type, target, and semantic operation. Store a digest of consequential parameters beside the key. If a later attempt reuses the key with a different amount or recipient, reject it instead of guessing.

const key = hash({ tenant, workflowId, action: "refund", paymentId });
await effects.reserve(key, hash({ amount, currency }));

Put an Effect Ledger Around Every Mutation

Track states such as reserved, executing, succeeded, failed_retryable, and needs_reconciliation. Use a unique database constraint on the idempotency key. Claim work with a lease so another worker can recover abandoned jobs without creating a second logical operation.

The hard case is an ambiguous timeout: the external system may have succeeded while the local ledger still says executing. Do not immediately repeat the mutation. Query the provider by its idempotency key or external reference. If the provider cannot support lookup or idempotent writes, route ambiguity to reconciliation or human review.

Separate Planning Retries From Effect Retries

An agent may regenerate a plan many times. That does not authorize new business effects. Represent planned actions as immutable commands and require the executor to commit each command through the effect ledger.

If a revised plan truly changes the action, mint a new command identity and invalidate the old one explicitly. Never let minor wording differences create fresh payment or publication keys. Semantic authority comes from structured fields approved by policy, not the natural-language explanation.

Make Approval Bind to the Exact Effect

An approval should cover a command digest, not a conversational turn. Bind approver, expiry, target, parameters, and idempotency key. When data changes, require a new approval.

This prevents a delayed retry from using yesterday’s approval for today’s amount. It also makes audit logs intelligible: operators can see which human authorized which one-time effect.

Test the Failure Windows

Kill workers before the provider call, during the call, after success but before local commit, and during acknowledgement. Deliver the same queue message concurrently. Expire leases. Delay provider webhooks. Confirm that the final external effect occurs once and the ledger converges.

Exactly-once delivery across independent systems is usually an illusion. Exactly-once business effect is achievable when stable identity, deduplication, provider support, and reconciliation work together. Build those controls before giving the agent a tool with consequences.