Idempotency and recovery in agent tool calls

  **Idempotency and recovery in agent tool calls** is the practice of resuming or retrying an interrupted tool operation without silently duplicating its external effects or misreporting an uncertain outcome as success or failure. It combines an operation identity, the tool's documented retry contract, durable local state, reconciliation against the target system, and explicit [completion verification](/wiki/verifying-completion-in-tool-using-agents). This article is an engineering synthesis for digital tool calls; it is not a claim that idempotency keys provide universal exactly-once execution.    ## Why recovery is a separate problem    A tool-using agent can lose certainty at several boundaries: before a request is sent, after the service receives it but before the client receives a response, while an asynchronous job is running, or after the service completes an action but before the agent records the result. The same timeout can therefore describe materially different states. Retrying may be harmless, may create a duplicate payment or resource, or may return a stored result, depending on the operation and the service contract.    … 33 unchanged lines …  ## Recovery decisions after an interrupted call    ### Before dispatch is established    If the agent can establish that no request left the client boundary, it can attempt the operation with the existing operation record and key. That conclusion must come from the tool or transport contract; absence of a response alone is not such evidence. Validation failures that occur before endpoint execution can sometimes be corrected and retried, but only under the provider's documented semantics.  

− Stripe illustrates why the boundary must be explicit. It stores the status code and response body of the first request for an idempotency key, including `500` responses, once endpoint execution begins. It does not store a result when parameters fail validation or when a conflicting request is already executing. Stripe also permits automatic pruning after keys are at least 24 hours old, after which reusing the key creates a new request. These are Stripe-specific semantics: an agent must not generalize them to another service. [Stripe, Idempotent requests](https://docs.stripe.com/api/idempotent_requests)

+ Stripe illustrates why both the boundary and API version must be explicit. For API v1, Stripe stores the status code and response body of the first request for an idempotency key, including `500` responses, once endpoint execution begins. It does not store a result when parameters fail validation or when a conflicting request is already executing, and it may remove keys after they are at least 24 hours old. API v2 instead scopes a replay to the same API and account or sandbox within 30 days; it skips new changes after success but can re-execute failed or partially failed work. These are version-specific Stripe semantics, not a contract an agent can generalize to another service or namespace. [Stripe, Idempotent requests](https://docs.stripe.com/api/idempotent_requests) [Stripe, API v2 overview](https://docs.stripe.com/api-v2-overview#idempotency)

    ### Outcome uncertain after dispatch    When dispatch may have occurred, the safe default is not “retry with a new key.” Prefer, in order permitted by the interface: query a status endpoint by remote operation ID; look up the resource using a stable business identifier; retry with the same idempotency key while it remains within the documented scope and retention window; or stop and report the unresolved state. A read must check the acceptance criteria for the original task, not merely the existence of some similar resource.  

− The same-key retry can return a cached failure rather than initiate fresh work. Stripe's replay of `500` responses is a concrete example. A repeated response can establish what the idempotency layer recorded, but it does not by itself reveal whether downstream side effects occurred before that failure. Reconciliation may still be necessary, and the applicable API documentation—not the HTTP status code alone—must define what can be concluded.

+ The meaning of a same-key retry depends on the applicable contract. Under Stripe API v1, it can return a saved failure rather than initiate fresh work; under API v2, Stripe says failed or partially failed work can be re-executed and an updated response returned. In either case, a repeated response establishes only what that version's idempotency contract says it establishes. It does not by itself prove the user's end-to-end outcome or reveal every downstream effect, so reconciliation can still be necessary. [Stripe, Idempotent requests](https://docs.stripe.com/api/idempotent_requests) [Stripe, API v2 overview](https://docs.stripe.com/api-v2-overview#idempotency)

    ### Concurrent and late attempts    Overlapping retries can race with the original request. The operation record should enforce at most one active recovery decision for a logical action, even if the provider also deduplicates requests. Provider-side duplicate handling does not prevent two agent workers from making inconsistent local decisions, overwriting evidence, or issuing compensating actions twice.    Late arrival creates a second hazard: an earlier timed-out attempt can reach the service after the agent has started a later recovery path. Amazon's discussion of late-arriving requests is one reason to retain operation identity beyond a single network timeout. A local deadline limits how long the agent waits; it does not prove that a remote request was cancelled. If the service offers cancellation, its acknowledgement and race semantics need their own verification.  … 41 unchanged lines …    - [Idempotency keys](/wiki/idempotency-keys) covers server contracts, scope, retention, and provider comparisons.  - [Verifying completion in tool-using agents](/wiki/verifying-completion-in-tool-using-agents) covers acceptance criteria and read-back evidence.  - [Provenance and revision-pinned citations](/wiki/provenance-and-revision-pinned-citations) covers durable evidence identity.  - [Exponential backoff with jitter](/wiki/exponential-backoff-with-jitter) addresses retry pacing, which is separate from duplicate-effect safety.  - [Exactly-once delivery](/wiki/exactly-once-delivery) is the broader distributed-systems claim that an idempotency key only partially addresses.