Error Handling and Recovery

Learn how to make agents resilient: classify tool failures, retry with exponential backoff, add fallbacks and timeouts, choose recovery strategies, and prevent infinite loops.

28 minIntermediateCode Examples

The Core Idea: Tools will fail: networks drop, services time out, models make bad calls. A reliable agent expects failure: it retries temporary errors, uses fallbacks, enforces timeouts, recovers with a plan, and stops loops before they burn money.

  1. Beginner: Tool Failures

Every external tool can fail. Knowing what kind of failure it is decides the right response:

Failure typeExampleTemporary?Typical response
Network or service error503 service unavailableYesRetry with backoff
Rate limit429 too many requestsYesWait, then retry
TimeoutNo answer in 30 secondsMaybeRetry once, then fall back
Bad requestMissing or wrong argumentNoFix the call, do not repeat it
Permission deniedNo access to the fileNoStop or ask for access
Wrong resultTool returns empty or nonsenseMaybeValidate and try another tool

Key idea: Do not treat every error the same. Retry what is temporary. Fix or report what is permanent.

  1. Beginner: Retries

A retry simply tries again. Done badly, it makes outages worse. Done well, it hides small glitches from the user. Use exponential backoff: wait 1 second, then 2, then 4, and so on, with a small random delay (jitter) so many clients do not retry at the same instant.

In the code: The flaky tool fails twice and succeeds on the third try. The agent waited 1 s and 2 s between attempts, 3 seconds of simulated time in total.

Never retry blindly: Do not retry errors that cannot change, such as a bad argument. And never retry an action with side effects, such as a payment, unless it is idempotent (safe to repeat).

  1. Medium: Fallbacks and Timeouts

A fallback is a plan B when the main option keeps failing: another tool, cached data, a simpler method, or an honest message. A timeout limits how long to wait, so one slow tool cannot freeze the whole agent.

FallbackExample
Cached dataShow yesterday's prices, marked as possibly old
Alternative toolSearch engine B if search engine A is down
Simpler methodSummarize titles only if the full page cannot be fetched
Ask the userRequest the missing information
Honest failureTell the user what failed and what was tried

In the code: The slow tool took 12 seconds against a 5 second limit, so the call is cut off with a clear timeout error that the agent can react to.

  1. Medium: Recovery Strategies

When something fails, the agent chooses a recovery strategy. Roughly from cheapest to most expensive:

1
Retry: The error looks temporary.
2
Repair the call: The model sent a bad argument. Return the error and let it correct the call.
3
Switch tools: Use a fallback or another route.
4
Replan: Change the plan around the broken subtask, keeping finished work.
5
Escalate: Ask a human or stop with a clear report.
Good error messages
Return errors the model can act on, such as missing argument: order_id, instead of a long stack trace.

  1. Advanced: Preventing Infinite Loops

The most expensive failure is an agent that never stops. Defend in layers:

GuardHow it works
Maximum stepsA hard limit on the number of loop iterations
Repeat detectionIf the last three actions are identical, stop or change approach
BudgetsLimits on tokens, time and money per run
No-progress checkIf the state has not changed for several steps, escalate
Retry capsA fixed number of retries per tool

In the code: The confused agent repeats the same search. The loop detector fires at step 3 and stops it. Without a guard, this would repeat until the budget is gone.

  1. Visual Explanation: Four Defenses and a Recovery Ladder

The figure shows the four defenses from the code, then orders the recovery strategies from cheapest to most expensive.

Part 1 · Four Defenses in the CodeEach handles a different failure
RetryTemporary error
Fails, waits 1 s
↓
Fails, waits 2 s
↓
Third try works
↓
fresh data
FallbackPrimary stays down
Two attempts fail
↓
cached data
TimeoutTool too slow
12 s taken, limit 5 s
↓
Cut off with an error
Loop guardSame action repeated
3 identical actions in a row
↓
Stopped at step 3
Part 2 · Choosing a RecoveryCheapest first
Retry
Temporary
Backoff and jitter.
Repair
Bad call
Return the error.
Switch
Tool down
Fallback tool.
Replan
Broken step
Keep finished work.
Escalate
Cannot fix
Ask a human.
Click to see why retries need jitterCompare ▼
If a thousand clients all retry at exactly 1 s, 2 s and 4 s, they hit the recovering service together and knock it down again. A small random delay spreads them out.

