Idempotency is the property of an operation whereby executing it multiple times produces the same effect as executing it once. For AI agents, idempotent tools are what make retries, crash recovery, and replay safe: a duplicated tool call charges one payment, sends one email, and writes one record instead of two.
Why idempotency matters
Agents act on the world through tools — charging cards, sending emails, creating tickets, writing rows — and distributed systems fail in a specific, awkward place: after the effect, before the acknowledgment. A network timeout can hide a request that actually succeeded. A worker can crash after the payment cleared but before the step was recorded. A model can even emit the same tool call twice in one conversation.
Every layer that adds reliability also adds repetition: the HTTP client retries, the runtime reassigns a step from a dead worker, an operator re-runs a failed workflow. Retrying a read is free; retrying a charge is a refund ticket. Without idempotent tools, each safety mechanism becomes a way to duplicate side effects — and an unattended agent will not notice the duplication the way a human operator might.
How it works
Idempotency is a property of the tool together with the system behind it, established through a few standard techniques:
- Idempotency keys. The caller attaches a unique key to each logical operation — derived, for example, from the run identifier and step identifier. The receiving service remembers keys it has completed and, on a duplicate, returns the original result instead of acting again. This is the pattern payment APIs made standard.
- Upserts and conditional writes. Phrase writes as create-or-update keyed on a natural identifier, or guard them with a version or precondition check, so replaying the write converges on the same final state.
- Check-before-write. The tool first queries whether its effect already exists — is there already a ticket for this incident? — and skips the action if so.
- Absolute rather than relative updates. Setting status to closed is idempotent; toggling status is not. Setting a balance to a value is idempotent; incrementing it is not.
Idempotency vs. retries
Retries and idempotency are two halves of one reliability strategy, not alternatives. A retry repeats an operation; idempotency makes the repetition safe. Retries provide at-least-once execution — the operation definitely happens, possibly more than once — and idempotency converts at-least-once execution into an effectively-once outcome. Retries without idempotency are how systems double-charge a card, double-send an email, and double-write a record while every individual component behaves exactly as designed.
In practice
Durable execution checkpoints each completed step so finished work is never re-run after a failure — but the checkpoint lands after the step, so a worker that dies mid-step leaves the runtime unsure whether the side effect fired. The step is redelivered, and the tool must tolerate that second invocation. Idempotent tools are therefore the contract that makes crash recovery safe, and they pair with deterministic replay: replay keeps the decision path stable, while idempotency keeps the side effects single. Guidance on writing well-behaved tools lives in building agent tools.