An agent's final bad answer is often the last symptom, not the first failure. A missing customer ID can cause the wrong retrieval, which causes the wrong tool selection, which triggers a permission denial, which the agent misreads and retries until the task times out.
Diagnose the earliest broken contract. Preserve the task trace, mark where observed state first diverged from an explicit expectation, and repair that layer before tuning downstream prompts. The useful categories are task, context, trajectory, tool, state, policy, and runtime—not a flat list of model mistakes.
Capture the evidence before changing the system
Start with one user-visible task and its complete execution tree. At minimum, preserve:
trace_id and task_iduser, tenant, feature, and policy versionmodel, prompt, retrieval, tool-set, and application versionsinput and retrieved document identifierstool names, validated arguments, results, and receiptsapproval and authorization decisionsattempt number, retry owner, timeout, and terminal statefinal result, evaluator result, latency, and cost
Do not require the investigator to reconstruct a task from unrelated log lines. The production LLM observability schema shows how to preserve one task hierarchy while limiting sensitive content.
AWS's 2026 failure-detection guidance makes a useful distinction: detection labels the failed spans, while root-cause analysis traces the causal chain and separates primary from propagated failures. Its implementation is vendor-specific, but the distinction is general. A timeout, refusal, or malformed final answer can be secondary evidence rather than the cause. See AWS's trace-based failure detection and root-cause analysis.
Use seven layers instead of one failure list
The taxonomy below is organized by the contract that broke first.
| Layer | Broken contract | Typical symptom | Evidence to inspect first | First repair |
|---|---|---|---|---|
| Task | The requested outcome or boundary is ambiguous | Plausible result that solves the wrong problem | Original request, clarification state, success criteria | Narrow the task; add clarification and abstention cases |
| Context | Required or trusted information is missing, stale, mixed, or poisoned | Wrong entity, lost constraint, unsupported claim | Retrieved IDs, scores, versions, memory reads/writes | Fix retrieval, provenance, isolation, or context budget |
| Trajectory | The agent chooses an unacceptable sequence | Correct outcome after unsafe or wasteful steps | Ordered decisions, tool calls, approvals, evaluator labels | Add trajectory constraints and targeted evals |
| Tool | Selection, arguments, execution, or error contract fails | Wrong tool, invalid arguments, repeated error | Tool schema, validated args, status code, response | Split/rename the tool; tighten schema and errors |
| State | Resume, retry, or memory changes the intended operation | Duplicate side effect, lost progress, persistent corruption | Operation key, checkpoint, receipt, memory provenance | Add idempotency, reconciliation, durable state, write policy |
| Policy | Identity, authorization, or human control is missing or bypassed | Cross-tenant access or unapproved action | Principal, resource, policy version, decision, approval payload | Enforce policy outside the model; reduce authority |
| Runtime | Capacity, dependency, budget, or configuration cannot support the task | Timeout, loop, cost spike, cascading failure | Per-span latency/cost, retries, limits, dependency health | Bound execution; add backoff, fallback, or safe degradation |
This taxonomy is deliberately smaller than a catalog of every possible symptom. A category is useful when it tells the team where to inspect and who should own the repair.
Microsoft's AI Red Team taxonomy separates security from safety failures and distinguishes novel agentic failures from inherited AI failures whose impact increases under autonomy. It also notes that applicability depends on architecture and context. Use it when the incident may involve compromise, memory poisoning, agent impersonation, flow manipulation, or user harm—not as proof that every category applies to every system. See Microsoft's agentic AI failure taxonomy and the accompanying whitepaper.
Find the first divergence
Use this triage sequence on a failed trace:
- State the expected terminal outcome. Include acceptable abstention, clarification, or escalation.
- Mark the observed bad outcome and its immediate parent spans. This bounds the failure path.
- Walk backward until observed state matches expectation again. The next span is the earliest known divergence.
- Name the broken contract at that span. Avoid labels such as “the model was confused.” Specify the missing input, invalid selection, policy bypass, ambiguous receipt, or exhausted limit.
- Test the cause independently. Replay or unit-test that boundary without the rest of the agent when possible.
- Repair at the owning layer. Prompt changes should not compensate for a missing authorization rule or an ambiguous API.
- Add a regression case. Preserve the triggering state, expected behavior, and evidence that the containment works.
If two independent divergences exist, record both. A taxonomy should not force a complex incident into one label.
Walkthrough: the duplicate refund
Consider a support agent that calls refund_order:
09:41:02 policy approved refund request rr_81209:41:03 refund_order sent to payment provider09:41:13 client timed out; no response recorded09:41:14 agent classified the tool call as failed09:41:15 agent retried with a new request identifier09:41:16 second refund succeeded09:42:01 reconciliation found two provider receipts
The visible symptom is a duplicate refund. The agent's decision to retry is not yet the root cause. The earliest broken contract is at the state/tool boundary: the application treated “no response” as “no side effect” and generated a new operation identity.
The first repair is not “tell the model not to retry.” Use a stable business operation key, preserve an uncertain state after timeout, query for the provider receipt, and prevent a second effect until reconciliation completes. The idempotency and retry boundary covers that implementation.
The regression suite should kill the worker after the provider accepts the refund but before the receipt is stored. The test passes only if resume produces one business effect and one durable receipt.
Separate outcome failures from trajectory failures
The final result and the execution path answer different questions:
- Did the user receive the correct outcome?
- Did the agent reach it through an allowed, efficient, and recoverable path?
Grade both. A correct answer after accessing another tenant's record is a policy failure. A safe refusal after malformed tool arguments may be an outcome failure and a successful containment. The agent trajectory evaluation rubric separates selection, arguments, order, recovery, efficiency, and outcome so the repair signal survives.
Prefer deterministic checks for hard constraints: no write without approval, no cross-tenant resource, no repeated operation key with different arguments, no more than five tool calls, and no terminal success without a provider receipt. Use human or calibrated model review for semantic outcomes that code cannot determine reliably.
Treat security evidence as an incident path
If the trace suggests unauthorized access, poisoned memory, prompt injection, agent impersonation, credential theft, or deliberate flow manipulation, stop ordinary debugging. Preserve evidence, contain credentials and execution, and follow the security incident process.
Do not replay an attack against production data merely to improve reproducibility. Recreate the trust boundaries in an isolated environment, then use the agent prompt-injection test plan to turn the incident into a controlled regression suite.
Close the failure with ownership and a test
A useful incident record is short enough to act on and specific enough to reproduce:
Impact: two refunds for one approved requestEarliest divergence: timeout mapped to failed instead of uncertainRoot layer: state/recoveryContributing factor: retry generated a new operation keyContainment: disable automatic refund retryPermanent repair: stable key plus provider reconciliationOwner: payments platformRegression: worker death after provider effect, before receipt persistence
Do not close the issue because the prompt changed and the example stopped failing once. Close it when the owning contract is explicit, the failure is contained, and the regression test proves the repair at the correct boundary.
The next step is to apply this method to five recent failed traces and look for repeated root layers. If the same failures expose gaps across tool design, evaluation, state, and operations, the JoinAI MasterClass teaches the broader production engineering system behind those repairs.
