Loading learning content…
Loading learning content…
Systematic approaches to finding and fixing agent failures without going insane.
Read through the lesson, mark it complete when the concept is clear, then move to the next lesson in the sequence or jump back to the module map.
Agent bugs differ from traditional software bugs. They're often probabilistic (happens 30% of the time), emergent (only appears in multi-step sequences), and hard to reproduce deterministically.
This requires a different debugging methodology.
Before debugging, classify the failure:
Each class has different fixes. Mixing them up wastes time.
Find the smallest input that reliably triggers the failure. Start with the full failing case and systematically simplify:
When you have a minimal reproduction, the fix is usually obvious.
Most agent bugs are prompt bugs. Diagnosis:
Fix: add explicit instructions for the failure case, or add a few-shot example.
Log every tool call input and output. When a tool fails:
Each of these is a separate failure mode.
Use the systematic-debugging skill for a structured 6-step debugging workflow. Never debug by intuition alone on agent failures — the state space is too large.