Agents make this old distributed-systems requirement more visible because they may autonomously retry a tool after a timeout. The safe design separates one business intent from the number of transport attempts. Stripe’s idempotent request documentation is a clear primary example of a service storing and returning the first result for a repeated key.
How does an idempotent tool call work?
The orchestrator creates a stable key for one intended operation before the first attempt. Every retry carries that same key. The receiving service or a local ledger stores the first accepted outcome and returns it for duplicates. Idempotency protects the business effect, not merely identical request text.
The key should derive from stable workflow identity, such as run, step, and operation version. Letting the model invent a new key on every attempt defeats the guarantee.
What should the tool contract specify?
Tool calling schemas should state which operations are idempotent, how keys are supplied, how long results are retained, and what response is returned for a duplicate. They should also define what happens when the same key arrives with different parameters. One key must represent one immutable business intent.
Read operations are often naturally idempotent, but they may consume quota or observe changing state. Write operations need an explicit server-side guarantee or a reliable operation ledger close to the effect.
How do idempotency and retry policies work together?
An agent retry policy decides whether a failure is temporary and when another attempt may run. Idempotency makes that repeated attempt safe when the first result is unknown. A retry is not safe merely because the previous call timed out.
If the first call succeeded but its acknowledgement was lost, the repeated key returns the recorded result instead of creating another payment, email, or record. Retries should still have a limit and should stop on permanent validation or authorization errors.
What if the underlying system cannot guarantee idempotency?
Use agent recovery to query the current external state by a stable reference before attempting another write. If the duplicate already happened, a compensating action may reverse or offset it. For high-impact uncertainty, route the case to a person. Unknown commit state is a reconciliation problem, not permission to repeat the action.
Test the guarantee with delayed responses, duplicate delivery, process crashes, and retries after restart. The important result is not that the tool returns twice. It is that the outside world contains exactly one intended effect.