Debugging Agent Failures
Agents fail in weird ways. Here's a guide to the most common failure modes and how to fix them.
Common Failure Modes
1. Hallucinated Success
Symptom: Agent says "done" but nothing happened.
Cause: Agent assumes success without verification.
Fix: Always verify outputs—check files exist, APIs returned success.
2. Tool Selection Errors
Symptom: Agent calls wrong tool or uses wrong parameters.
Cause: Unclear tool descriptions or ambiguous prompts.
Fix: Improve tool descriptions, add examples in system prompt.
3. Context Overflow
Symptom: Agent forgets early instructions.
Cause: Too much context, hitting token limits.
Fix: Summarize old context, use vector search instead of including everything.
4. Infinite Loops
Symptom: Agent repeats same action endlessly.
Cause: No termination condition, goal never satisfied.
Fix: Add max iterations, explicit stop conditions.
5. Silent Failures
Symptom: Agent stops responding, no error message.
Cause: Unhandled exceptions, timeouts.
Fix: Comprehensive error logging, try/catch everywhere.
Debugging Workflow
- Reproduce — Isolate the failing scenario
- Enable verbose logging — See every step
- Trace the decision path — Where did agent go wrong?
- Identify root cause — Prompt? Tool? Context?
- Fix and verify — Test the specific case
- Document — Add to feedback memory
Essential Logging
- All LLM requests and responses
- Tool calls with parameters
- Decision reasoning
- Error messages with stack traces