Courses / Agentic AI from Scratch (Python)
Session 22 of 40
When tools fail: tool errors, a step limit, and saying "I can't"
Notes
How to Handle Tool Errors and Step Limits in a LangChain Agent
Agentic AI Foundations · Session 22 — When tools fail: tool errors, a step limit, and saying “I can’t”
Before you start: what do I need before I make an agent fail safely?
You need the code folder for this session open in your terminal. It holds agent_safe.py, make_tickets_db.py, data/tickets.csv with the sample tickets, data/policies/ with the policy files, the copilot carried over from session 19 (helpdesk_rag.py and search.py), build_index.py and load_policies.py, model_prompts/agent.md with the new rule for a tool error, and one build prompt in prompts/. Install the libraries with pip install langchain langchain-openai langchain-chroma langchain-community langchain-text-splitters. You need the settings from earlier sessions (LLM_BASE_URL, LLM_API_KEY, LLM_MODEL, EMBED_MODEL). Two files are not in the lesson folder: policy_index/ and tickets.db, which you build with python build_index.py and python make_tickets_db.py. Recap of what this session assumes: an agent is a model that calls tools in a loop (session 20), and session 21’s agent has a ticket lookup over SQLite and the copilot as a tool. Have paper or a notes app ready for the Flashcards and the Model answer.
Summary: how does an agent handle a failing tool and a loop that will not end?
Tools break, and left alone a tool that raises an error stops the whole program, while a model that keeps asking for tools can loop on and run up cost. This session adds three guards to session 21’s agent. One function marked @wrap_tool_call catches any tool error and returns it to the model as a message that starts with Tool error. A rule in the system prompt tells the model that such a message means no result, so it should say it could not, name a human and not guess. A step limit, set as recursion_limit in the run’s config, stops a loop that will not finish, and the program catches the stop and answers in the agent’s place.
Key concepts: tool error, middleware, step limit and “I can’t” explained in plain English
| Term | Definition |
|---|---|
| Tool error | An exception raised while a tool runs, such as a database file that cannot be opened. |
@wrap_tool_call |
A LangChain decorator for a function that runs around each tool call, so one place can watch, change or catch what the tools do. |
| Middleware | Code placed around the agent’s loop; here catch_tool_errors is passed with middleware=[catch_tool_errors]. |
ToolMessage |
The message type that carries a tool’s result back to the model; the catcher builds one holding the error text. |
Tool error line |
The text the catcher returns, such as Tool error: lookup_ticket failed (OperationalError). It gave no result. |
| “I can’t” | A reply that states plainly what could not be done and who can help, instead of guessing a result. |
| Super-step | The unit LangGraph counts for the step limit: one round of the graph, in which one or more nodes may run. |
recursion_limit |
The key in the run’s config that caps how many super-steps one run may execute. |
GraphRecursionError |
The error LangGraph raises when the limit is exceeded; the program catches it and answers for the agent. |
Explanations: how do you catch tool errors and stop a runaway agent?
What happens when a tool fails, and how do you catch it?
Failure first. The ticket database cannot be opened and an employee asks, “What is the status of ticket T-1042?” With no catcher, lookup_ticket raises an error and the whole program stops with a traceback; the employee gets a crash and the model gets no chance to explain. In this session’s lookup_ticket there is no try of its own, on purpose: when the database cannot be opened, SQLite raises, and something else must deal with it.
Think of a shop assistant who finds the shelf empty. A good one says “we are out of stock” instead of walking off. A satnav told the road is closed plans another route and does not drive into the barrier. A tool error is that empty shelf: an exception raised while a tool runs. Handled, it becomes a message the model can read and explain.
@wrap_tool_call marks a function that runs around each tool call. LangChain’s docs describe it as wrapping each tool call with custom logic, and a wrap-style hook decides when, and how often, the handler is called. Picture a security guard at one door: visitors pass the same desk whichever room they are going to. One catcher covers the whole tool list, so a tool you add later is protected without new code:
@wrap_tool_call
def catch_tool_errors(request, handler):
try:
return handler(request)
except Exception as error:
name = request.tool_call["name"]
print(f" caught : {name} failed with ...")
return ToolMessage(
content=f"Tool error: {name} failed "
f"({type(error).__name__}). It gave no result.",
tool_call_id=request.tool_call["id"])
handler(request) runs the tool. If it raises, the catcher prints a caught line for you, the developer, and returns a ToolMessage instead. That message becomes the tool’s result, so the model reads it and decides what to say. The agent is built with it: create_agent(model, tools=[lookup_ticket, ask_policy], system_prompt=system_text, middleware=[catch_tool_errors]).
The message names the tool and the kind of error, not the raw error text. LangChain’s tool-error middleware docs give the same advice: prefer content that names the exception type over the raw message, which may carry sensitive or internal detail. Telling the model that the tool failed, and nothing more than it needs, keeps a file path or a query out of what the employee sees.
How do you tell the model to say “I can’t”?
A waiter who says the kitchen is out of fish lets you choose again. One who says “coming right up” and brings nothing leaves you hungry and cross. A courier with no one home leaves a card saying the parcel was not delivered, not a note saying it was. A model asked for a result can write one that sounds right, so the instructions must tell it that “I could not” is an acceptable answer.
The rule lives in model_prompts/agent.md:
If a tool returns a line that starts with "Tool error",
the tool did not work and you have no result from it.
Do not guess what the result would have been. Say
plainly in one or two sentences that you could not get
it, and tell the person to ask a human on the help
desk team. Do not call the same failing tool again.
Three rules sit in it: a Tool error means no result; say you could not, and name a human; do not call the failing tool again. The catcher’s message starts with those same words, which is how the code and the prompt meet: the code produces Tool error, and the prompt says what to do when the model sees it. The prompt also tells the agent to say plainly when a tool says it does not know or finds nothing.
What is a step limit, and how do you set one?
A kitchen timer rings and the dish comes off the heat, whatever happens. A phone plan with a data cap stops a small mistake from turning into a large bill. A step limit is that cap on an agent: it ends a run that would otherwise loop on. The limit goes into the run’s config as recursion_limit. LangGraph’s docs describe it as a cap on how many super-steps one run may execute, and say that exceeding it raises GraphRecursionError. A super-step is one round of the graph, and nodes that run side by side share one, so the count is rounds, not individual model turns or tool runs. In agent_safe.py, STEP_LIMIT = 10 is the limit for the first two cases, and the third case passes 3 on purpose, a limit too low for a ticket lookup followed by a policy question.
try:
result = agent.invoke({"messages": [("user", question)]},
config={"recursion_limit": limit})
except GraphRecursionError:
print(" STOPPED : step limit reached")
print("answer: I could not finish this within my step "
"limit. Please ask a person to help.")
return
The catcher handles a failure inside one tool call; the step limit handles a loop that will not end. Handle the errors you expect, and cap the loop for the ones you do not.
What does the agent print in each of the three cases?
Run python agent_safe.py. It runs three cases: a tool that works, a tool that fails (the database path points into a folder that does not exist) and a step limit that is too low. Ours printed (long lines trimmed with ...):
=== tool works (step limit 10)
question: What is the status of ticket T-1042?
act : lookup_ticket({'ticket_id': 'T-1042'})
observe : T-1042: Carry over ... status: open | assignee: Priya
answer: Ticket T-1042, ... is open and assigned to Priya.
=== tool fails (step limit 10)
question: What is the status of ticket T-1042?
caught : lookup_ticket failed with OperationalError: unable ...
act : lookup_ticket({'ticket_id': 'T-1042'})
observe : Tool error: lookup_ticket failed (OperationalError). ...
answer: I could not retrieve the status of ticket T-1042. Please ask a human on the help desk team.
=== step limit hit (step limit 3)
question: Look up ticket T-1042, then ask the policy helper ...
STOPPED : step limit reached
answer: I could not finish this within my step limit. Please ask a person to help.
Case two is the same question as case one, but the database cannot be opened. The tool raised an error, catch_tool_errors caught it (the caught line) and turned it into a tool result that starts with Tool error, and the model, following agent.md, said it could not get the answer and sent the person to a human. Case three needs two tools one after the other, the ticket and then the policy about its subject, which did not fit inside a limit of 3 in our run, so the limit stopped the loop. If your case three finishes instead, the model asked for both tools in one turn; lower the limit to 2.
What goes wrong when an agent has no guards, and what does it mean for the design?
Before the design table, three situations you will meet:
- The ticket database cannot be opened and the whole request stops with a long error. The exception was not caught, so the employee sees a crash and the model gets no chance to explain.
- The model invents a ticket status after the tool failed. The prompt did not tell it that “I could not” is an acceptable answer.
- The agent keeps asking for tools and does not answer. Nothing limits how many steps one question may take.
What these mean for the design:
| What you learned | The design decision | Where it shows |
|---|---|---|
| Tools raise errors | Catch them in one place and return a message | catch_tool_errors |
| A model may guess after a failure | Tell it to say “I can’t” and name a human | model_prompts/agent.md |
| A raw error can carry internal detail | Return the tool name and the error type | The ToolMessage text |
| A loop can run away | Set a step limit and catch the stop | recursion_limit, GraphRecursionError |
Basic assignment: run python build_index.py, python make_tickets_db.py and python agent_safe.py. For each of the three cases, write down whether the tool worked, failed or the agent was stopped, and which printed line told you.
Project step: break it and fix it. Remove middleware=[catch_tool_errors] from create_agent and run the second case: read the traceback. Put it back. Delete the “Tool error” paragraph from model_prompts/agent.md and run case two a few times: does the model still say it could not get the ticket, or does it invent a status? Change the limit in case three to 6, then 10, and find when the agent finishes. The build prompt is prompts/1-write-agent-safe.md. Stop when you can explain each change you saw.
Flashcards: test yourself on tool errors, step limits and “I can’t”
Say the answer aloud before revealing it. Speaking is a different skill from reading, so practise both.
1. What is a tool error?
An exception raised while a tool runs, such as a database file that cannot be opened. Left alone it stops the whole program; caught, it can become a message the model reads.2. What does `@wrap_tool_call` do?
It marks a function that runs around each tool call. `catch_tool_errors` uses it to run the tool inside a `try` and return a message if the tool raises.3. Why catch tool errors in one place and not in each tool?
One catcher covers the whole tool list, so a tool you add later is protected without new code. Each tool stays short and simply raises when it cannot do its job.4. What does the catcher return when a tool fails?
A `ToolMessage` whose text starts with `Tool error`, names the tool and the error type, and says the tool gave no result. The model reads it as the tool's result.5. Why not give the model the raw error text?
Raw text can carry internal detail such as a file path. LangChain's docs prefer content that names the exception type, so the model learns that the tool failed and little else.6. What does the system prompt tell the model to do after a `Tool error`?
Treat it as no result and not guess. Say plainly in a sentence or two that it could not get it, tell the person to ask a human, and do not call the same failing tool again.7. Why is "I could not do that" better than a confident answer?
A model asked for a result can write one that sounds right. If the tool failed, an invented status is wrong and the employee may act on it; an honest "could not" lets them ask a person.8. What is a step, and how do you set a step limit?
The limit counts super-steps, which are rounds of the graph in which one or more nodes run. You set the limit with `config={"recursion_limit": limit}` in the call to `agent.invoke`.9. What happens when the step limit is reached?
LangGraph raises `GraphRecursionError`. `agent_safe.py` catches it, prints `STOPPED : step limit reached` and answers that it could not finish and a person should help.10. How do the catcher and the step limit differ?
The catcher handles a failure inside one tool call. The step limit handles a loop that will not end. You need both, because one does not replace the other.Model answer: how do I explain handling a failing tool and a runaway agent in an interview?
The core question this session answers: “A teammate asks: the ticket system was down and the agent crashed. How should an agent handle a failing tool, and how do you stop a runaway loop?”
Four beats a teammate listens for, in this order: catch the error · keep detail out · say “I can’t” · cap the loop. Skip any of these four and the answer is incomplete.
- Catch the error: one catcher turns a tool’s exception into a message for the model.
- Keep detail out: name the tool and the error type, not the raw text.
- Say “I can’t”: the prompt tells the model to say what it could not get and name a human.
- Cap the loop: a step limit stops a run that will not finish.
The full answer, said aloud:
(Catch the error) “One catcher wraps the tool calls. If a tool raises, it returns a result that starts with Tool error instead of letting the program crash, so the model can read it.
(Keep detail out) The message names the tool and the error type, not the raw error text, which may carry internal detail.
(Say “I can’t”) The system prompt says a Tool error means no result: do not guess, say you could not, and tell the person to ask a human.
(Cap the loop) A step limit in the run’s config stops a loop that will not end. The program catches the stop and answers that it could not finish.“
Missing a beat is a failure state. The follow-up question lands where you went quiet: leave out the last beat and the next question is what stops the agent calling a failing tool forever. Practise until the four come out without prompting, then stop talking and let the questions come.
Why this matters: why do tool errors and step limits matter at work?
In a conversation with a teammate or manager: people ask what the employee sees when a system is down and what stops an assistant looping and running up cost. A catcher, a prompt rule and a step limit are concrete answers.
On the job: real tools can fail, whether it is a database, a ticket system or a web service. Deciding in advance what the model says when one does is part of reviewing an AI feature, as is checking that an error message does not leak internal detail.
In the rest of this course: sessions 23 to 28 put this agent inside a graph you can see, where the same ideas of limits and honest failure return, and sessions 29 to 32 add outside tool servers and several agents.
After this unit: what do I do after this lesson, and what comes next?
Assignment. Remove the catcher and read the traceback, then put it back and run the three cases. The project work, breaking the guards one at a time, is set out in the project brief. Keep agent_safe.py and your tickets database.
What’s next. Session 23 starts LangGraph basics: state, nodes and edges, so the agent becomes a workflow you can see.
Want help building this with someone?
Tell us what you are working on and we will write back about a mentor-led cohort, live sessions or 1:1 training. It is only an enquiry: you choose whether to go further.
Ask about mentor-led trainingTechEazy Consulting training material — not affiliated with or endorsed by OpenAI, Anthropic, LangChain or any other company named in this course.