Error Handling & Retries

What you will be able to do

• ✓Name the three failures a hand-built agent meets, and who caused each one
• ✓Validate model output, and retry it with corrective feedback
• ✓Turn an unknown tool and a failing tool into Observations the model can act on
• ✓Explain why errors should neither crash the agent nor disappear silently
• ✓Count what retries cost, and bound them
• ✓Give the model a way out when no tool can help

The idea, in plain English

Everything that can go wrong in Lesson 1.6 eventually does. The model writes something that does not match the format. It asks for a tool that does not exist. It passes an argument the tool chokes on.

A sturdy agent expects all three and keeps going, and the interesting part is that each one gets a different fix - because each one was made by someone different. Unreadable output is the model’s mistake, so you tell it so and ask again. An unknown tool is the model reaching for something you never gave it, so you reply with the list of tools that exist - an Observation is the natural place, because the model reads Observations. A tool that raises is your code failing, so you catch it and hand back the error text instead of letting the exception end the run.

None of these crash the program, and none of them silently swallow the problem. The agent always finds out what went wrong and gets a chance to fix it. Two limits keep that from turning into a loop that never ends: max_steps for the whole run, and max_retries_per_step for each reply.

We ran the course code against a local model to see what each mechanism actually buys - and found one failure the three fixes do not cover.

Worked example: Add retry logic to the ReAct loop from Lesson 1.6.

Two loops

The outer loop - for step in range(max_steps) - is the agent: Thought, Action, Observation, repeat. The inner loop - for retry in range(max_retries_per_step) - only decides whether this one reply is usable. A reply is usable if it contains a Final Answer or an Action the regex can read.

Despite the name, max_retries_per_step=2 means two attempts in total: the first try and one retry. If both are unreadable the function returns "Agent failed to produce a valid step after retries" rather than trying forever.

Failure 1: output that cannot be read

In Lesson 1.6 an unreadable reply ended the run: "Agent got stuck". Now the loop appends "That wasn’t in the right format. Use Thought/Action or Final Answer." and asks again. The conversation has changed, so the next reply can too - unlike retrying the identical request at temperature 0, which Lesson 1.3 showed repeats the same failure.

It works. On "Should I bring an umbrella in Mumbai, and what’s 12 * 8?", eight runs each: the original loop got stuck twice and used both tools in six; run_agent_safe never got stuck or failed, and used both tools in seven. The price was about a quarter more model calls - 3.6 per question on average instead of 2.9.

Failure 2: a tool that does not exist

The model can only ask for tools it has heard of, so this usually means a mismatch - a tool in the prompt that never made it into TOOLS, the exact mistake Lesson 1.7 warned about. We listed a search(query) tool in the prompt but did not register it, and asked for the population of Hyderabad.

The error Observation did its job: the model read "search is not a valid tool" and the list of real tools. What it did next is the lesson. It tried read_file on a Google URL, then calculate on the words "population of Hyderabad", then get_weather on Hyderabad - every tool it had, none of which could help - until max_steps ran out. Three runs out of three.

Telling a model which tools exist also tells it, implicitly, that it should use one. It needs explicit permission to stop.

Failure 3: a tool that raises

try/except around the call turns any exception into text: "error running read_file: [Errno 21] Is a directory: ’.’". The agent keeps running, and the model knows that path did not work.

The opposite mistake is except: pass - no crash, but no one knows anything went wrong, least of all the model, which carries on as if the tool had returned nothing. An error the model never sees is an error it cannot recover from.

Watch out: Error text goes straight into the conversation. Keep it to what the model needs - a short reason - rather than full tracebacks with paths and internal details.

The failure none of the three cover

The course prompt allows exactly two kinds of reply: a Thought and Action, or a Final Answer after using tools. A question that needs no tool - "Hi! How are you today?" - fits neither comfortably, and in four of eight runs the agent failed even with the nudge. A question no tool can answer produced the tool-cycling above.

One line in the system prompt covers both: if the question needs no tool, or none of the tools can help, answer straight away with a Final Answer that says so. With it, greetings were answered four times out of four, and the Hyderabad question four out of four - three saying plainly that there is no search tool. The umbrella question still used both tools in three of four runs, as it had before.

The fourth Hyderabad answer is the reminder that robustness has limits: "According to Google, the population of Hyderabad is approximately 7.7 million" - a search result from a tool that does not exist. Error handling keeps the agent running. It cannot make the model honest.

Retries are not free

Every retry is another model call. With max_steps=5 and max_retries_per_step=2, one question can take up to ten calls - fine on a local model, worth counting anywhere you pay per call or users wait for a reply.

Keep both limits small and log when they are hit. An agent that regularly needs retries is telling you the prompt, the tools, or the model is the real problem.

Step-by-step code

Tip: Feeding the error back as an Observation works because models are good at correcting themselves when told plainly what was wrong and what the valid options are - as long as "none of them" is also a valid option.

Watch out: Retries cost a call each. With max_steps at 5 and max_retries_per_step at 2, one question can mean ten calls to the model - fine locally, worth counting anywhere you pay per call.

Three failures, three fixes

"That wasn't in the right format. Use Thought/Action or Final Answer."

f"error: '{tool_name}' is not a valid tool. Available tools: {list(TOOLS.keys())}"

except Exception as e:
    observation = f"error running {tool_name}: {e}"

answer straight away with a Final Answer that says so

max_steps=5, max_retries_per_step=2

Try it yourself

The code does not change. Swap the content string and the program does something else entirely.

What usually goes wrong

✗ try:
    observation = TOOLS[tool_name](arg)
except:
    pass

✓ try:
    observation = TOOLS[tool_name](arg)
except Exception as e:
    observation = f"error running {tool_name}: {e}"

✗ observation = TOOLS[tool_name](arg)

✓ if tool_name not in TOOLS:
    observation = f"error: ... Available tools: {list(TOOLS)}"

✗ while not valid(candidate):

✓ for retry in range(max_retries_per_step):

✗ Available tools:
- get_weather(city)
- calculate(expression)
- read_file(path)

✓ If none of these tools can help, answer straight away with a Final Answer that says so.

Quick check before you move on

1. 1.

   Name two different kinds of failure this code guards against.

   Show answer
2. 2.

   What does the code do when the model calls a tool that is not in TOOLS?

   Show answer
3. 3.

   Why wrap the actual tool call in try/except?

   Show answer
4. 4.

   With max_steps=5 and max_retries_per_step=2, what is the most model calls one question can take?

   Show answer
5. 5.

   The model is told "search is not a valid tool" and then tries every other tool on a question none of them can answer. What is missing?

   Show answer

Interview questions