What is idempotency, and why does it matter for agent tools?

Where duplicates come from in agents

• Code-level retry after a timeout, when the first call actually succeeded.
• Resuming from a checkpoint taken before the tool result was saved.
• The model itself calling the same action twice ("let me send it again to be sure").

Techniques

1. Idempotency keys: generate a unique key per intended action (e.g. run_id + step_id). The downstream API (Stripe-style) or your wrapper stores it and returns the original result if the key is seen again.
2. Check-then-act: before create_ticket, search for an existing ticket for this run or issue.
3. Naturally idempotent design: set_status(order, "shipped") instead of increment_counter; upsert instead of insert.
4. Action ledger: record each side effect with its result in the agent state. On resume, skip completed actions.
5. Two-phase actions: prepare/draft (safe, repeatable) → commit (once, often approval-gated).

Related

• Previous: Q31. Your agent worked great in the demo, but fails about 30% of the time in production. How do you approach it?
• Next: Q33. What are the pitfalls of using LLM-as-judge to evaluate agents, and how do you mitigate them?
• LangGraph