Part 1 maps each failure to its defense. Part 2 is a ladder you climb only as far as needed. Open the bar to learn why jitter matters.

  1. Python Implementation: Retries, Fallbacks, Timeouts and a Loop Guard

This script uses a fake clock so it runs instantly. It retries a flaky tool with exponential backoff, falls back to cached data when the primary tool stays down, cuts off a slow tool with a timeout, and detects an agent repeating the same action.

error_handling.pyPython 3.10+ · standard library only
# Error handling: retries with backoff, fallbacks, timeouts and loop detectionclass FakeClock:                      # so the demo runs instantly instead of really waiting    def __init__(self):        self.now = 0    def sleep(self, seconds):        self.now += seconds clock = FakeClock()attempts = {"flaky": 0} def flaky_tool():                     # fails twice, then works    attempts["flaky"] += 1    if attempts["flaky"] < 3:        raise ConnectionError("503 service unavailable")    return "fresh data" def with_retry(fn, max_attempts=4, base_delay=1):    for attempt in range(1, max_attempts + 1):        try:            return fn()        except ConnectionError as error:            if attempt == max_attempts:                raise            delay = base_delay * 2 ** (attempt - 1)        # 1, 2, 4 seconds...            print("  attempt", attempt, "failed (" + str(error) + "), waiting", delay, "s")            clock.sleep(delay) print("1. Retry with backoff ->", with_retry(flaky_tool), "| simulated waiting:", clock.now, "s") def primary_tool():    raise ConnectionError("primary down") def fallback_tool():    return "cached data (may be old)" def with_fallback():    try:        return with_retry(primary_tool, max_attempts=2)    except ConnectionError:        return fallback_tool() print("2. Fallback ->", with_fallback()) def slow_tool():    return "report", 12                                    # result and the seconds it took def with_timeout(tool, limit):    result, seconds = tool()    if seconds > limit:        raise TimeoutError("took " + str(seconds) + "s, limit is " + str(limit) + "s")    return result try:    with_timeout(slow_tool, limit=5)except TimeoutError as error:    print("3. Timeout ->", error) def detect_loop(actions, window=3):    last = actions[-window:]    return len(last) == window and len(set(last)) == 1 actions = []for step in range(1, 10):    actions.append("search:weather today")                 # a confused agent repeats itself    if detect_loop(actions):        print("4. Loop detected at step", step, "-> stop and change approach")        break
EXPECTED OUTPUT (your numbers may differ slightly)
attempt 1 failed (503 service unavailable), waiting 1 s
attempt 2 failed (503 service unavailable), waiting 2 s
1. Retry with backoff -> fresh data | simulated waiting: 3 s
attempt 1 failed (primary down), waiting 1 s
2. Fallback -> cached data (may be old)
3. Timeout -> took 12s, limit is 5s
4. Loop detected at step 3 -> stop and change approach

Each of the four defenses fires on its own kind of failure: the retry recovers a temporary error, the fallback covers a longer outage, the timeout bounds slow work, and the loop detector stops the repeating agent. Together they turn crashes into controlled outcomes.

Knowledge Check

Question 1: Which error should an agent NOT retry?
Question 2: What does exponential backoff mean?

Key Points

✓Classify failures: temporary errors get retries, permanent errors need a fix or a report.
✓Use exponential backoff with jitter, and retry only safe or idempotent actions.
✓Fallbacks give a plan B: cached data, another tool, a simpler method or an honest message.
✓Timeouts stop one slow tool from freezing the agent.
✓Recovery goes from retry to repair, switch, replan and escalate.
✓Prevent infinite loops with step limits, repeat detection, budgets and retry caps.

The Big Picture

Reliability in One Line

Expect failure → classify it → retry or fall back → replan or escalate → never loop forever

Resilient agents turn most failures into small delays instead of broken tasks.

Up Next: Some actions should not happen without a person's say-so. In Human-in-the-Loop and Guardrails you will learn approvals, permissions and validation.