LLMs, GenAI, RAG, agents, evaluation · insight-0635
Make side-effecting tools idempotent so retries cannot double-act
- Evidence type
- practitioner heuristic
- Difficulty
- medium
- Roles
- ML engineer, Applied AI
- Industries
- aviation, e-commerce
Summary: situation, action, reason, boundary
Situation
A booking or payment tool call times out, and the agent or the client library retries it.
Action
Generate an idempotency key per intended action (for example run id plus step number), pass it to the downstream API, and have the handler return the stored result when it sees a known key.
Reason
Timeouts do not tell you whether the action happened. Idempotency keys let a service recognise repeats within a window and return the original outcome instead of acting twice.
Boundary
Every write tool in an agent, workflow or queue consumer.
Symptom or risk
The first call actually succeeded, so the retry creates a second booking, a second refund or a duplicate customer email.
Exceptions
Naturally idempotent operations such as "set status to X".
Trade-offs
Key storage and expiry windows must cover the longest retry horizon.
Pitfalls
Deriving the key from the model's text output, which changes between attempts.
Lessons and concepts
Claims and their sources
Resend's documentation describes idempotency keys for send requests, where a repeated request with the same key inside a limited retention window returns the same response without sending the email again; the window was documented as 24 hours when checked on 2026-10-11 and differs between services.