DEV Community: Opswald

AI Agent Debugging Checklist: From Failed Run to Root Cause

Opswald — Mon, 01 Jun 2026 08:15:25 +0000

When an AI agent fails in production, the first instinct is usually to tweak the prompt and rerun the workflow.

That can make the incident harder to understand.

The rerun may change the model output, retrieved context, tool state, timing, permissions, or external API response. If the agent already sent an email, issued a refund, changed a ticket, or called an MCP tool, a naive rerun can also repeat a side effect.

A better workflow starts by preserving evidence from the failed run before changing anything.

This checklist is for developers debugging production AI agents that use tools, retrieval, memory, workflows, or external APIs. The goal is not to make every run deterministic. The goal is to find the first unsupported decision and turn the failure into a replayable regression.

1. Capture the run identity

Start by making sure the failed run can be found again.

Record:

Trace ID or run ID
User/session/job ID
Agent version
Deployment SHA
Model and provider
Prompt or instruction version
Tool registry version
Retrieval index version
Environment and region
Timestamp and timezone

Without this, incident review becomes archaeology. Screenshots and copied logs are not enough. The team needs a stable identifier that joins model calls, tool calls, application logs, queue jobs, and external API writes.

2. Preserve the original trigger and context

The same user request can produce different behavior depending on context.

Capture:

Original user input or job payload
System/developer instructions active for the run
Retrieved documents or chunks
Memory entries used by the agent
Account, tenant, role, and permission scope
Relevant product state before the run
Feature flags and routing decisions

A common failure pattern is a plausible model answer built from incomplete or stale context. If you only inspect the final response, the agent may look unreasonable. If you inspect the context it actually saw, the failure often becomes obvious.

3. Inspect the decision, not just the output

For agents, the important question is often not “what did the model answer?” It is “why did the agent choose this next action?”

Look for:

Selected tool or branch
Alternatives the agent could have chosen
Guardrails or policy checks that ran
Guardrails or policy checks that should have run but did not
Missing facts
Assumptions introduced by summaries or retrieved content
Handoffs between agents or workflow steps

A bad final response is visible. A bad intermediate decision can stay hidden while the final response looks fine.

4. Treat tool calls as model decisions plus API events

Tool calls are where agent debugging diverges from normal request tracing.

For each tool call, preserve:

Tool name and schema
Generated arguments
Validation result
Permission or auth scope
Raw tool response
Normalized tool response
Latency and timeout behavior
Retry count
Error payloads
External mutation or durable receipt ID

A tool call can “succeed” at the API boundary while still being the wrong action. The tool endpoint returned 200. The agent still issued the wrong refund, queried the wrong account, trusted a partial response, or retried a write.

5. Separate read-only tools from mutating tools

Do not debug all tools the same way.

Classify each tool as:

Read-only
Write
Risky write
Human approval required
External side effect

For mutating tools, capture before/after state and an idempotency key. For emails, tickets, refunds, database writes, calendar changes, and external workflow updates, capture a durable receipt.

The key replay rule: debugging should not repeat production side effects.

6. Check retrieval and memory before blaming the model

Many agent failures are context failures.

Ask:

Did retrieval return the right source?
Was the source stale?
Was the relevant fact omitted by chunking or summarization?
Did memory introduce old user preferences or obsolete state?
Did the agent cite or rely on evidence that was not actually present?
Did a later tool result contradict earlier retrieved context?

If the model was given bad or incomplete evidence, prompt tuning may hide the symptom without fixing the system.

7. Compare the failed run to a known-good run

A good comparison can save hours.

Compare:

Same user intent, different outcome
Same tool, different arguments
Same retrieval query, different chunks
Same workflow branch, different guardrail result
Same external API, different permission scope
Same prompt version, different model/provider response

The goal is to find the first divergence that matters. Timelines show order. Decision graphs show causality.

8. Make replay safe before rerunning

Replay does not have to mean regenerating every token exactly. It means preserving enough evidence to ask disciplined questions.

Before replaying, pin or stub:

User input
Prompt/instruction version
Retrieved context
Tool outputs
External API responses
Current time
Random IDs
Mutating tool behavior
Secrets and sensitive fields after redaction

Safe replay lets the team test whether a fix changes the failing decision without sending another email, creating another ticket, issuing another refund, or mutating production state.

9. Convert the incident into a regression

After root cause is found, keep the evidence.

Create a regression fixture with:

Minimal failing input
Pinned context
Expected decision or blocked action
Tool output stubs
Assertions for side effects
Notes on the root cause
Link back to the production trace

Good regression fixtures prevent the same class of failure from coming back through a future prompt change, model upgrade, retrieval change, or tool schema edit.

10. Use a short incident review template

A useful post-incident review for agents can be simple:

Incident: what happened?
Impact: who or what was affected?
First unsupported decision: where did the agent become wrong?
Evidence: what prompt/context/tool/state proved it?
Root cause category: context, tool, permission, memory, orchestration, model, guardrail, or side effect?
Fix: what changed?
Regression: what replay or test now catches this?

The “first unsupported decision” line is the important part. It keeps the review from collapsing into vague statements like “the model hallucinated” or “the prompt was bad.”

Quick checklist

Before changing prompts or code, capture:

[ ] Run ID / trace ID
[ ] Agent, model, prompt, tool, and deployment versions
[ ] Original user input or job payload
[ ] Retrieved context and memory entries
[ ] Selected tools and skipped alternatives
[ ] Tool schemas, arguments, outputs, retries, and errors
[ ] Permission and tenant/account scope
[ ] Side effects and durable receipt IDs
[ ] Before/after state for writes
[ ] Replay plan with stubs for external mutations
[ ] Regression fixture and assertion

