How We Built a Way to Replay AI Agent Failures Without Paying to Reproduce Them

What testing our tool against 104 real GitHub issues across eight agent frameworks taught us

By Rudrendu Paul and Sourav Nandy

Repo: github.com/RudrenduPaul/agent-observability. It records and replays AI agent runs so you can debug a failure without paying to trigger it again. Install it with pip install agent-observability-trace-cli.

Quick summary: We tested our approach against 104 real GitHub issues from eight different agent frameworks. It worked for almost all of them. Here is what we learned, including the cases where it did not work at first and what we had to change.

---

Imagine your LangGraph agent fails on step 8 of a 10-step process. LangSmith shows you the trace, so you can see what happened.

But to actually reproduce that failure so you can study it, you have to run the whole agent again. That means eight more calls to the language model, about 30 more seconds of waiting, and roughly 15 cents in API costs. And because language models do not always answer the same way twice, the failure might not even happen again.

Nobody has really solved this problem yet.

Here is what our approach looks like instead: record a real network call once, then replay it as many times as you want, with no network traffic and no cost.

Record it once, while it's live. After that, every replay is the same run, with the same result, no API calls and no money spent triggering it again.

Even advanced AI models struggle with a task that sounds simple: look at a multi-agent system that just failed, and say which agent caused it. In 2025, researchers from Penn State and Duke built a dataset of 127 real multi-agent failures and tested whether AI models could correctly identify the cause. The best model only picked the right agent 53.5% of the time, and only found the exact failing step 14.2% of the time. The researchers concluded that even the most advanced reasoning models are not reliable enough for this task yet.

You cannot fix this with a better dashboard. Most "agent observability" tools are answering the wrong question. Knowing what happened is fairly easy. Making that exact failure happen again, cheaply and reliably, so you can actually study it, is a completely different problem, and almost nobody has built for it.

This matters right now because agent deployments are growing faster than anyone's ability to debug them by hand. Gartner predicts that 40% of enterprise applications will use task-specific AI agents by the end of 2026, up from under 5% in 2025, one of the fastest adoption curves it has ever tracked. McKinsey's 2026 State of AI report is more cautious: 23% of organizations say they are actually scaling an agent system somewhere in the business, and no single business function has passed 10% adoption yet. Put those two numbers side by side and the picture is clear. Agents are moving into production much faster than the tools to debug them are maturing.

The real gap in agent observability

When people talk about "agent observability," they usually mean tracking an agent's calls, sending them to a dashboard, and looking at a trace when something breaks. That gives you visibility into what happened. It does not give you an easy or cheap way to make the same problem happen again so you can actually study it.

That is the important difference. Trace tools tell you what happened. They do not tell you how to make the same thing happen again, cheaply and reliably. Those are two separate problems. The first one is mostly solved already. Almost nobody has solved the second one.

The cost of the API calls to trigger a failure again is actually the smaller cost. The bigger cost is the engineering time spent re-running a production failure over and over, hoping to catch it in the act. That is what really slows teams down once their agents move past the demo stage.

Other parts of software have solved this kind of problem before. Mozilla's rr debugger has been able to record and replay the exact behavior of an ordinary Linux program since 2017, and it is solid enough to work on something as large as Firefox's codebase. ACM Queue wrote about the same general idea in a widely cited 2020 piece called "To Catch a Failure: The Record-and-Replay Approach to Debugging." In the Ruby and Python testing world, a library called VCR has let developers record one real HTTP call and replay it in their tests for well over a decade. The idea itself is not new. What is new is applying it carefully to the kind of network traffic that AI agents create. Multi-agent systems make this more urgent, since the research numbers above are exactly what you would expect when nobody can cheaply reproduce a failure to study it in the first place.

Finding out where our approach breaks down

Before writing anything about this idea, we tested it. We went through every GitHub issue where a developer had reported a real, specific problem, not a documentation typo or a feature request, across eight of the most widely used agent frameworks. For each one, we asked a simple question: if we pointed our tool's actual recording system at this exact failure, would it capture enough information to explain what went wrong?

We found a working fix for 104 of those issues, spanning langchain-ai/langgraph, langchain-ai/langchain, openai/openai-agents-python, run-llama/llama_index, microsoft/autogen, crewAIInc/crewAI, pydantic/pydantic-ai, deepset-ai/haystack, and agno-agi/agno. Every one of those fixes is already in the project's main branch, and the whole test suite, 1,367 tests, passes cleanly.

The process mattered more than the final count. We started out assuming that watching the HTTP traffic between a Python program and the model's API would be enough, since that is how most Python AI tools actually talk to a model. That assumption turned out to be wrong fairly quickly, and it was wrong in a useful way. It kept failing on the same kinds of traffic, not on random edge cases.

