To build a failure taxonomy for an AI agent, name failures by the workflow stage, observable symptom, consequence, detectability, and recovery path. Do not place every bad answer under hallucination. That label cannot tell an engineer whether retrieval failed, a policy was absent, a tool call was malformed, or a reviewer accepted unsupported output.
The taxonomy is an operating interface between product, engineering, security, operations, and the business owner. Each label should lead to a different investigation or control. If two categories never change the response, they may not need to be separate.
Start with the agent’s execution chain
Map the stages from trigger to destination: intake, identity and permission, context retrieval, planning, model output, validation, tool use, human review, external action, confirmation, and logging. A failure can originate in one stage and become visible later. Record both locations.
Create top-level families that remain stable across releases. Useful families include input and identity, source and retrieval, instruction and policy, reasoning and unsupported assertion, tool selection and arguments, authorization, state and concurrency, handoff, output destination, and evidence or receipt.
The article on company memory beyond vector search helps distinguish retrieval quality from mere similarity. Its architecture does not prove the source behavior of another agent, so the new system still needs traceable cases.
Write coding rules with concrete boundaries
For each label, provide a definition, inclusion rule, exclusion rule, example, counterexample, severity guidance, and likely owner. A missing source and a source ignored by the model are different. A correct tool chosen with forbidden arguments differs from an unauthorized tool that should never have been available.
Allow a primary label plus contributing factors. An expired credential may cause a tool failure, while poor recovery logic turns it into an abandoned customer task. The primary code should represent the failure that most directly determined the outcome; secondary codes preserve the causal chain.
Assign severity from consequence. Consider unauthorized disclosure, irreversible action, financial or safety impact, blocked workflow, recoverability, affected scope, and time to detection. An absurd answer caught before use can be less severe than a plausible error that quietly reaches a downstream system.
The checklist for confident AI failure is useful for defining unsupported-claim examples. It is not a complete taxonomy because operational, permission, tool, and recovery failures need their own labels.
Use incidents to maintain the taxonomy
Begin with real test failures and near misses, then add anticipated high-consequence cases. Have two reviewers code a sample independently. Disagreement reveals overlapping definitions, missing categories, or a workflow that lacks a clear expected outcome.
Track frequency only after denominators are defined. Ten retrieval errors among a thousand eligible calls mean something different from ten incidents found in an unknown support backlog. The guide to checking agent metrics reinforces this denominator discipline without supplying numbers for a new deployment.
Connect each category to detection, containment, repair, and a regression test. A policy failure may require an allowlist and reviewer gate. A stale source may require freshness metadata. A duplicate tool action may require an operation identifier and idempotent handling.
Version the taxonomy without rewriting history. Preserve retired labels and publish a mapping when categories split or merge. Reports should identify the taxonomy version used, otherwise an apparent trend may come from changed definitions rather than changed behavior.
Review the scheme after material incidents, model or tool changes, and repeated coding disputes. The goal is not an exhaustive dictionary. It is a small, usable system that makes failure visible, assignable, and testable.
Frequently Asked Questions
It is a controlled vocabulary that records a failure's stage, observable symptom, consequence, detectability, recovery path, and owner.
Yes. A case may have one primary failure and secondary contributing labels, provided the coding rules remain explicit.
Base severity on the workflow consequence and recoverability, not on how surprising or embarrassing the output appears.
It turns incidents into measurable slices, targeted regression cases, control owners, and release conditions.
For an agent-specific taxonomy, control map, and regression plan, use AI governance and agent audit. The audit can define evidence for the scoped workflow; it cannot promise that every future failure has been eliminated.