insideout Get Pro

07 · Idempotency keys

Pro

Agents, lesson 7

Idempotency keys

Make tool calls safe to repeat.

You know from "When a tool call fails" when to retry a failed tool call and how long to wait.

Part 1. A timeout tells you nothing

An agent calls charge_card(order 5521, $40). Ten seconds pass with no reply, so your code gives up waiting. Here's the uncomfortable part: you don't know what happened on the other side. The request may never have arrived. Or the card was charged and the reply got lost on the way back.

Your turn

After that timeout, your retry logic from the last lesson sends the same charge again. What might happen?

If the first request did go through, the retry is a second, separate charge. Nothing ties the two together unless you make it so. Timeouts and retries are fine for reading data. For actions with side effects, they're how you double-charge people.

At-least-once

If you retry until you get a reply, every action happens at least once, and sometimes more. Getting exactly-once delivery over a network isn't possible in general, so the usual fix is to make doing it twice harmless.

Part 2. Idempotency keys

Keep going with Pro

You've done the first part. Pro opens the rest of this lesson, and every other one.

Still to come
  1. Idempotency keys
  2. Which tools need this
  3. When the API has no keys
  4. Deadlines, and picking up after a crash
See Pro plansI have Pro: sign in
Next lessonKnowing when to stopStep limits, budgets and done conditions. Start lesson 8

Agents overviewSpotted a mistake? Tell us.