Idempotency

What is idempotency?

Idempotency is the property that repeating the same operation has the same intended effect as performing it once. It is especially important when agents call tools that create side effects, because networks can fail after an operation succeeds but before the response reaches the caller.

An idempotent read can usually be repeated safely. A write such as “create payment” needs deliberate design to avoid producing another payment on each attempt.

How it works

Systems often use an idempotency key: a unique identifier for one logical operation. The client sends the same key when retrying. The service records the first accepted outcome and returns that result for repeated requests instead of executing the side effect again.

The key must represent the intended operation at the right scope. Reusing one key for unrelated actions can incorrectly collapse valid work, while generating a new key for each retry defeats the protection.

Simple example

An agent requests a $100 refund with key refund-order-481-v1. The service processes it, but the response times out. The agent retries with the same key. The service returns the original refund result rather than issuing another $100.

The agent can now recover from an uncertain response without assuming the first call failed.

Idempotency versus duplicate prevention

Duplicate prevention is the broader goal of detecting or blocking repeated work. Idempotency is a behavioral guarantee for repeated requests representing the same operation.

Simple duplicate detection might compare similar payloads within a time window, which can reject legitimate repeated actions. Idempotency uses explicit operation identity and defined service behavior.

Limits

Idempotency does not make every workflow automatically safe. A multi-step operation may call non-idempotent downstream systems, and stored keys need retention and concurrency rules. Builders must define what happens when the same key arrives with different arguments.

Why it matters

Retries, timeouts, reconnects, and duplicated event delivery are common in agent workflows. Idempotency turns many uncertain failures into recoverable operations while protecting users from repeated side effects.

Pair it with durable state, clear tool results, bounded retries, and observability. See [Tool Use in AI Agents](/tool-use-in-ai-agents/) for where execution safeguards fit.