Closing thought

Production agent debugging is less about watching a pretty trace and more about preserving the evidence behind a decision.

If you can answer what the agent saw, what it chose, what changed, and how to replay it safely, you can debug the failure. If you cannot, you are guessing.

Useful related resources:

AI agent debugging guide: https://www.opswald.com/ai-agent-debugging/
AI agent replay: https://www.opswald.com/ai-agent-replay/
Tool-calling failure debugging: https://www.opswald.com/debug-tool-calling-failures/
Agent debugging playbook: https://github.com/opswald/agent-debugging-playbook

Why Logs Aren't Enough to Debug AI Agents

Opswald — Wed, 20 May 2026 22:06:53 +0000

Most teams start debugging AI agents the same way they debug normal software: logs.

That works until the failure is not a single exception.

AI agents fail across decisions:

the model picked the wrong tool
the tool returned ambiguous data
the agent ignored relevant context
a retry changed the path
the final answer looked correct, but came from the wrong chain of decisions

A log line can tell you what happened.
It rarely tells you why the agent chose that path.

That difference matters a lot once agents start doing real work.

The problem with agent logs

Traditional logs are linear.

A request comes in. Your system calls a service. A response comes back. Something succeeds or fails.

For normal backend systems, that is often enough. If a database query times out, a log line can point you to the query. If an API returns a 500, the log can tell you which call failed.

AI agents are different.

An agent run is not just a sequence of function calls. It is a decision process:

read the task
inspect context
choose a next action
call a tool
interpret the result
update the plan
decide what to do next

The failure may not be in the tool call itself. It may be in the decision that led to the tool call.

That is where logs start to break down.

Example: a tool calling failure

Imagine an agent that should look up a customer invoice.

The user says:

Can you check whether ACME has paid invoice INV-1042?

The agent calls the CRM search tool and gets no result.

The logs show something like this:

crm.search_customer({ "name": "ACME" })
→ []

final_answer: "I couldn't find an invoice for ACME."

From the logs, this looks straightforward. The CRM returned no result, so the agent answered that no invoice was found.

But the real problem might be somewhere else:

the agent searched by customer name instead of invoice ID
the CRM tool expected an account ID, not a name
the invoice number was available in context but ignored
a previous tool returned partial data and the agent misread it
a retry changed the search parameter
the agent failed to call the billing tool after the CRM returned empty

The failure is not simply “CRM returned empty.”

The failure is: why did the agent decide that CRM search by customer name was the right next action?

A log line usually cannot answer that.

What engineers need to know

When an agent fails, the useful debugging questions are different from normal software debugging.

You need to know:

What did the agent know at this step?
What options did it have?
Which tool did it choose?
Why did it choose that tool?
What did the tool return?
How did the agent interpret the result?
Where did the first bad decision happen?

Logs usually capture pieces of this, but not the decision context around it.

That is why teams end up doing log archaeology: reading prompts, tool inputs, tool outputs, retries, traces, and final answers separately, trying to reconstruct the run after the fact.

More logs are not the same as better debugging

A common reaction is to add more logging.

Log the prompt. Log the tool input. Log the tool output. Log the final answer. Log token counts. Log latency. Log cost.

All of that is useful.

But it still leaves a gap: logs are observations, not explanations.

If an agent calls the wrong tool, the log can show the wrong tool call. It does not automatically show why the agent thought that was correct.

If an agent ignores context, the log can show the prompt contained the context. It does not show which part of the context the agent used or skipped.

If an agent succeeds after a retry, the log can show the retry. It does not always show how the retry changed the path.

For agents, the key unit of debugging is not just the event. It is the decision.

What better agent debugging looks like

For production agents, useful debugging needs more than flat logs.

It needs a replayable structure of the run:

the goal the agent received
the context available at each step
every decision point
every tool call and result
retries and alternate paths
the final answer
the first point where behavior diverged from what was expected

This is closer to replaying a session than reading a log file.

A good agent debugger should let you inspect a failed run step by step and answer:

At this exact moment, why did the agent do this?

That is the question that matters.

Decision graphs instead of timelines

Many observability tools show agent activity as a timeline.

Timelines are helpful, but agents are not always best understood as timelines. They are better understood as decision graphs.

A timeline tells you:

Step 1 → Step 2 → Step 3 → Step 4

A decision graph tells you:

The agent had these options.
It chose this one.
That choice led to this tool call.
The result changed the next decision.
This is where the run went wrong.

That structure is much more useful when you are trying to debug behavior instead of infrastructure.

Logs are still necessary

None of this means logs are bad.

You still need logs for:

errors
latency
cost
request volume
tool availability
API failures
security audits

Logs are part of the debugging picture.

They are just not the whole picture.

For AI agents, logs tell you what happened. Replay and decision context tell you why it happened.

A practical checklist

If you are building agents, ask whether you can answer these questions for a failed run:

Can you replay the exact run?
Can you see each tool input and output?
Can you inspect what context was available before each decision?
Can you identify the first bad decision, not just the final bad answer?
Can you compare a failed run to a successful one?
Can you explain why the agent chose a specific tool or path?

If the answer is no, more log lines probably will not solve the problem.

You need decision-level debugging.

Closing thought

AI agents introduce a new debugging problem.

The hard part is not always knowing whether a tool failed. The hard part is understanding why the agent chose that tool, how it interpreted the result, and where the reasoning path first went wrong.

That requires moving beyond flat logs toward replayable traces and decision graphs.

If you are working on production agents and have felt this pain, Opswald is building around exactly that problem: making agent runs easier to replay, inspect, and explain.

https://www.opswald.com/