A support agent at a mid-market SaaS company kept returning refund amounts that were off by a few dollars. The team spent eight days rewriting the system prompt: rules about rounding, rules about currency, rules about partial-month edge cases. The numbers stayed wrong. The actual fault was a pricing tool that returned list price instead of the customer's contracted price. No amount of prompt wording fixes a tool that hands the model the wrong number to start with.
When an agent misbehaves, the prompt is the first thing almost everyone edits, because it is the one component you can change without a deploy. That reflex is the most expensive habit in production agent work. It burns engineering days on the wrong layer, and worse, a prompt patch often masks the real bug well enough to pass a demo, only for it to resurface under real traffic. Google Cloud's 2026 agent trends report frames the shift bluntly: teams are moving from "make the model smarter" to "make the system observable," because the failures that matter live in the plumbing, not the prose.
This is a root-cause guide. The goal is to give your on-call engineer a way to locate which layer actually broke before anyone touches a single word of the prompt.
The Prompt Is Almost Never the Real Problem
Start with an uncomfortable number. WRITER's enterprise AI report found 79% of organizations running AI initiatives hit serious challenges getting them to stick, despite heavy investment. The pattern underneath that statistic is rarely "the model could not reason." It is that nobody could explain why a specific failure happened, so they patched the most visible surface and moved on.
Prompt-first debugging fails for a structural reason. The prompt sits at the very end of the pipeline. By the time the model reads it, the tools have already returned their data, retrieval has already chosen its documents, and the router has already decided which step runs. If any of those upstream stages handed the model garbage, a better prompt only changes how confidently the model presents the wrong answer.
There is a tell for this. If you can reproduce the failure by feeding the model the same inputs in a playground and it answers correctly there, your prompt is fine. The bug is upstream. That five-minute test saves more debugging time than any prompt iteration.
The honest version of agent debugging treats the prompt as the last suspect, not the first.
Read the Trace Before You Touch Anything
Root-cause analysis on agents is error analysis on traces. Hamel Husain's work on evals makes the case that error analysis, not metric-chasing, is where the actual signal lives, and that teams should spend the majority of development time reading what their system actually did. For agents specifically, that means reading the full execution trace: every tool call, every argument, every returned payload, every retrieval result, every routing decision.
Braintrust's guide to hidden failure patterns describes the productive move as clustering production traffic by where the trace diverged from the expected path, rather than by final output quality. Two failures with identical wrong answers can have completely different causes - one a stale retrieval, one a bad tool argument - and they need different fixes. Grouping by symptom hides that. Grouping by failure location reveals it.
When you read a trace, you are answering five questions in order:
- Did the agent call the right tools, in the right order?
- Did each tool return correct, fresh data?
- Was the retrieved context relevant and current?
- Did the agent have permission to take the action it tried?
- Given correct tools, data, and context, did the model still reason wrong?
Notice that the prompt does not get suspected until question five. Everything before it is plumbing.
The Five Layers Where Agents Actually Break
Most production agent failures resolve into one of these layers. The value of naming them is that each maps to a different team, a different fix, and a different test.
| Layer | What it looks like in the trace | Concrete example | The patch |
|---|---|---|---|
| Prompt | Tools and data correct, model still misreads the instruction | Agent summarizes when it was asked to classify | Tighten instruction, add few-shot example, restructure the task |
| Tool contract | Tool returns wrong, malformed, or stale data, or is called with wrong arguments | Pricing tool returns list price, not contract price | Fix the function, validate its schema, correct the argument mapping |
| Retrieval | Search returns irrelevant or outdated documents | RAG pulls last quarter's policy doc | Re-index, fix chunking, add recency filters, tune the query |
| Routing | Agent picks the wrong branch, tool, or sub-agent | Billing question routed to the returns agent | Fix the router logic or classifier, add a confidence threshold |
| Workflow | Steps run out of order, in parallel when they should be sequential, or with ambiguous handoffs | Refund issued before approval check completes | Make the orchestration deterministic, enforce ordering |
Three more sit just outside this core set but cause real outages:
- Bad source data. The agent and its tools worked perfectly; the underlying record was wrong. This is a data-quality bug wearing an AI costume. No agent change fixes it.
- Permissions. The agent tried to act and lacked access, or worse, had too much access. Simon Willison's "lethal trifecta" - private data, untrusted input, and an exfiltration path together - is the permission failure that turns into a security incident rather than a wrong answer.
- Model limitation. Sometimes the task genuinely exceeds what the model can do reliably, and the answer is a different model, a decomposition, or a human step - not another prompt revision.
- Missing escalation. The agent should have stopped and asked a human, and there was no path for it to do so. A missing escalation route is a design failure, not an edge case.
The discipline here is matching the fix to the layer. IBM Research's AgentFixer work for ICSE 2026 formalizes exactly this idea: detection alone is not enough, because the same observed failure can demand a tool fix, a routing fix, or a prompt fix, and recommending the wrong category of repair just resets the clock.
A Decision Tree for Locating the Fault
Hand this to whoever is on call. The point is to fail the cheap-to-blame prompt last, not first.
Step 1 - Did the agent call the right tools in the right order? If no, the fault is routing (wrong tool or branch chosen) or workflow (right tools, wrong sequence). Stop here. Do not edit the prompt yet, even though prompt wording can influence routing - confirm whether the router logic or classifier is the real culprit first.
Step 2 - Did each tool return correct data? If a tool returned wrong, stale, or malformed output, the fault is the tool contract or bad source data. Check whether the function is broken or whether the underlying record was wrong before it ever reached the agent.
Step 3 - Was the retrieved context fresh and relevant? If the agent pulled outdated or off-topic documents, the fault is retrieval. This is where the DEV Community breakdown of production agent failures puts a large share of real incidents in 2026: agents that read the right document from six months ago and reasoned perfectly off stale ground truth.
Step 4 - Did the agent have permission to act? If the action was blocked or over-permitted, the fault is permissions. Treat over-permission as urgently as under-permission.
Step 5 - With correct tools, data, and context, did the model still reason wrong? Now, and only now, suspect the prompt. If the prompt is clean and the model still cannot do the task, you have hit a model limitation, and the fix is decomposition, a stronger model, or a human step.
Step 6 - Should a human have been in the loop here at all? If the agent made a call it should never make alone, the fault is a missing escalation path, regardless of whether its answer happened to be right this time.
Walk the tree top to bottom. Most failures resolve by step three.
Patches That Match the Layer
A patch is correct when it changes the layer that broke and nothing else. Some common mismatches worth naming, because every team I have seen makes at least one of them:
- Patching a tool-contract bug with prompt instructions. Adding "remember to use the contracted price" to the system prompt when the tool returns list price. It works in testing because the model gets lucky, then fails when the data shape shifts. Fix the tool.
- Patching a routing bug with a bigger model. A more capable model can mask a weak router for a while by guessing better, but you are now paying more per call to hide a deterministic bug. Fix the router.
- Patching a workflow ordering bug with retries. If a refund can fire before approval completes, retrying the failure does not make the ordering safe. Make the steps deterministic. As Chip Huyen catalogs in her writing on AI engineering pitfalls, reaching for an agentic abstraction when a fixed code path would do is one of the most common and costly mistakes - and it shows up most clearly in workflow ordering.
- Patching a data-quality bug anywhere in the agent. If the source record is wrong, every layer downstream is innocent. Fix the data and add validation at ingestion.
The cheapest fixes - editing the prompt, swapping the model - are the ones most often applied to the wrong layer, precisely because they are cheap to try. Cheap to try is not the same as correct.
There is a compounding benefit to getting this right. Every correctly-diagnosed failure becomes a test case at the layer where it lives: a tool-contract assertion, a retrieval freshness check, a routing eval. Over a few months your test suite stops being generic and starts encoding your actual production failure history. That is the difference between an agent that gets more fragile as it grows and one that gets harder to break.
How OpenNash Can Help
If your team is on its third prompt rewrite for the same recurring failure, the problem is usually not the prompt - it is that nobody can see which layer broke. That is a diagnosis and instrumentation gap, and it is fixable.
OpenNash builds production AI agents with this root-cause structure designed in from the start. In practice that means:
- Audit: map where your current agent actually fails, by layer, using its real traces rather than its demo behavior.
- Design: define tool contracts, retrieval freshness rules, deterministic workflow ordering, and explicit human escalation points before anything ships.
- Build and deploy: instrument traces so on-call engineers can run the decision tree above in minutes, with the agent handed off as something your team fully owns.
Custom is not always the right call. If your need is a standard, well-supported workflow, a platform may serve you faster and cheaper, and a good partner will tell you so. Custom earns its keep when the workflow is specific to your operation, when auditability and clean human handoff are non-negotiable, and when you want to own the system rather than rent it.
Book a call to map this decision tree to your own agent's failure history and find out which layer is actually costing you.
The next time your agent does something wrong, resist the text box. Open the trace, walk the tree, and fix the layer that broke. The prompt will still be there if it turns out to be the culprit - and most of the time, it will not be.