Give every side-effecting tool call an idempotency key

The retry bug bites every agent team eventually: your agent calls a payment or email tool, the response is ambiguous — a timeout, a truncated payload, a "maybe it worked" — the agent retries because retrying is its whole personality, and now the customer got charged twice.

The fix is boring and old: idempotency keys. With one agent-specific twist — they have to be issued by the planner, not the tool.

The pattern¶

Derive the key from the plan run ID plus the action sequence number: key = hash(run_id, seq). The executor checks the key against the recorded-action store before touching the tool. Key seen → return the recorded result, do not re-execute. Key unseen → execute, record the result under the key, return.

def execute_tool(run_id, seq, tool, args):
    key = idempotency_key(run_id, seq)
    if store.exists(key):
        return store.get_result(key)   # replay, not re-fire
    result = tool.call(args)
    store.record(key, result)
    return result

Assign the key at plan time, not inside the tool¶

The key has to be assigned at plan time, before any execution, because the retry decision happens at the agent's layer — and the agent's layer does not know whether the tool call landed. If the key is generated inside the tool call, the retry generates a new one and you have lost the game. The whole point of the key is that the retried attempt carries the same identity as the attempt that may have succeeded.

Record a result the agent will actually accept¶

The recorded result has to include enough context to satisfy the agent on replay. If the agent cannot tell a replayed result from a fresh one, it will start inventing workarounds — calling the tool a different way, splitting the action, re-asking for confirmation — and those workarounds are worse than the duplicates they were trying to prevent. A replay that looks like success ends the loop; a replay that looks suspicious restarts it.

The same key design also covers the nastiest variant: the timeout where the tool succeeded but the response was lost in transit. Because the key was assigned at plan time, the retry carries the same identity, sees the recorded result, and returns it — the agent never knows there was a gap, and the customer never sees a double charge.

The takeaway¶

Learned this one the hard way: the duplicate charge is never discovered by your monitoring. It is discovered by the customer, at 3am, in the worst possible tone.

Idempotency keys are not an agent innovation — they are a Stripe pattern with the assignment point moved to the planner. That one move turns "the agent retried and double-charged someone" from an incident class into a replayed no-op. Boring, old, and exactly what production agents need.