Replaying Agent Loops for Debugging

Ever stared at an agent failure in your logs, tried to reproduce it, and watched the agent work perfectly on the same input every time you re-ran it? It's one of the most frustrating experiences in agent development. The failure was real — you have the bad output — but it lived in a specific sequence of tool results and model decisions you can't recreate on demand. Agent loop replay solves this by letting you re-run the exact recorded trace, step by step, with the same inputs the failing run saw.

This is a teardown of a debugging setup that logs plenty but can't replay anything, why that makes hard bugs nearly unfixable, and the rewrite that makes any failure reproducible.

Before: The Weak Prompt

Here's a typical logging setup. It records a lot, and none of it lets you replay.

[object Object], ,[object Object],(,[object Object],):
    ,[object Object], step ,[object Object], ,[object Object],(max_steps):
        action = model_decide(state, tools)
        logger.info(,[object Object],)   ,[object Object],
        result = run_tool(action)
        logger.info(,[object Object],)            ,[object Object],
        state = update_state(state, action, result)
    ,[object Object], force_answer(state)

What this does: It logs which tool was chosen and that a result came back, which looks like reasonable observability — but it records only names and acknowledgments, not the actual inputs, arguments, and result payloads, so you can see the shape of a run without being able to reconstruct or replay it.

Why It Fails

The logging fails for debugging because it captures the narrative of a run but not its data. You can read that the agent chose

search

read_doc

search

Reproduction is the core problem. Agent runs depend on tool results that change over time — a search index updates, a record changes, an API returns something different today than it did during the failure. So re-running the same user input doesn't reproduce the failure, because the tools return different data now. Without the original tool results captured, the specific conditions that triggered the bug are gone the moment the run ends.

⚡ Pro tip: The single most important thing to capture for replay is the exact input and output of every tool call, byte for byte. The model's decisions are a function of what the tools returned, so if you have the tool results, you can reproduce the reasoning. If you don't, you're trying to debug a decision without the evidence it was based on — which is guesswork, not debugging.

There's a deeper issue with debugging agents that this exposes. Traditional debugging leans on determinism: run it again, set a breakpoint, watch it fail. Agents violate that assumption twice over — the model can sample differently, and the tools can return differently. Any debugging approach that assumes "just run it again" is defeated before it starts. Agent loop replay is what restores the determinism that debugging depends on, by pinning both sources of variation.

It's worth appreciating how much this changes the economics of fixing a hard bug. Without replay, a rare intermittent failure might take days to catch in the act, because you have to wait for it to happen again while you happen to be watching with the right logging enabled. With replay, the moment it happens once and you have the trace, you can reproduce it on demand as many times as you need — add logging, test a fix, confirm the fix, all against the exact conditions that triggered it. A bug that was a multi-day stakeout becomes a normal debugging session. That's the real payoff of agent loop replay: it converts the hardest category of agent bug, the un-reproducible intermittent one, into an ordinary one.

⚡ Pro tip: Capture the model's raw outputs in the trace too, not just the parsed actions. When an agent does something bizarre, the question is often whether the model produced garbage or whether your parsing mangled good output. The raw completion tells you which, and without it you can waste hours debugging your parser when the model was at fault, or vice versa.

After: The Improved Prompt

The rewrite captures a complete, replayable trace — every input, argument, and result — and provides a replay mode that feeds recorded tool results back instead of calling live tools.

[object Object], ,[object Object],(,[object Object],):
    recorder = trace ,[object Object], Recorder(run_id=state.run_id)
    ,[object Object], step ,[object Object], ,[object Object],(max_steps):
        recorder.snapshot_state(step, state)
        action = model_decide(state, tools)
        recorder.record_action(step, action)          ,[object Object],
        ,[object Object], action.name == ,[object Object],:
            recorder.finish(action)
            ,[object Object], action.args[,[object Object],]
        ,[object Object], replay ,[object Object], ,[object Object], ,[object Object],:
            result = replay.result_for(step)           ,[object Object],
        ,[object Object],:
            result = run_tool(action)
        recorder.record_result(step, result)           ,[object Object],
        state = update_state(state, action, result)
    ,[object Object], force_answer(state)

