How to Investigate AI Agent Failures Without Guessing
Use a repeatable triage order to separate intent, context, retrieval, tool, orchestration, policy, and outcome failures.
Short answer
Start from the failed user outcome and walk backward through the exact trajectory. Classify the earliest evidence-backed divergence—intent, context, retrieval, selection, arguments, execution, recovery, policy, or final response—before changing prompts or models.
Key takeaways
- The earliest meaningful divergence is usually more useful than the loudest downstream error.
- Preserve one coherent evidence packet for the whole run.
- Turn the confirmed cause into a minimal regression case before broad tuning.
Signs this is the problem
Start by confirming the symptom before changing prompts, models, or infrastructure.
- Teams debate the cause from screenshots or the final response alone.
- The same incident is labeled hallucination, tool error, and prompt problem by different reviewers.
- A broad prompt rewrite fixes one example but moves failures to another slice.
Step-by-step approach
- 1
State the failed outcome
Describe what the user needed, what actually happened, and why the difference matters. Avoid beginning with a theory about the model.
- 2
Reconstruct the trajectory
Order inputs, context, retrieval, decisions, tool calls, results, retries, approvals, output, and final state on one timeline with stable identifiers.
- 3
Find first divergence
Compare the failing path with an expected or successful path. Mark the first point where required evidence, action, or constraint diverged.
- 4
Prove the fix
Create the smallest representative case that fails before the change and passes after it, then rerun neighboring protected slices for regressions.
What to measure
| Metric | What it measures | How to use it |
|---|---|---|
| Failure-class coverage | Share of material failures assigned to a specific, evidence-backed stage. | Treat 'unknown' as a signal to improve capture, not as a prompt category. |
| Time to first divergence | Investigation time needed to locate the earliest wrong step. | Use decreases to validate better trace and comparison tooling. |
| Recurrence rate | Confirmed repeats of a failure after its fix was released. | A recurrence means the regression proof or deployment boundary was incomplete. |
Common mistakes
- Calling every incorrect answer a hallucination.
- Changing several prompts, tools, and models before reproducing the failure.
- Closing an incident without a durable case or an explicit reason coverage is impossible.
Practical checklist
- Describe the failed user outcome in plain language.
- Collect the complete run with stable IDs.
- Classify the earliest divergence.
- Change the owning layer only.
- Add regression proof and rerun adjacent slices.
Frequently asked questions
What is the best AI agent failure taxonomy?
Use stages your system can observe and teams can act on. Intent, context, retrieval, tool selection, arguments, execution, recovery, policy, output, and final state are a practical start.
Should traces store hidden chain of thought?
No investigation should depend on private reasoning. Store observable inputs, decisions, tool interactions, state transitions, outputs, and evidence your system is allowed to retain.
When is a failure not reproducible?
External state or nondeterminism may prevent exact replay. Preserve the original evidence and reproduce the governing conditions or invariant instead.