Skip to content
Agentic AI

intermediate · Interactive lab

Agent Retries

A person retries once and thinks about it. A loop retries as fast as the network allows, several times, without pausing — so the retry policy is no longer advice, it is behaviour.

By the end: Read a repeat as a property of the tool: an idempotency key, a naturally idempotent call, or neither.

Your challenge

Start here. This lab opens with the loop retrying at every attempt, which is the wrong starting point and what an agent does by default: the retry is the cheapest thing it can do. One of these repeats may charge a customer twice, one goes into a pause the API asked for, one is past its budget, and one should be handed to a person.

See it happen

Inside the loop

Loop: may go again
Slowed down so you can follow
SOURCE|+⟩and a coin in a boxBENCHDETECTORZ BASISanswers 0 and 1TALLYTHE QUBITTHE COIN
The agent calls a tool and the answer comes back, or does not. The loop decides what happens next, the system carries whatever the call did, and a person is available when the loop should not decide alone.
  1. The loop → The tool
  2. The tool → The system
  3. The tool → A person
STEP 1 / 6

Nobody is watching the loop

The loop calls The tool and decides what to do with the answer, in milliseconds, as many times as its budget allows. Everything a retry policy ever said is still true, and now it is behaviour rather than advice.

Configure

Your decision at each attempt

At each attempt, decide what the loop should do next. Read what a repeat means for that tool, what came back, and how much budget is left.

What should the loop do next?
Try again
· A repeat is safe and the budget allows it.
Ask what happened
· Find out before doing anything else.
Hand it to a person
· This one should not be decided by a loop.
Report it as failed
· Stop, and say so truthfully.
  1. R-901 — A create that timed out, on a tool that takes an idempotency key

    The loop does not know whether the first attempt landed.

    The call
    orders.create · recoverable · there is a way to ask what happened
    What came back
    nothing — the call timed out
    Where the loop is
    attempt 1 of a budget of 3
    A repeat
    the tool takes an idempotency key: a repeat is not done twice
  2. R-902 — A charge that timed out, on a tool with no key

    The same not-knowing, with money attached.

    The call
    payments.charge · irreversible · there is a way to ask what happened
    What came back
    nothing — the call timed out
    Where the loop is
    attempt 1 of a budget of 3
    A repeat
    the tool has no way to recognise a repeat
  3. R-903 — A 429 asking for fifteen minutes, two attempts in

    The API has said exactly what it wants, and it is longer than a loop can hold.

    The call
    orders.update · recoverable · there is a way to ask what happened
    What came back
    429, Retry-After 900 s
    Where the loop is
    attempt 2 of a budget of 5
    A repeat
    the call sets a value rather than adding one: a repeat lands the same
  4. R-904 — A 429 with no Retry-After, two attempts in

    Nothing to obey, and the call is safe to repeat.

    The call
    orders.update · recoverable · there is a way to ask what happened
    What came back
    429, with no Retry-After
    Where the loop is
    attempt 2 of a budget of 5
    A repeat
    the call sets a value rather than adding one: a repeat lands the same
  5. R-905 — A 500 on the first attempt of a call that sets a value

    The far end is in trouble; the call is safe to repeat.

    The call
    inventory.set · recoverable · there is a way to ask what happened
    What came back
    500 from the server
    Where the loop is
    attempt 1 of a budget of 3
    A repeat
    the call sets a value rather than adding one: a repeat lands the same
  6. R-906 — The same 500, with the budget spent

    Three attempts of three, still failing, and nothing for a person to decide.

    The call
    inventory.set · recoverable · there is a way to ask what happened
    What came back
    500 from the server
    Where the loop is
    attempt 3 of a budget of 3
    A repeat
    the call sets a value rather than adding one: a repeat lands the same
  7. R-907 — An email that timed out, with no way to ask whether it went

    No key, nothing to check, and it cannot be unsent.

    The call
    email.send · irreversible · nothing to ask afterwards
    What came back
    nothing — the call timed out
    Where the loop is
    attempt 1 of a budget of 3
    A repeat
    the tool has no way to recognise a repeat

What a repeat means for this tool, what came back, and how much budget is left. All three decide it.

Learn more

Why this pattern exists

Everything the reliability lessons say about retrying is still true here, and one thing has changed: nobody is watching. A person who gets a timeout retries, waits, and thinks about whether that was wise. A loop gets the timeout and goes again in milliseconds, and again, until something stops it — so the policy is not advice any more, it is the behaviour of the system. That makes three questions sharper than they were. Is a repeat safe, which is a property of the tool and not of the agent's confidence. Is there anything left in the budget, because a loop with no budget is an outage generator. And is there a person at the end of this, because "stop and ask" is a real answer for an agent in a way it never was for a retry policy in a config file.

An agent is working through a queue of order tasks, and each of these is a moment inside its retry loop. Every row shows the call, what came back, where the budget is, and what the tool does with a repeat. What actually happened at the far end is revealed only after the decision.

  • Read a repeat as a property of the tool: an idempotency key, a naturally idempotent call, or neither.
  • Keep a loop out of a pause the API asked for, and out of a budget it has already spent.
  • Choose between finishing the work, asking the system what happened, handing it to a person, and reporting failure honestly.

The rule this lesson applies: A repeat is safe when the tool says so, not when the agent is confident. An idempotency key makes a repeat a no-op for the same logical operation; a call that sets a value rather than adding one is naturally safe to repeat; anything else may do the work twice, and after a timeout the agent cannot tell whether the first attempt landed. That is the same reasoning as the Timeout lesson, with the loop turning a single bad decision into several. Two things belong to agents specifically. The first is the budget: a loop needs a number of attempts it may spend and a rule for what happens when they are gone, or it will keep going long after a person would have stopped. The second is escalation — an agent can hand the work to a person, which is the right answer exactly when the tool cannot be repeated safely and the effect cannot be undone, and the wrong answer when a safe repeat was sitting there and the budget was untouched. An agent that escalates everything costs more than the process it replaced; an agent that escalates nothing eventually does something nobody can undo.