Notes · AI agents · · 5 min read
A green trace is not a correct outcome
A root-cause checklist for AI agents in production. Four questions to ask every failed run, what to log so you can answer them, and the failure patterns that hide behind green spans.
In short
Most production failures in AI agents don't throw errors. Latency is fine, every span is green, and the customer still gets the wrong answer. Observability tells you what ran. It doesn't tell you why the answer was wrong.
This is the checklist I use when I read a failed run. It came out of work on Forensi, a project I am building to investigate production agent failures. It has four questions for every failed run, the logging that makes them answerable, and five patterns to check for. You don't need any tool to use it, only your traces.
Who it's for: engineers running retrieval-augmented or tool-using agents in production who are tired of reading long traces by hand.
Done when: for one failed run, you can name the cause in one line, point to the trace evidence for it, and say what to fix first.
Before you start: log enough to answer
You can't find a root cause in data you didn't keep. For each run, make sure your traces store:
| Layer | What to keep |
|---|---|
| Retrieval | The query, filters applied, and every candidate with id, score, rank, source type and updated_at |
| Context | The exact chunks sent to the model, in order, with token counts |
| Tools | Arguments and the raw response body, not only the span status |
| Answer | Citations mapped to chunk ids |
Check: pick one recent run and try to rebuild the exact context the model saw. If you can't, fix the logging before anything else.
Step 1. What was retrieved?
Look at the full candidate list with scores, not only what was passed on. The right document is often there, ranked just below the cut-off.
Check: if the chunk that holds the answer sits just past top_k, it was found and then thrown away. The fix is in ranking, not in the model.
Step 2. What did the model actually see?
Compare the candidates with the final context after top_k, filters, reranking and truncation. What survived is the only thing the model could reason about.
Check: every fact in the answer should appear somewhere in that final context. If a fact appears nowhere, you have a grounding failure. The answer sounds right but nothing the agent retrieved supports it.
Step 3. Which source did it trust?
For each claim in the answer, find the chunk behind it and note its type, date and owner. Three patterns show up again and again:
- Stale source wins. An older version of a policy ranks higher than the current one, and the citation points to the older one.
- Sources conflict, no caveat. Two current sources give different values for the same field. The answer mentions only one and never says there was a conflict.
- Authority inversion. An informal source, such as a chat thread or an old ticket, outranks the official document because it sounds more like the question.
Check: two chunks in context cover the same topic with different dates or values, or the cited chunk is informal while an official one is also in context. Then the problem is precedence. You fix it with metadata and rules, not with a better prompt.
Step 4. Did any tool fail quietly?
Read tool inputs and outputs, not only span status. A wrapper can catch a timeout and return {"error":"timeout"} with status OK. A call can return 200 with page 1 of 4 of the results. Or the tool says refund_eligible: false and the agent acts as if it were true.
Check: the span status is OK but the body holds an error, an empty list, null, a default value or partial data. Or the answer states facts that appear in no tool output.
Step 5. Write the cause in one line
Name the cause with a label you can count across runs, such as grounding, misread tool result, source conflict, stale source or incomplete tool data. Then write the causal chain as evidence: retrieved, what reached context, what was cited, what was answered.
Check: someone who wasn't there can read your line and the chain, open the trace and reach the same conclusion. Once you have labelled twenty or so failed runs, group them by label and fix the biggest group first.
What to fix, by pattern
| Pattern | First fix |
|---|---|
| Found but dropped | Retrieve wider, then rerank. Boost specific sources over general ones |
| Stale source | Store version and effective date as metadata. De-index superseded docs |
| Conflict, no caveat | Define precedence (specific over general, newer over older) and make the agent say which rule it applied |
| Authority inversion | Tag a source of truth per topic. For policy and pricing, require an official citation |
| Quiet tool failure | Fail the span when the payload signals an error. Validate tool outputs against a schema |
Honest limits
- This checklist reads one run at a time. It finds causes; it doesn't measure how often they happen until you label enough runs.
- It depends on your logging. If you don't keep candidates, final context and raw tool bodies, most of these checks can't be done.
- The examples here are illustrative patterns, not real customer cases.
- Some failures are plain model reasoning errors with correct inputs. This checklist helps you rule out the input-side causes first, which are often the easiest ones to fix.
Sources
- Forensi: the project this checklist comes from. The public site describes checks for grounding, tool-output interpretation, cross-source conflicts, freshness and authority, and calls that succeed technically but fail semantically. Forensi is a landing page and a demo.
- Forensi field guide, 10 ways RAG agents fail. It covers the four questions and the logging table above.