Classifying Agent Failure Modes
Build a taxonomy of agent failures: tool errors, malformed outputs, reasoning loops, context exhaustion, and external service unavailability, and design recovery strategies for each.
Why Agents Fail in Distinctive Ways
Agents fail differently from simple LLM calls. A single-turn call either returns an answer or throws an error. An agent executing a multi-step task can fail at any point — and the failure might not be obvious from the final output. Understanding the taxonomy of agent failure modes is the first step toward building agents that detect, diagnose, and recover from their own failures.
Failure Mode 1: Tool Errors
Tool errors occur when the agent calls a tool with invalid arguments, the tool raises an exception, or the tool returns an empty or malformed result. Examples include: calling a search API with a malformed query, querying a database with invalid SQL, or invoking a code executor that times out. Tool errors are the easiest to detect because they produce explicit exception signals that can be caught and handled.
class ToolError(Exception):
def __init__(self, tool_name: str, args: dict, error: Exception):
self.tool_name = tool_name
self.args = args
self.original_error = error
super().__init__(f'Tool {tool_name} failed: {error}')
def safe_tool_call(tool_func, args: dict) -> str:
try:
result = tool_func(**args)
if not result:
return 'Tool returned empty result. Try a different approach.'
return str(result)
except Exception as e:
raise ToolError(tool_func.__name__, args, e)All lessons in this course
- Classifying Agent Failure Modes
- Self-Correction and Reflective Prompting
- Checkpointing and Task Resumption
- Human-in-the-Loop Escalation