When you need to debug AI agent behavior, starting by rewriting the prompt is usually a poor first move. Debugging an agent is diagnosis: find out what the agent saw, what it decided, what it did, and where that chain first went wrong — then fix that step and prove the fix with a test.
This article gives you a repeatable method for that, built on the agent loop itself rather than one vendor’s dashboard.
What it means to debug AI agent behavior
An agent run is a loop: perceive, decide, act, observe. The agent reads the request and the state of the world, decides what to do, calls a tool or produces text, then observes the result and decides again. A failure can live in any one of those steps.
There are four places to look. The model decision can be wrong: the agent chooses the wrong tool or reasons from a false premise. The tool or environment can be wrong: a search returns stale results, or an API returns an error the agent does not understand. The state or context can be wrong: a long run drops an earlier fact. And the instructions can be wrong: the goal is ambiguous, or the success criteria were never written down.
Each location points to a different kind of intervention, to be selected after inspecting the failure. A wrong tool choice may call for tightening the tool definitions. A misleading tool result may call for validating the result before the agent acts on it. Lost context may call for managing state rather than adding prompt text. Ambiguous instructions may call for writing down what success looks like. None of these is guaranteed to be the fix — the trace decides which one applies.
The stakes are not abstract. A Sierra survey of 411 enterprise agent pilots run in Q4 2025 found that 87% failed to reach a budgeted line item within nine months — most often because success criteria were under-specified (64% of failed pilots), no eval set was built before launch (61%), or tool boundaries were brittle on production-shaped inputs (52%).
Make the agent observable before you debug anything

Without a record of what the agent saw, decided, and did, debugging is guesswork. The prerequisite is a trace: a complete, ordered record of a single run. At minimum it must capture the inputs, the model outputs, every tool call and its result, token and context usage, and latency — plus the reasoning chain connecting them. With a traditional API you know what the system did because it executed your code; with an agent you often do not know why it did something, and the reasoning chain is often the clearest evidence of why it did so — alongside environment outcomes and grader results.
Several tools capture traces well. LangSmith, built by the LangChain team, captures the full trace tree and supports trajectory evaluation — scoring the sequence of tool calls and decisions rather than just the end state. Its free tier covers 5,000 traces a month, Plus is $39 per seat per month. Langfuse is open source and self-hostable, with hierarchical traces plus datasets and LLM-as-judge evaluators. Arize Phoenix is also open source and focuses on the evaluation layer, and Opik adds pass/fail test suites with more than 30 built-in metrics.
You do not need a platform to start: structured logging of each step — inputs, model outputs, tool name, arguments, result, token usage, and latency — captures the minimum trace in any codebase.
Traces should follow a shared shape. The OpenTelemetry GenAI semantic conventions define standard span names for agent operations — invoke_agent, chat, execute_tool, and plan — so a trace from one SDK can be read by Langfuse, Phoenix, MLflow, or a generic OpenTelemetry backend instead of locking you into one vendor’s format:
{
"trace_id": "trace_9f2c1a",
"spans": [
{"name": "invoke_agent", "input": "Book a flight to Berlin on 20 November"},
{"name": "chat", "output": "I will call book_flight."},
{"name": "execute_tool", "tool": "book_flight",
"arguments": {"date": "20 November 2026"},
"result": "error: invalid date format"},
{"name": "chat", "output": "Your flight has been booked."}
]
}That short trace already contains a debugging story, and we will come back to it.
Reproduce the failure reliably
A failure you cannot reproduce is hard to verify a fix for. Before changing anything, turn the bad run into a repeatable test case. Freeze everything that varies: the exact inputs, the tool responses, and the model version. That controls external variability, but model outputs can still vary between runs, so a reproduction is a starting point for testing, not a guarantee. Tool responses are the part teams forget — if a search tool returns different results tomorrow, the same prompt can take a different path. Where a tool is non-deterministic, record its actual response from the failing run and replay it during debugging.
Then build a minimal reproduction: strip away unrelated steps until the failure still occurs. A twenty-step run that fails at step fourteen becomes a five-step case that fails at step three — faster to run, easier to read, harder to misdiagnose. Save that minimal case as a regression case: the first entry in the eval set you will build later.
Anthropic’s own writing on agent evals draws the underlying distinction: an agent may claim success while the outcome is missing. The walkthrough that runs through the rest of this article is an illustrative extension of that distinction, not a record of a real run. In the illustration, a user asks an agent to book a flight to Berlin on 20 November, and the booking tool requires ISO dates (YYYY-MM-DD). The agent’s final message says “Your flight has been booked.” But the bookings database has no reservation. The agent claimed success; the outcome is missing. Freeze the request, the model version, and the tool responses, and re-run the case until the false success repeats. Now you have a regression case with a clear success criterion: a reservation exists in the bookings database.
Read a trace like a debugger

