OpenAI Agents SDK · Chapter 19 of 24
Errors and limits
By the end of this chapter you can say what can go wrong in an agent run and what the SDK raises for each (a loop that never ends, a reply cut short, a provider that is down, a model that is too slow, a tool that fails), catch each one, fall back to another model, let the model fix a bad tool call, and answer a parent politely when nothing works. Build it in your browser: a real editor and terminal, AI that explains, and tests that tell you when it works.
- Part: Production
- 4 tasks
- Python
- In the all labs plan
The first 2 chapters of OpenAI Agents SDK are free. This one comes with the all labs plan.
Why you need this
Shikhar's assistant is about to answer every parent on WhatsApp. Karthik has seen what happens in production: the provider's servers are overloaded for ten minutes at exam time, one request hangs for half a minute, a model asks for the same tool again and again, a tool gets an argument it cannot use. Kavita has one rule: a parent never sees a traceback, and never waits forever.
Until now your programs simply stopped with a traceback when a run went wrong. That is fine in a lab and unacceptable at a helpdesk. This chapter makes each failure happen on purpose, with the lab's faulty models, so you know its name before you meet it.
What you build: 4 tasks
Each task has tests. You write the code in the lab's editor and press Check.
- Task 1
errors.py: what fails, and what the SDK raises
Make a fees desk: an agent for lab-chat with the instructions You are Shikhar Classes' fees desk. Use the tools. and a tool fee_status(student_id) returning json.dumps of shikhar.fee_status. Run it on S2041 ki fees kitni baki hai? four times, in this order, each with a clone of the same agent: on lab-chat-slow with model settings timeout=1.5; on lab-chat-down as it is; on lab-chat-loopy with the run's max_turns=3; on lab-chat with model settings max_tokens=5.
Catch each run's error and print one line per run: the model's name, a colon and a space, the error's class name, a colon and a space, and the error's message (str of it). One failing run must not stop the program.
- Task 2
fallback.py: a second model when the first is down
Make the fees desk of task 1 on lab-chat-down and run it on S2052 ka next instalment kab due hai? When the run fails with the openai client's status error (a 503 here), run a clone of the agent on lab-chat-mini on the same message.
Print the final output of the run that answered, then a last line Answered by: and the model of the result's last agent (read it, do not type it in). Catch the status error only.
- Task 3
polite.py: fail politely
Write answer(question, model) that runs the fees desk (instructions You are Shikhar Classes' fees desk. Use the tools., model settings with a timeout of 2 seconds) on the question with the run config's model set to model and max_turns=4, and returns the final output. When the run fails, it returns exactly: Sorry, I cannot answer right now. Bhanu will call you back.
Its fee_status tool has a failure_error_function: when the tool fails, the model receives json.dumps of an object with one key, error, saying what went wrong, so it can try again. Catch only a run's errors (the SDK's base class and the openai client's), not Exception.
The Check calls answer with lab-chat-slow, lab-chat-down, lab-chat-loopy, lab-chat-confused (one wrong argument in its first tool call) and lab-chat.
- Task 4 · interview question
Interview: retry_or_fallback.py, retry or fall back
Ask the fees desk S2030 ki fees ka kya status hai? two ways, timing each with time.perf_counter. First on lab-chat-flaky (it fails twice, then answers), with the openai client's retries left as they are. Then on lab-chat-down, falling back to a clone on lab-chat-mini as in task 2, timing both runs together.
Print two lines: Retry: lab-chat-flaky answered in 4.80s, then Fall back: lab-chat-mini answered in 2.10s (the model's name from each result's last agent; your seconds, two decimals).
The interviewer will ask: when should Shikhar's assistant retry the same model, when fall back to another, and when stop and say sorry? What does each cost?
What you will learn
- What fails, and what is raised: MaxTurnsExceeded, ModelBehaviorError, ModelTimeoutError from the SDK, and the openai client's APIStatusError after its own retries.
- Two families: the SDK's AgentsException and openai's APIError.
- Falling back to another model when one is down.
- A tool that fails: what the model is told, and failure_error_function.
- Failing politely: one function a parent can never crash.
More in Production
Build "Errors and limits" yourself
Shikhar Classes, a Kota coaching institute, answers parents and students on WhatsApp all day. You build its helpdesk assistant. A real editor and terminal in your browser, AI that explains, and a Check that says when it works.
The first 2 chapters of OpenAI Agents SDK are free. This one comes with the all labs plan.