Give each logical action a durable, stable idempotency key, and enforce it in trusted tool or service code—not just in the agent prompt. When the same action is retried, the service should return the saved outcome instead of performing the side effect again. If a downstream API does not support idempotency and a timeout leaves the outcome uncertain, reconcile its state before retrying.
Why an agent can post twice
A timeout does not tell an agent whether a request failed. The server might have created a post, sent a notification, or opened a record, while the response was lost on its way back. If the agent tries again as though nothing happened, the side effect can happen twice.
As an Amazon Associate I earn from qualifying purchases.
An idempotency key is an identifier for one logical operation. A service that supports idempotency uses the key to recognize a retry and return the prior outcome rather than repeat the operation. AWS Well-Architected describes repeated identical requests as having the same effect as one request; in practice, that guarantee depends on where the service records the key and coordinates the side effect.
The important distinction is between a retry of the same intent and a new, intentional action. Retrying “publish this post” should reuse its key. A user who deliberately asks to publish the same text again is making a new operation and needs a new key. Matching arguments alone cannot reliably tell those cases apart.
Where to enforce idempotency
Put the durable boundary in trusted code
Enforce deduplication in the tool server, orchestration layer, or service that owns the side effect. A prompt asking a model not to repeat a call is not a durable safeguard: the model may be invoked again, a worker may resume, or a new tool invocation may occur after the original response was lost. Store the operation identity and outcome in durable storage, not only in transient model context or process memory.
This boundary matters for agents because a network library may retry a request within one tool call, while the agent may later issue a new tool call for the same logical step. A May 3, 2026 issue in Stripe’s public AI repository illustrates that distinction: it reports a case where network-level retry handling may not cover a new agent-level invocation with a newly generated key. It is an individual issue report, not evidence that every framework or version behaves this way; check the behavior of the stack you actually use.
Keep local and provider safeguards distinct
Your orchestration layer protects the logical agent operation. A downstream provider’s idempotency key protects the request at that provider. They are related, but not interchangeable: local deduplication cannot stop a provider from repeating an effect if your service sends it twice, and a provider key may not cover a new agent invocation if the orchestration layer generates a fresh one.
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →Design the operation record before making the side effect
- Assign a stable operation ID. Create it from the durable workflow step or logical intent before execution. Preserve it if the model or worker resumes that step. Generate a different ID for a genuinely new action.
- Persist and claim the ID atomically. Record the key with a request fingerprint and a state such as
pending,completed, orfailed. A unique constraint or transaction should arbitrate concurrent attempts so two workers cannot both pass a separate “check, then execute” sequence. - Define pending behavior. If another attempt finds the same operation in progress, do not start a second side effect. Wait, return a pending result, or provide a controlled way to check the operation’s status. Set recovery rules for work that remains pending after a worker crash.
- Perform the mutation and save a replayable outcome. Where one database transaction can cover both, use it. When the effect happens in an external system that cannot join that transaction, pass the same key downstream if supported and store the provider’s receipt or result. If it is not supported, plan reconciliation or an appropriate compensating action.
- Replay matching requests. When the same key arrives with matching operation data, return the saved status or a semantically equivalent receipt. The agent can then proceed as if its original call returned successfully.
- Reject key reuse with different data. Associate a request fingerprint with the key. If the key is presented for different parameters, reject it rather than silently treating the new request as the old operation.
- Retain and monitor records deliberately. Choose retention to cover realistic workflow delays and any downstream provider window. Log the operation ID for traceability and monitor unexpected duplicates, mismatched parameters, and operations stuck in pending state.
Handle the difficult crash and timeout cases
| What happened | What a retry should do | Why |
|---|---|---|
| The request never reached the service, and no operation was claimed. | Retry using the same logical operation ID. | The durable claim lets the service recognize attempts as the same operation. |
| The operation is still marked pending. | Check or wait for the existing attempt; do not launch a second side effect. | Two workers may otherwise execute the same logical action concurrently. |
| The effect completed and its result was recorded, but the response was lost. | Return the saved outcome for the same key. | The caller needs a usable receipt, not a duplicate-action error. |
| An external effect may have completed, but your service has no confirmed result. | Use downstream idempotency or reconcile the provider’s authoritative state before retrying. | A local key cannot prevent a provider that ignores it from performing the action twice. |
| The same key arrives with different parameters. | Reject the request and surface the conflict. | Reinterpreting an existing key could turn a retry into an unintended mutation. |
There is no general way to make a database update and an unrelated external API call one atomic transaction. If a process crashes between those actions, the local record and provider may disagree. A provider’s idempotency contract can close that gap for its request; otherwise, build a reconciliation path that checks authoritative downstream state before deciding whether to retry. For irreversible effects with no way to check, do not blindly repeat an ambiguous request.
Apply provider idempotency without assuming a universal contract
Providers differ in which endpoints accept keys, how they scope them, how they handle parameter mismatches and concurrent requests, whether they replay errors, and how long they retain records. Check the current documentation for the specific API and endpoint before relying on its behavior.
Stripe’s documented behavior
Stripe’s API reference, accessed October 4, 2026, says that idempotent requests save the first endpoint result and replay the same status and body for the same key, including a 500 result. The parameters must match the original request. Stripe may prune keys once they are at least 24 hours old; after pruning, reusing a key can start a new request. Thus, a retained key is not a permanent guarantee that an old operation can never run again.
Stripe also says it saves a result only after endpoint execution begins. Validation failures and conflicts with a concurrent request that prevent execution are not stored and can be retried. Its documentation says all POST requests accept idempotency keys, while GET and DELETE are already idempotent by definition in its API. These are Stripe-specific semantics, not a template for every provider. For Stripe keys, the documentation recommends a v4 UUID or another high-entropy random string and warns against putting sensitive information in the key.
A replayed 500 deserves particular care: getting the same error again does not prove the operation had no effect. Follow the provider’s documented recovery guidance and inspect authoritative state where possible; do not assume that a fresh key is a safe way to “try again.”
Choose keys and storage to fit the workflow
Use intent-based identifiers, not argument hashes
A stable random identifier, such as a high-entropy UUID, can identify an operation without exposing its contents. Persist it with the workflow step so a resumed worker reuses it. Avoid timestamps as keys: a retry at a later time could look like a new operation. Avoid embedding personal or otherwise sensitive data in a key.
Hashing request parameters can detect that two payloads match, but it cannot establish that they represent the same intent. Two separately requested posts can have identical text and parameters. Amazon’s Builders’ Library recommends a unique caller-provided request identifier because it expresses intent and can also support auditability. A fingerprint is useful for detecting accidental reuse of a key with changed parameters; it should not substitute for the operation ID.
Select durable storage by operational needs
AWS names DynamoDB, ElastiCache, RDS, and S3 as possible storage examples, not as a universal ranking or recommendation. Compare candidate stores against the operation volume, lookup and write latency, durability and availability requirements, transaction and concurrency controls, retention period, and the architecture you already run. The essential property is not the product name: the key, state transition, and replayable result must remain consistent and durable enough for the workflow.
Recommended Free Tools
Validate the design around retries
- Simulate a lost response after the provider has completed the action; verify that retrying returns the original receipt and creates no second effect.
- Run two requests with the same key at once; verify that only one can claim and execute the operation.
- Retry after a worker restart or a new agent invocation; verify the workflow resumes with the original key rather than generating a new one.
- Send the same key with changed parameters; verify the service rejects it.
- Exercise pending operations and crashes between local persistence and an external call; verify the recovery path checks or reconciles downstream state instead of blindly repeating an irreversible effect.
- Check behavior at and beyond local and provider retention windows; expired records can change what a reused key means.
Idempotency reduces duplicate effects at defined service boundaries; it does not make an entire distributed workflow magically execute exactly once. AWS Well-Architected distinguishes at-most-once and at-least-once request strategies from the difficulty of exactly-once effects across distributed systems. Design for stable intent, durable state, concurrency control, downstream contracts, and recovery when the outcome is uncertain.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
