NOTES / AGENTIC DESIGN PATTERNS
Error handling and recovery
How an agent should treat failures: return them as readable results, classify them, retry what is worth retrying, and stop what is not.
Failures are normal
Tools time out, APIs rate-limit, arguments come out malformed, files do not exist. An agent that treats every failure as fatal is brittle; one that retries everything forever burns money. The design question is what the agent sees when something goes wrong, and what the harness does about it.
Return the error as a result
In Anthropic’s API you still send back a tool_result, with is_error set to true and the message in the content1. The model reads that result and chooses what to do next4. The SDK tool runner does this for you: when a tool throws, it catches the exception and returns it as an error result carrying the exception message rather than the full stack trace2.
Diagram: my own, following the is_error mechanism in 1 and 2.
For invalid calls, such as missing parameters, Anthropic’s documentation says Claude will retry two or three times with corrections before apologising to the user, and that strict tool use can eliminate invalid calls1.
MCP draws a similar line. It separates protocol errors, for problems with the request itself such as an unknown tool, from tool execution errors, which are reported in the result with an error flag set4.
Write errors the model can act on
The message is the model’s only information. Anthropic’s example is that a rate-limit error which says when to retry gives Claude what it needs to recover, whereas an opaque failure does not1. Tian Pan makes the same point: error quality decides whether the agent corrects itself or enters a retry loop that burns tokens without converging, and a generic {"error": "invalid input"} is useless3.
Diagram: my own.
Classify, then respond
The classification below is my own working scheme, not a standard.
Diagram: my own.
| Class | Examples | Who handles it | Response |
|---|---|---|---|
| Transient | timeout, rate limit, 5xx | harness, below the model | retry with backoff and a small cap |
| Fixable input | missing or wrong argument | model, via the error result | explain the problem, let it retry |
| Permanent | not found, permission denied | model and user | stop retrying, report, or ask |
Handling transient errors in the harness keeps them out of the context window. Fixable-input errors belong in the model’s view because it can fix them. Permanent errors should end the attempt: repeating an identical failing call is the classic no-progress loop.
Recovery strategies
- Retry with the same call only for transient faults, with exponential backoff and a limit.
- Retry with changes when the error explains what to change.
- Try another route: a different tool, a smaller step, or a different query.
- Degrade gracefully: return a partial result and say what is missing.
- Escalate to a person (Human in the loop) when the same failure recurs.
- Resume, do not restart: with checkpoints, a crash costs one step rather than the whole run.
Watch for silent failures
The worst failure is one nobody saw. Verification steps are one defence: the MAST study of multi-agent systems found that missing or incorrect verification is a recurring failure category5. Check the outcome, not only the call: see Trajectories and outcomes and Tracing and monitoring.
Sources
- [1]Handle tool calls — Anthropic, Claude Platform docsPARAPHRASED
- [2]Tool runner (SDK) — Anthropic, Claude Platform docsPARAPHRASED
- [3]Writing Tools for Agents: The ACI Is as Important as the API — Tian Pan · tianpan.co · 2025PARAPHRASED
- [4]Designing Tool Errors for Agents — Trida AI, DEV CommunityPARAPHRASED
- [5]Why Do Multi-Agent LLM Systems Fail? — Mert Cemri and co-authors · arXiv · 2025FURTHER READING