Debug an LLM agent: find the first bad step in its trace
An agent run can end with Done and still be wrong. By the end of this guide you can:
- Read an agent trace as a list of spans and find the first bad one.
- Tell a tool failure from an ungrounded argument and from an unverified Done.
- Keep a failed run as a pytest test.
You need Python 3 and pytest. No API key and no network.
Before you start
You should know Python functions, dicts and the json module, and how a tool-calling loop works. If not, open these chapters first. Each link opens a breakdown for that topic with a revision guide and side chats. Sign in to open it.
- How an LLM tool-calling loop works. The model asks for a tool and your app runs it.
- Traces and spans for one agent run. The worked example reads a trace as a list of spans.
- Regression tests with pytest. The last step keeps a failed run as a test.
The run we will debug
A support agent gets this request: Refund order 1042, it arrived broken. It looks up the order, issues a refund and answers Done. Every span in the trace is marked ok. The refund amount was a guess.
This trace is a recorded run written for this guide. It is not output from a live model, and it has no customer data.
| Span | What happened |
|---|---|
| 0 | The model asks for lookup_order(order_id=1042). |
| 1 | lookup_order returns a web page that says Access denied, HTTP 403. |
| 2 | The model asks for issue_refund(order_id=1042, amount=49.0). |
| 3 | issue_refund returns a refund id and the status ok. |
| 4 | The model answers: Done. Refunded 49.00 for order 1042. |
A trace is one end-to-end run made of spans. In the OpenAI Agents SDK, each model call and each function tool call gets its own span by default. The OpenTelemetry tool-execution conventions record the tool name and, if the call failed, an error type. They have Development status, so names can change. In a tool-calling loop the model proposes a call and your application runs it and returns the result, as the Microsoft Foundry docs describe.
Three kinds of bad step
Anthropic's guide to building agents says an agent needs “ground truth” from the environment at each step, such as tool call results. The checker below tests two things: that a tool result is usable, and that later steps rest on one.
- Tool or environment failure
tool_result_invalid - The tool ran, but its output is not the JSON object the tool should return.
- Ungrounded argument
ungrounded_argument - A value in a tool call is in neither the task nor any earlier tool result.
- Unverified done
unverified_done - The final answer states a number that neither the task nor any tool result contains.
The first flag is the likely root cause. Later flags are often its consequences. These rules were written for this guide. They are not a standard.
Worked example
The refund run above ended with Done, but the amount was a guess. Find the first bad step, label every flag, fix the cause and keep the run as a test.
Look only at the final answer
Every span is marked ok and the answer says Done. Nothing looks wrong. That is the trap: ok means the call returned, not that the result was good.
Check what each step received
Span 1 should return a JSON order. It returned an error page. The checker flags (1, tool_result_invalid). The page says HTTP 403, which means the server refused the request, yet the wrapper marked the call ok. First bad step: span 1. Kind: tool or environment failure.
Trace each argument to its source
Span 2 asks to refund 49.0. That number is not in the task and not in the error page. The checker flags (2, ungrounded_argument). With no order data, the model had nothing to take the amount from. This flag is a consequence of span 1, not a second root cause.
Check the Done claim against the evidence
The final answer says 49.00. No tool result contains it. The checker flags (4, unverified_done). This is another consequence of span 1.
Fix the cause, not the symptom
Change lookup_order so a status other than 200, or a body that is not an order, comes back with ok set to False. Then your loop can stop or retry instead of handing a web page to the model. Also read the refund amount from the order record, never from the model's arguments.
Keep the run as a test
Replay each recorded run through the checker with pytest.mark.parametrize and assert the first flag. Add a test on the wrapper too, because the bug lived there. The wrapper tests fail before the fix (2 failed, 4 passed) and pass after it (6 passed).
Run it yourself
Put these files in one folder. Every command here was run on 8 November 2026 with Python 3.15.2 and 3.12.16 and pytest 9.2.0. The output was the same on both Python versions. Pytest header lines are left out, and timings will differ.
The commands use uv. Without uv, install pytest in a virtual environment and run python show.py and python -m pytest -v --tb=no -rN instead.
runs.py holds three recorded runs: a good run, the blocked run and a run where the model guessed the amount. The wrapper marked every span ok.
import json
TASK = "Refund order 1042, it arrived broken."
ACCESS_DENIED = "<html><h1>Access denied</h1><p>HTTP 403</p></html>"
REFUND = '{"refund_id": 9001, "status": "ok"}'
def order(total):
return json.dumps({"order_id": 1042, "status": "delivered", "total": total})
def llm(name, output="", **args):
return {"kind": "llm", "name": name, "input": args, "output": output, "ok": True}
def tool(name, output, **args):
# ok is what the tool wrapper reported, not what we found
return {"kind": "tool", "name": name, "input": args, "output": output, "ok": True}
def run(order_body, amount):
return [
llm("lookup_order", order_id=1042),
tool("lookup_order", order_body, order_id=1042),
llm("issue_refund", order_id=1042, amount=amount),
tool("issue_refund", REFUND, order_id=1042, amount=amount),
llm("final", f"Done. Refunded {amount:.2f} for order 1042."),
]
GOOD_RUN = run(order(49.0), 49.0)
BLOCKED_RUN = run(ACCESS_DENIED, 49.0)
GUESSED_RUN = run(order(52.5), 49.0)trace_check.py is the checker. bad_steps returns every flagged span as (index, label), in trace order. A tool output that json.loads cannot read as an object is flagged.
import json
import re
def numbers(text):
return {float(n) for n in re.findall(r"\d+(?:\.\d+)?", text)}
def grounded(value, source):
if isinstance(value, (int, float)):
return float(value) in numbers(source)
return str(value).lower() in source.lower()
def bad_steps(trace, task):
"""Return every flagged span as (index, label), in trace order."""
flags, seen = [], task
for i, span in enumerate(trace):
if span["kind"] == "tool":
try:
is_object = isinstance(json.loads(span["output"]), dict)
except json.JSONDecodeError:
is_object = False
if not is_object:
flags.append((i, "tool_result_invalid"))
seen += " " + span["output"]
elif span["name"] == "final":
if not numbers(span["output"]) <= numbers(seen):
flags.append((i, "unverified_done"))
elif not all(grounded(v, seen) for v in span["input"].values()):
flags.append((i, "ungrounded_argument"))
return flagsshow.py runs the checker on the blocked run.
from runs import BLOCKED_RUN, TASK
from trace_check import bad_steps
print("every span ok:", all(span["ok"] for span in BLOCKED_RUN))
print("final answer:", BLOCKED_RUN[-1]["output"])
for i, label in bad_steps(BLOCKED_RUN, TASK):
print(i, label)uv run --no-project --with pytest python show.pyevery span ok: True
final answer: Done. Refunded 49.00 for order 1042.
1 tool_result_invalid
2 ungrounded_argument
4 unverified_doneBefore the fix, tools.py passes every response through as ok. test_runs.py replays the recorded runs, then tests the wrapper. The two wrapper tests fail.
def lookup_order(status, body):
return {"ok": True, "output": body}import pytest
from runs import ACCESS_DENIED, BLOCKED_RUN, GOOD_RUN, GUESSED_RUN, TASK, order
from tools import lookup_order
from trace_check import bad_steps
@pytest.mark.parametrize(
"trace, first",
[
(GOOD_RUN, None),
(BLOCKED_RUN, (1, "tool_result_invalid")),
(GUESSED_RUN, (2, "ungrounded_argument")),
],
ids=["good", "blocked-403", "guessed-amount"],
)
def test_first_bad_step(trace, first):
flags = bad_steps(trace, TASK)
assert (flags[0] if flags else None) == first
@pytest.mark.parametrize(
"status, body, ok",
[
(200, order(49.0), True),
(403, ACCESS_DENIED, False),
(200, "<html>Maintenance</html>", False),
],
ids=["good-order", "blocked-403", "maintenance-page"],
)
def test_lookup_order_ok_flag(status, body, ok):
assert lookup_order(status, body)["ok"] is okuv run --no-project --with pytest python -m pytest -v --tb=no -rNtest_runs.py::test_first_bad_step[good] PASSED [ 16%]
test_runs.py::test_first_bad_step[blocked-403] PASSED [ 33%]
test_runs.py::test_first_bad_step[guessed-amount] PASSED [ 50%]
test_runs.py::test_lookup_order_ok_flag[good-order] PASSED [ 66%]
test_runs.py::test_lookup_order_ok_flag[blocked-403] FAILED [ 83%]
test_runs.py::test_lookup_order_ok_flag[maintenance-page] FAILED [100%]
========================= 2 failed, 4 passed in 0.09s =========================After the fix, tools.py reports ok only for status 200 and a body that is an order. Run the same tests again.
import json
def lookup_order(status, body):
try:
order = json.loads(body)
except json.JSONDecodeError:
order = None
ok = status == 200 and isinstance(order, dict) and "total" in order
return {"ok": ok, "output": body}uv run --no-project --with pytest python -m pytest -v --tb=no -rNtest_runs.py::test_first_bad_step[good] PASSED [ 16%]
test_runs.py::test_first_bad_step[blocked-403] PASSED [ 33%]
test_runs.py::test_first_bad_step[guessed-amount] PASSED [ 50%]
test_runs.py::test_lookup_order_ok_flag[good-order] PASSED [ 66%]
test_runs.py::test_lookup_order_ok_flag[blocked-403] PASSED [ 83%]
test_runs.py::test_lookup_order_ok_flag[maintenance-page] PASSED [100%]
============================== 6 passed in 0.04s ==============================What this checker misses
It is a teaching checker, not a production evaluator. A trace shows what happened. A check written as code tells you whether it was right. This one does not catch:
- A stale record that is well formed. If the order service returns an old total, and the agent refunds that same total, no rule fires.
- A number that matches by chance. If the task says the order arrived 49 days late, a guessed amount of 49.0 counts as grounded.
- A false claim in words. The Done rule only checks numbers.
Real traces can hold customer data. This one is made up. In the OpenTelemetry conventions, tool arguments and results are opt-in attributes, so decide on purpose what you record.
Next: stop it from shipping again
You found the bad step and kept one run as a test. Episode 2 saves the whole failure as an eval case, grades what changed and lets CI block the release. Read Turn a failed agent run into an eval that blocks the release.
Explore this topic in the workspace
Topic Breakdown gives you a structured revision guide for this topic and lets you highlight any phrase to open side-by-side chats with worked examples. Sign in to open it.
Open breakdownOr type LLM agent debugging, tracing and evals into the topic box on the home page. To see a lesson first, open the sample breakdown on Machine Learning.
Sources
All sources were checked on 8 November 2026. Read each page for the full context.
- OpenAI Agents SDK: Tracing
A trace is one end-to-end run made of spans. Model calls and function tool calls each get a span by default.
- OpenTelemetry: GenAI tool execution
A tool span has a tool name and, if the call failed, an error type. Tool arguments and results are opt-in. Status is Development, so names can change.
- Microsoft Foundry: Function calling
The model returns a function call with arguments. Your application runs the function and returns the result.
- Anthropic: Building effective agents
An agent needs ground truth from the environment at each step, such as tool call results.
- RFC 9110, section 15.5.4: 403 Forbidden
A 403 means the server understood the request but refuses to fulfill it.
- Python: json.loads and JSONDecodeError
JSONDecodeError is raised when the data is not a valid JSON document.
- pytest: parametrize
One test function can run over several sets of arguments.