Networks fail, and agents retry. If a retried action runs twice, the result can be a duplicate payment or a second email. Idempotency prevents that.
What idempotent means
An operation is idempotent if performing it multiple times has the same effect as performing it once. Setting a value is idempotent. Appending to a list or charging a card is not, unless you design it to be.
Why agents need it
An agent may time out after sending a request but before seeing the response. It cannot know whether the action succeeded. A retry without protection could repeat it. Models may also request the same action again after losing track of earlier steps.
Idempotency keys
The usual approach is to attach a unique key to each logical action. The service stores the result for that key and returns it again if the same key arrives a second time. The agent runtime generates the key, usually derived from the task and step so that retries reuse it.
Other techniques
- Use "create if not exists" or conditional updates instead of blind inserts.
- Check current state before acting.
- Record each action's status in durable storage.
What to test
Simulate a timeout after the side effect and confirm the retry does not duplicate it.
Takeaway
For every tool that changes the world, ask what happens if it is called twice, and design the answer deliberately.
Continue with the book
Explore the full treatment, worked examples, and exercises in Building Production-Grade AI Agents.
Adapted from Building Production-Grade AI Agents, published by Choral Software. Article text and original examples © 2026 Choral Software. All rights reserved.