What this does: It records a full snapshot of state, the action with all its arguments, and the complete result payload at every step, and in replay mode it feeds the recorded tool results back instead of calling live tools — so a failed run can be re-executed against the exact data it originally saw.

The replay harness reads a recorded trace and re-runs it deterministically for inspection.

[object Object], ,[object Object],(,[object Object],):
    trace = load_trace(trace_file)
    initial = trace.initial_state()
    ,[object Object],
    ,[object Object], agent_loop(initial, replay=trace, deterministic=,[object Object],)

What this does: It loads a saved trace and re-runs the loop with deterministic model settings and the recorded tool results, reproducing the original failure exactly so you can step through it, add logging, and find the root cause on demand.

Breaking Down Each Element

The full result capture is the foundation. Recording complete tool payloads — not summaries, not acknowledgments — is what makes replay possible, because the model's behavior is downstream of exactly those payloads. This is the piece the weak version skipped, and everything else depends on it.

The replay mode that substitutes recorded results for live tool calls is what pins down tool nondeterminism. By feeding the agent the exact results the failing run saw, you remove the "tools return different data now" problem entirely. The agent reasons over the original evidence, not today's.

The deterministic model setting pins the other source of variation. Recorded tool results plus deterministic sampling means the replay follows the original path exactly, which is what lets you reproduce a specific failure rather than a similar one. Both pins are necessary; either alone leaves a source of drift.

⚠️ Common mistake: Capturing traces only for failed runs. You usually don't know a run failed until after it's over, and by then, if you weren't recording, the trace is gone. Record replayable traces for all runs, at least by sampling, and retain them long enough to investigate. A failure you can't replay because you only started recording after you noticed it is the most common way teams end up unable to debug their hardest bugs.

⚡ Pro tip: Store traces in a format you can diff. When you fix a bug and re-run, you want to compare the new trace against the original to confirm the behavior actually changed at the step you think it did. A structured, diffable trace format turns "I think I fixed it" into "the trace diverges exactly where I intended and nowhere else," which is a far stronger guarantee.

Variations for Different Contexts

For a high-volume agent where recording every run is too expensive, sample — capture full replayable traces for a percentage of runs plus all runs that hit error or ceiling outcomes, so you always have the failures and a representative sample of the rest.

For a multi-agent system, replay needs to capture the messages between agents too, not just each agent's tools, since a bug often lives in the coordination. An engineer on a multi-agent team told me their hardest bugs were always in the hand-offs, invisible until they started recording inter-agent messages as part of the trace.

For a compliance-sensitive agent, replayable traces double as an audit record — the exact inputs, decisions, and outputs of any run, reproducible on demand, which satisfies both the debugging need and the audit requirement with one mechanism.

For an agent under active development, agent loop replay pairs naturally with a regression suite: save the traces of runs you've verified as correct, and after any change, replay them and confirm the agent still reaches the same good outcome against the same recorded inputs. This turns your accumulated debugging traces into a growing test set for free — every hard bug you capture and fix becomes a permanent guard against that bug returning. The traces you record to debug today are the regression tests that protect you tomorrow, which makes the replay infrastructure compound in value the longer you run it.

⚡ Pro tip: Give every replayable trace a stable ID and make it linkable from your logs, dashboards, and alerts. The friction that kills replay in practice isn't the replay itself — it's finding the specific trace you want among thousands. When a monitoring alert links directly to the replayable traces behind it, reproducing a production failure becomes a single click instead of a scavenger hunt, and a tool that's one click away actually gets used.

Save and Reuse This

Replay infrastructure is real work to build the first time and trivial to reuse once you have it, which makes it exactly the kind of thing worth building well once. The recorder, the replay harness, and the trace format carry across every agent you build.

A prompt and snippet library like PromptABCD is a handy home for your replay scaffolding and the prompts it runs, so your next agent is debuggable from day one — every failure reproducible on demand — instead of leaving you staring at a bad output you can't recreate.