An AI workflow fails. The customer received a wrong answer. The agent took an incorrect action. The classification pipeline assigned the wrong label. Something went wrong — but what?
In traditional software, debugging follows the stack trace. The error message points to a line of code, the line of code points to the condition that failed, and the condition points to the root cause. The path from symptom to cause is usually deterministic and reproducible.
In AI workflows, there is no stack trace in the traditional sense. The failure could originate at any point in the chain: the retrieval system returned the wrong documents, the context assembly truncated critical information, the model misinterpreted the context, the action selection logic mapped the model's output to the wrong action, or the downstream system behaved unexpectedly.
Worse, the same input does not always produce the same output. A workflow can fail once and then succeed when you re-run the identical request, which makes the traditional habit of reproducing a bug before fixing it unreliable. If you cannot see what happened inside the chain the first time, you are left guessing at a failure you can no longer trigger on demand.
Without a trace, debugging AI workflows is guesswork. With a trace, it is engineering.
What a Trace Contains
A complete trace for an AI workflow records every step of the processing chain with enough detail to reconstruct what happened and why.
Input Trace
The original user input, including any preprocessing or normalisation applied. If the workflow rewrites the query (expanding abbreviations, correcting spelling, adding context), record both the original and rewritten versions.
Retrieval Trace
Which documents were retrieved, in what order, with what relevance scores. What was the search query used for retrieval (which may differ from the user's original query). Which documents were in the knowledge base but not retrieved. How the retrieved documents were filtered, re-ranked or truncated before being passed to the model.
Context Assembly Trace
The exact context window sent to the model: the system prompt, any few-shot examples, the retrieved passages in their final order, and the user's query. This is the model's input — the single most important artifact for debugging, because it determines everything the model can possibly know when generating its response.
Generation Trace
The model's raw output before any post-processing. If the model is called multiple times (chain-of-thought, self-correction, multi-step reasoning), record each call and response. Include token counts, latency and any sampling parameters (temperature, top-p).
Action Trace
For agent workflows: the action the model selected, the parameters it extracted, the API call that was made, the API response received, and the resulting state change. If the action involves multiple API calls, trace each one.
Post-Processing Trace
Any filtering, formatting or validation applied to the model's output before it reaches the user. If a quality control gate blocked or modified the response, record the original response, the gate's decision, and the modified response.
From Trace to Root Cause
The Five Whys for AI Failures
When a failure is identified, walk backward through the trace asking "why?" at each step.
The agent took the wrong action. Why? Because the model interpreted the user's request as a cancellation rather than a modification. Why? Because the retrieved policy document described the cancellation process but not the modification process. Why? Because the retrieval query was too broad and the cancellation document had a higher relevance score. Why? Because the user's phrasing ("I want to change my plan") is semantically closer to "cancel and re-subscribe" in the embedding space than to "modify subscription."
Each "why" points to a different component. The root cause determines the fix: a retrieval improvement, a prompt modification, a policy document update, or a post-processing guard. Without the trace, the same failure would most likely be logged as "the model made a mistake" and closed with a vague prompt tweak that does not touch the retrieval problem that actually caused it.
Common Root Cause Patterns
After debugging many failures, patterns emerge. Retrieval failures account for the majority of RAG system errors — the model cannot answer correctly if it does not have the right information. Context assembly failures — truncation, misordering, conflicting passages — are the second most common. Model interpretation failures, where the model has the right context but draws the wrong conclusion, are less common but harder to fix because they require prompt engineering or model changes.
Knowing the distribution of causes changes where a team spends its effort. If most failures are retrieval failures, investing weeks in prompt engineering is effort spent on the smallest slice of the problem. The trace is what tells you which slice you are actually looking at.
A Worked Example
Consider an illustrative failure. A support assistant tells a customer that their warranty has expired, and the customer complains because it has not. Without a trace, the team can only re-run the question, and this time the assistant answers correctly — the bug appears to vanish.
With a trace of the original interaction, the sequence is visible. The input trace shows the customer gave an order number. The retrieval trace shows two warranty documents were retrieved: the current policy and a superseded one from a previous product line, with the superseded document scoring marginally higher. The context assembly trace shows both were placed in the context window, the outdated one first. The generation trace shows the model faithfully summarised the first document it saw. Nothing in the chain was random; the second run simply retrieved the documents in a different order.
The root cause is not "the model hallucinated." It is that the knowledge base contains a superseded document that should have been retired, and the retrieval step has no recency preference. The fix is a knowledge-base cleanup plus a re-ranking rule, and it is verifiable. That precision is only possible because the trace preserved what the model actually saw. (This example is illustrative, used to show how a trace turns a vanishing bug into a fixable one.)
Building Trace Infrastructure
Structured Logging
Implement structured logging at every step of the workflow. Each log entry should include a trace ID (linking all entries for a single request), a timestamp, the component name, the input to the component, the output of the component, and any metadata (latency, token count, relevance scores).
Trace Storage
Store traces for a defined retention period. Production traces are large — a single RAG interaction can produce several kilobytes of trace data — but they are invaluable for debugging, evaluation and continuous improvement. Consider sampling: store complete traces for a percentage of interactions and summary traces for the rest.
Trace Analysis Tools
Raw traces are useful for debugging individual failures. Aggregated trace analysis is useful for identifying systematic issues: which retrieval queries consistently fail, which document types produce context assembly problems, which input patterns lead to model interpretation errors.
The Debugging Culture
Trace-based debugging changes the conversation around AI failures. Instead of "the model is wrong" — a statement that is true but unhelpful — the conversation becomes "the retrieval system returned an outdated document, and the model followed it faithfully." The first framing leads to vague model improvements. The second leads to a specific fix with measurable impact.
Every AI workflow failure has a root cause. Traces make that root cause findable.