AI Agent Error Handling: Retry, Timeout, Size Cap

Part 17 of the free AI Engineer course: how to handle messy AI agent tools. Real tools fail for a moment, run slowly, and return far too much. You learn when to retry (transient errors only), how to add a timeout, how to page and cap big results, and how to write error messages that tell the model what to try next. The "model" in the demos is a mock I wrote by hand, not a real AI, and the failing and slow tools are made up on purpose. In this video: - Three kinds of mess: fail, slow, too big - Retry transient errors only, with backoff, and only for read tools - Timeouts, and what a timeout in Python does not do - Paging and a size cap with a clear cut note - A real run: the agent pages through a log and recovers from a timeout - Tool design lessons from Anthropic: search not read-all, consolidation, naming, measuring - 25 tests, 4 exercises and a quiz CHAPTERS 0:00 Start here: messy AI tools 1:17 Why real tools are messy 2:39 Tools that fail 5:10 Slow tools 6:52 Big results 9:07 The agent survives 10:48 Designing for the agent 12:40 Testing the mess 14:14 Put it together 15:17 Your turn 16:49 Check yourself COURSE CODE (Parts 1 to 17) Part 17 files: guard.py, messy_tools.py, agent.py, schema.py, tools.py, mock_messy_model.py, demo17.py, test_messy.py. No extra packages (Python 3.11+). EXERCISES 1. Add a tool that returns a huge result, run it through a small cap, then write a paged version and test both. 2. Add a small random delay (jitter) to the retry waits, and keep the tests fast by passing in the sleep and random functions. 3. Give the slow tool its own deadline inside the tool, so it really stops its work, and compare with the wrapper timeout. 4. Stretch: run the same three goals with a real model function (key in .env, never in code) and note what it does differently from my mock. HONEST NOTES - I had no model key and my workspace cannot reach public APIs, so no real model and no real service was used. The mock model is hand-written rules, not an AI. The checkout log, the carrier service (it fails on purpose for its first two calls) and the slow report are made up. The retry, timeout, size cap, paging and tests are real code. The terminal screens are real runs of my own code (Linux, Python 3.13, 5 Nov 2026); some lines were shortened by the code itself to fit. Token numbers are a rough estimate (about 4 characters per token). Windows not tested. - My timeout stops WAITING; a Python thread cannot be killed, so the slow function may keep running. Only read tools are retried; tools that change things need more care (next part). The retry has no random delay. - Facts from Anthropic's article "Writing effective tools for agents" (published 11 Sep 2025, read 5 Nov 2026): pagination/filtering/truncation with sensible defaults, Claude Code's default cap of 25,000 tokens per tool response, concise vs detailed responses (72 vs 206 tokens in their example), actionable error messages, search tools over read-everything tools, consolidating chained tools, namespacing, and tracking tool errors and runtime. They can change. No prices quoted. SOURCES (read 5 Nov 2026) Anthropic, Writing effective tools for agents: https://www.anthropic.com/engineering/writing-tools-for-agents Anthropic, Tool use overview: https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview Subscribe to AI Made Clear for plain English AI tips. Disclosure: the voice is AI-generated. Screens labelled real run are real terminal output from my own code with a mock model (not a real AI); other screens are illustrations. Anthropic, Python and other names belong to their owners. This channel is not affiliated with any company named. Business inquiries: rabbihossain01941@gmail.com #AIEngineer #AIAgents #Python