• Google's Gemini and Vertex AI tools normally send requests over gRPC instead of ordinary HTTP. A tool that only watches HTTP traffic sees nothing at all in that case. That gap is exactly why langchain-ai/langchain#8304 happened: VertexAI's text-bison model quietly returned no output, and there was no record of why.
• AWS's SDK for Bedrock and SageMaker manages its own network connections in a way that sits below the layer we were watching. That gap left crewAIInc/crewAI#4749 with no captured evidence to work from, after a Bedrock error on a multi-tool-call request.
• OpenAI's Realtime API and any MCP tool server use long-lived connections instead of a single request and response. When tool calling silently broke in a Realtime Agent, in openai/openai-agents-python#2308, we could not just extend our existing tool to handle it. We had to build a completely separate system to capture that kind of connection.
• We also found a subtle bug involving HTTP clients that get created once, when a program first starts, before any recording session has begun. This is exactly how langgraph dev starts up. Our early fix only patched clients created after recording started, so it silently missed every one of these. Fixing it meant changing how our tool decides which client to intercept, not just flipping a setting.

We are not blaming any of these frameworks. This is simply how complicated the real problem is. Capturing everything an agent does takes four or five separate pieces of work, not just one. The only way to find the missing pieces is by testing against failures real users have actually hit. Reading the documentation and guessing will not get you there.

Here is what the actual process of checking a run looks like: list the runs you have recorded, then point the inspect command at one to automatically flag anything that looks broken.

This is the same process we repeated 104 times against real GitHub issues: find the run, point inspect at it, see whether the evidence is actually there.

Twelve examples out of the 104

Every row below links to the real issue. This is a representative sample of what we found. The complete list of all 104 issues, with the exact fix for each one, is in the repository.

Issue	Framework	What broke	What fixed it
agno-agi/agno#5298	Agno	An UnboundLocalError during streaming under Uvicorn	We added support for Agno's own streaming setup, along with timestamps on each streamed chunk, so the timing and state around the failure became visible.
crewAIInc/crewAI#4749	crewAI	An AWS Bedrock error on a request with multiple tool calls	We built a way to watch botocore/boto3 traffic directly, since AWS's SDK bypasses the normal HTTP layer entirely and nothing had been recorded at all before.
langchain-ai/langchain#8304	LangChain	VertexAI's text-bison silently returning no output	We built support for capturing gRPC traffic, since some SDKs default to gRPC instead of HTTP.
langchain-ai/langgraph#2920	LangGraph	A report that the model felt slow inside a LangGraph agent, with no way to tell where the time was going	We added timing for each exchange and a metric for unaccounted time, so it became clear how much delay came from the model versus the framework itself.
langchain-ai/langgraph#6202	LangGraph	The frontend stopped receiving stream updates mid-run, even though the backend was still running	We added a pass-through streaming mode plus new tracking on the outbound delivery path, so this kind of silent stall becomes visible.
langchain-ai/langgraph#7714	LangGraph	A report of checkpoints using 85% more storage than expected, with no way to confirm it	We built a way to measure checkpoint size and content independently, so this kind of claim can actually be checked.
openai/openai-agents-python#2308	OpenAI Agents SDK	Tool calling silently failing to work with a Realtime Agent	We built a dedicated way to capture the Realtime API's long-lived connection traffic.
openai/openai-agents-python#1671	OpenAI Agents SDK	Occasional "tool not found" errors after an agent handoff	We added a check that compares the failing tool name against the registered tools by similarity, which catches near-misses and mismatched capitalization.
pydantic/pydantic-ai#2837	pydantic-ai	A FallbackModel quietly swallowing an error raised inside the agent	We added a way to watch boto3 traffic directly, along with a pydantic-ai integration that hooks into the agent's own run and state transitions.
run-llama/llama_index#7170	LlamaIndex	The agent occasionally calling tools that do not exist, then crashing	We added an automatic check that compares every tool call against the run's actual list of registered tools, so made-up tool names get flagged right away.
run-llama/llama_index#18937	LlamaIndex	Google's GenAI SDK silently disabling tool calling, with no visible cause	We fixed the ordering bug in how we intercept clients, and added dedicated support for the google-genai SDK.
langchain-ai/langgraph#6449	LangGraph + MCP	An error from an MCP server that was not being handled correctly, with no evidence captured	We built a way to record MCP's raw message exchanges directly, since MCP tool calls do not travel over HTTP at all.

Where this approach genuinely does not work

A tool like this earns trust by being honest about its own limits, so here is where it stops working.

