I've been shipping a few small AI-agent features lately, and the thing that helped most wasn't a fancy framework — it was making every tool call idempotent with a stable operation id.
Early on I hit the classic problem: a request times out, the agent retries, and suddenly the same side effect happens twice (two charges, two emails, two tickets). A timeout only tells you what the caller observed — not what the server actually committed.
A few practical rules I now follow:
- Give every meaningful operation a stable id derived from the logical intent, not from the request. If the agent retries the same intent, it maps to the same id.
- Treat "unknown" as a real state. Don't assume failure just because you didn't get a response.
- Make the write path idempotent: the second call with the same id should return the first result instead of doing the work again.
- Surface that unknown state in the UI so a human isn't told "failed" when it might have succeeded.
None of this is exotic distributed-systems theory — it's the same idempotency key idea the payment world has used for years. The twist with agents is that they retry very eagerly, across multiple layers, so one lost response can cascade into many duplicates.
Still learning here. Curious how others handle the "retried but maybe already succeeded" case in their agent tooling — do you push idempotency into the tool framework, or leave it to the model to remember?
Top comments (0)