Open the trace for the reproduced failure and walk it from the top. You are looking for the first divergence: the first step where the agent’s behavior departs from what was intended. Later steps are usually consequences, not causes, and fixing a consequence leaves the defect in place.
In the flight-booking trace, the divergence is at the third span. The agent calls book_flight with the date as “20 November 2026” and the tool returns an error: invalid date format. The fourth span is the failure: instead of reporting the error or retrying with a corrected date, the agent tells the user the flight has been booked. The first divergence is the tool error; the second is the agent treating a failed tool call as a success.
At each step, check what the model actually saw. Was the context truncated so an earlier fact was missing? Was a tool result misleading — an error object the agent read as a success, or a search result that looked authoritative but was stale? Were the instructions ambiguous about what to do when a tool fails? These are three different defects with three different fixes, and reading the trace — together with environment checks — is how you tell which one you have: a reasoning error means the model had the right information and decided wrongly; a bad observation means it was given wrong information; a bad tool result means the environment failed the model.
Common failure patterns and their fixes
Most agent failures fall into a small set of patterns. Each comes with its fix and the check that proves it worked.
Tool misuse. The agent calls the wrong tool, passes wrong arguments, or ignores a tool’s result — often the schema-on-paper tool, whose docstring promises an order object while the tool returns an error object it never mentions. Strict tool use (strict: true) addresses one part of it: it guarantees the arguments follow the tool’s schema. It does not choose the right tool, and it does not make the agent handle results correctly — those need separate checks: review the tool descriptions against the task, and validate every tool result before acting on it. Check: re-run the reproduction case and assert the arguments and the error handling.
Loops and repeated failures. The agent retries the same failing action, or two steps undo each other forever. Fix: progress detection plus a step budget — stop with a clear failure message when no step changes the state within a fixed number of steps. Check: the run terminates within the budget and reports the failure instead of spinning.
Context loss. Long runs drop earlier facts or work from stale state. Fix: manage state explicitly — summarize completed work into a compact state record and checkpoint important facts. Check: the facts the task depends on are still in context at the step that needs them.
Ambiguous instructions and underspecified goals. The agent has no reliable way to succeed when success was never defined — the most-cited cause of pilot failure in the Sierra survey. Fix: write the success criteria down before the agent runs: what state must exist at the end, and what must never happen. Check: the eval pass rate improves, and two reviewers agree on what counts as a pass.
Hallucinated tool outputs or fabricated observations. The agent claims a result it never got, like the flight-booking agent announcing a booking that does not exist. Fix: check outcomes in the environment, not the transcript — verify the reservation in the database, the file on disk, or the ticket in the queue. Check: the outcome matches the agent’s claim on every case.
Two related mechanisms each reduce a different class of failure. Structured outputs — OpenAI’s response_format with a JSON schema, or Anthropic’s output_config.format — constrain the model’s response text to a schema, so malformed replies largely disappear; OpenAI recommends them whenever possible, and plain JSON mode only guarantees syntactically valid JSON. Strict tool use (strict: true on the tool definition) is the separate mechanism that constrains the arguments the model passes to your functions. Neither guarantees correct values: a value can still be wrong, and refusals and truncation can break the schema — so validate values against your business rules after parsing.
Verify the fix with evals, not vibes
A fix is not verified because the failing case now passes once. It is verified because a defined set of cases passes, including the ones that used to pass. That set is an eval. Anthropic’s vocabulary: a task is a single test with defined inputs and success criteria; a trial is one attempt at a task; a grader scores an aspect of performance; a transcript is the complete record of a trial; the outcome is the final state of the environment. Before claiming a fix holds, run each case several times and compare success and failure rates on the failing cases and the cases that used to pass — a single passing run does not establish that an intermittent failure is repaired.
Build the eval set from your own failures. Anthropic’s advice: start with 20 to 50 tasks pulled from real failures, including the regression cases you saved during debugging. Grade the outcome, not the path — agents reach the same result by different routes, and pinning a fixed sequence of tool calls makes tests brittle. In the walkthrough, the grader checks the bookings database, not the transcript. A case can be written down as data:
{
"task": "book_flight_berlin_nov20",
"input": "Book a flight to Berlin on 20 November 2026",
"success_criteria": [
"a reservation exists in the bookings database",
"the confirmation matches the requested date"
],
"grader": "outcome_check"
}Use the right tooling for the job, in three layers. DeepEval is pytest-native: test cases with metrics such as answer relevancy, faithfulness, and hallucination, run in CI so a metric below threshold fails the build. Braintrust treats evals as a CI gate, with scorers, datasets, and experiment diffs. LangSmith owns the production trajectory layer, scoring full runs. RAGAS covers retrieval, scoring faithfulness, answer relevance, context precision, and context recall.
Measure the change on the same case set: compare task success, tool-call accuracy, steps to completion, and cost before and after the fix. In production, sample traces by failure class for regular review — the sample is where the next eval cases come from.
One rule governs the whole layer: never let the agent grade its own work. Anthropic’s harness experiments found that agents asked to evaluate their own work tend to confidently praise it even when it is mediocre — they spot real problems, then wave them off as unimportant and approve anyway. Separate generation from evaluation: a separate evaluator agent, deterministic graders, or human review of sampled transcripts.
Prevent regressions with monitoring and guardrails
Debugging one failure is not the same as preventing the next one. Production needs the same trace you used in development, plus a way to notice when a known failure signature reappears. LangSmith’s Engine, for example, monitors traces, groups failures into issues, and proposes fixes along with evals. Even without a platform, you can alert on signatures you already know: tool-error rates above a threshold, runs that hit the step budget, or outcomes that do not match the agent’s claims.
Guardrails sit inside the loop and catch failures before they reach the user. Output validation rejects responses that do not match the expected shape. Tool-call allowlists restrict which tools the agent can reach at all — they are not approval. Approval is a separate gate: a human-in-the-loop checkpoint pauses the agent before irreversible actions, so a person authorizes the step. Automated screening is a third mechanism: one documented pattern is a second model instance screening queries while the first handles them. In the illustrative walkthrough, a guardrail that verified the reservation before the confirmation message was sent would have turned a silent false success into a visible, recoverable error. Think of quality as layers rather than a single check: evals, production monitoring, and human review of sampled transcripts each catch failures the others miss, so they work best together.
When debugging is not enough
Some failures are not bugs. They are signs the design may be wrong, and further debugging alone may not fix them. Watch for the signals: the task is persistently ambiguous; the task is beyond the model’s capability; the tools are unreliable; or each fix has created a new failure somewhere else — the reactive loop Anthropic describes, where fixing one failure creates others.
Treat that as a reason to reassess the design, and compare the options on measured outcomes: narrow the agent’s scope until the task is well-defined; replace a fragile autonomous step with a deterministic one, where the model decides and code executes; change the instructions where they are the problem; or improve the tools or the data — a tool that returns structured errors beats a prompt that begs the model to handle unstructured ones.
The common mistake at this stage is endlessly re-prompting a fundamentally unreliable step. If you have debugged the same behavior repeatedly and the root cause is still “the model sometimes decides wrongly,” reassess the design rather than assuming another prompt change will help — and let measured outcomes decide between the options above.
Debugging an agent is a discipline, not a talent: make the run observable, reproduce the failure, find the first divergence, fix that step, and prove it with an eval. Each failure then leaves behind a trace you can read, a regression case you can re-run, and a guardrail that makes a repeat less likely, with monitoring and evals watching for it.