The tool only sees traffic sent by your own program. It cannot see the internal calls made by a separate hosted service that you do not run yourself. Our support for gRPC, the protocol some AI providers use instead of HTTP, is real but only partial. We fully capture the common request-and-response pattern. We do not yet capture gRPC's streaming modes, including the newer async streaming style some tools use. Recording only starts once an actual request exists. If something fails earlier, for example while an SDK is still building that request, there is nothing for us to capture. If you have set up one of our framework-specific integrations, its own error handling can sometimes still catch that earlier kind of failure. If you have not set one up, you will need to catch that error somewhere else in your code.

We also want to be honest about what this tool replaces and what it does not. Sometimes you need to understand behavior across live traffic where you have not seen a specific failure yet. For that kind of open-ended debugging, you still want a normal dashboard tool watching everything as it happens. Our tool is built for the moment right after you already know something broke, and you need to study that exact failure closely, as many times as you need, at no extra cost. It is not meant to help you discover unknown problems in the first place. These are two different jobs, and treating them as the same thing oversells both.

If your team is about to run a lot more agents in production, here is the simple takeaway. Do not treat the ability to reproduce a failure offline as a nice-to-have you will get to later. Treat it as something you need in place before you scale, the same way you would want proper monitoring in place before scaling a large system. The numbers from McKinsey and Gartner above show that scaling is already happening faster than most teams' debugging tools can keep up with. Once a failure is something you can reproduce locally instead of re-running against a live API, the time it takes to fix a bug can drop from a frustrating afternoon to just a few minutes, because the run is already sitting on your disk.

Why this gets more urgent once agents call other agents

Everything above describes one team debugging its own agent. The next problem is much bigger. Agents are starting to call other organizations' agents directly, as a real piece of infrastructure, not just an experiment.

The Agent2Agent protocol, now managed by the Linux Foundation, passed 150 supporting organizations and 22,000 GitHub stars in its first year, with SDKs in five languages already in production use across supply chain, financial services, insurance, and IT operations. Separately, Gartner expects AI agents to be involved in 90% of business-to-business buying activity by 2028, representing more than $15 trillion in spending.

Put that next to what we found earlier. Figuring out which agent caused a failure, inside your own system, is already unreliable, with even the best AI models only getting it right about half the time. That problem does not get easier once the failure crosses into someone else's agent. It gets harder, because you no longer control both sides of the interaction, and there is no shared standard yet for tracing a failure across company boundaries the way there is for tracing normal software within a single company.

This is exactly where debugging tools need to change. They cannot stay something a person clicks through on a dashboard. They need to become something another program, or another agent, can call directly. That is the reason our command-line tool always offers a plain, structured data option instead of only a page meant for a person to read. The command agent-trace show <run_id> returns the full recorded run as JSON by default. The commands agent-trace list, agent-trace inspect <run_id>, and agent-trace diff <run_a> <run_b> all support a --json option too, so another program, or a CI job, can read the result with no person involved. That is a different goal than a dashboard built for human eyes, and it is the goal that actually matters once debugging becomes a normal step inside an automated pipeline instead of a stressful afternoon for one engineer.

What other tools solve, and what they miss

Most existing tools in this space fall into four groups. Each one solves a real part of the problem, but leaves the same gap open.

LangSmith, Langfuse, and Helicone are the most common tools people already use. LangSmith is a strong choice if your team already uses LangChain, and it is genuinely good at showing traces, managing datasets, and versioning prompts. Langfuse offers similar strengths as a fully open-source tool you can host yourself, backed by solid database storage. Helicone works as a simple proxy that sits in front of your API calls and records the raw traffic, with very little setup required. All three are good at showing you what your system is doing across many runs. But with all three, reproducing one specific failing run still generally means running it again against the live model, with whatever cost and unpredictability that carries.

There are also tools built on the OpenTelemetry community's GenAI standards, which have been under development since 2024. These make traces look the same across different vendors, so you are not locked into one tool. That is a genuinely useful improvement. It does nothing, though, to help you cheaply reproduce the run that created the trace in the first place.

Older application monitoring tools have added AI-specific features on top of their existing systems. This is a real strength if you need to see agent problems alongside the rest of your infrastructure. But the gap here is structural. A response can come back with a normal success code and still contain a wrong answer or leaked data, and these tools were built to watch status codes and response times, not to check whether the content of a response is actually correct.

Finally, there are proxy and gateway tools that sit at the edge of your network and log traffic, mainly to track cost and usage. They are easy to add, but that ease is also their limit. They see raw traffic, not what is actually happening inside your agent's reasoning, and that internal state is usually exactly what you need to explain a failure.

A gap runs through all four of these approaches. None of them make it cheap, reliable, and free to reproduce one specific known failure. None of them go beyond your normal HTTP client to also cover the gRPC, WebSocket, and other connection types that agent frameworks increasingly use underneath their SDKs. We built a tool that works at that lower, transport level specifically to close that gap, and then tested it broadly enough to cover the connection types agents actually use, validating it against real reported failures from real users.

Try it

The repository is called agent-observability. The Python package is agent-observability-trace-cli. Once installed, the command-line tool is agent-trace, and the Python package you import is agent_trace.

pip install agent-observability-trace-cli
# framework extras, e.g.:
pip install agent-observability-trace-cli[langgraph]
pip install agent-observability-trace-cli[openai-agents]

# Record a run (your script just needs `import agent_trace` somewhere)
agent-trace run --name my_agent -- python my_agent.py

# List recorded runs
agent-trace list

# Replay offline, zero network, zero cost
agent-trace replay <run_id>

# Inspect a run for known failure patterns
agent-trace inspect <run_id>

# Diff two runs
agent-trace diff <run_a> <run_b>

If you would rather control things directly in code instead of using the command line, you can use the Python API:

from agent_trace import tracer
import httpx

@tracer.instrument(record=True)
def fetch_data(query: str) -> dict:
    with tracer.span("http-call") as span:
        resp = httpx.get("https://httpbin.org/get", params={"q": query})
        span.set_attribute("http.status_code", resp.status_code)
        return resp.json()

In CI, the same commands work the same way. You just give the run a specific ID so the next step knows which run to check:

# .github/workflows/agent-debug.yml
name: Capture agent runs for debugging
on: [push, pull_request]

jobs:
  capture:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: pip install agent-observability-trace-cli[langgraph]
      - name: Run and record agent
        run: agent-trace run --run-id ci-run --name ci-run -- python my_agent.py
      - name: Check for known failure patterns
        run: agent-trace inspect ci-run --json
      - uses: actions/upload-artifact@v4
        with:
          name: agent-trace-runs
          path: ~/.agent-trace/runs/

This records every run, saves it as a downloadable file, and lets you replay it locally in under a millisecond, with no API calls and no cost.

In our own testing, recording added about 0.011% overhead to a GPT-4o call, a tiny fraction of the call's normal response time. Replay runs in under a millisecond, and the result is identical, byte for byte, to the original run.

Every command supports a JSON output option, so another program can read the result directly. The run command writes its normal progress messages to one output stream, and a single final summary as JSON to another, since we cannot control the output format of whatever program is running underneath it. This connects back to what we described earlier about agents calling other agents: a debugging step becomes something a program can run on its own, the same way a person would run it by hand.

This is what an automated pipeline, or another agent, actually reads: structured data, not a page built for a person to look at.

One question we have not settled yet: should replay keep working the way it does today, as a small piece of Python code you wrap around your function, or should it become a plugin that works with any OpenTelemetry-based pipeline with no code changes at all? We would genuinely like your opinion. The discussion is open in our issue tracker, which is where that conversation belongs.

Repo: github.com/RudrenduPaul/agent-observability. If this would have saved you from re-running a live API just to catch a bug, starring the repo helps other teams find it.

You record a run once with agent-trace run, and you can replay it as many times as you want with agent-trace replay. The failure is already sitting on your disk, waiting for you to look at it again.

---

References

• Zhang, Yin, Zhang, Liu, Han, Zhang, Li, Wang, Wang, Chen, Wu. "Which Agent Causes Task Failures and When? On Automated Failure Attribution of LLM Multi-Agent Systems." ICML 2025 Spotlight, arXiv:2505.00212.
• O'Callahan, Jones, Froyd, Huey, Noll, Partush. "Engineering Record and Replay for Deployability." USENIX ATC 2017, arXiv:1705.05937. See also the rr project.
• "To Catch a Failure: The Record-and-Replay Approach to Debugging." ACM Queue, 2020.
• Gartner. "Gartner Predicts 40% of Enterprise Apps Will Feature Task-Specific AI Agents by 2026, Up from Less Than 5% in 2025." August 2025.
• McKinsey State of AI 2026, as covered by Forbes, March 2026.
• Linux Foundation. "A2A Protocol Surpasses 150 Organizations, Lands in Major Cloud Platforms, and Sees Enterprise Production Use in First Year." April 2026.
• Gartner B2B commerce forecast, as covered by Digital Commerce 360, November 2025.
• OpenTelemetry. GenAI Semantic Conventions. 2026.

---

Co-authored by Rudrendu Paul and Sourav Nandy. Rudrendu is a founder and engineer building open-source tools for AI agents, including agent-trace (Agent Observability) and a related set of AI-agent infrastructure projects. Find the code at github.com/RudrenduPaul.