langgraph-replay

Time-travel debugging for LangGraph agents.
Record every step. Replay without API calls. Fork from any checkpoint. Catch regressions before they ship.

Install

pip install langgraph-replay

Requires Python 3.10+ and a LangGraph agent.

Why langgraph-replay?

LLM agents are non-deterministic. A prompt tweak or model upgrade can silently break routing, and you only discover it in production. langgraph-replay gives you:

• Full execution history in a single SQLite file — no external services.
• Deterministic replay — substitute recorded LLM + tool responses. Zero API calls, instant re-execution.
• Regression detection — real LLM + recorded tools. If the agent routes differently after a code change, you see exactly where it diverged.
• Fork from any step — branch, modify inputs, and re-run downstream logic.
• Built-in dashboard — timeline, state diffs, and one-click replay/fork in your browser.

Quick start

from langgraph_replay import ReplayCheckpointer, ReplayCallbackHandler

checkpointer = ReplayCheckpointer(db_path="replay.db")
handler = ReplayCallbackHandler("replay.db")

graph = workflow.compile(checkpointer=checkpointer)
graph.invoke(
    {"messages": [("user", "What's the weather in Tokyo?")]},
    {"configurable": {"thread_id": "run-1"}, "callbacks": [handler]},
)

Launch the dashboard:

langgraph-replay dev --db replay.db
langgraph-replay dev --db replay.db --graph my_agent:build_graph   # enables Re-run and Fork

Features

Dashboard

CLI

# Launch dashboard
langgraph-replay dev --db replay.db --graph my_agent:build_graph

# Restart from a specific step
langgraph-replay replay --db replay.db --graph my_agent:build_graph --thread run-1 --from-step 3

# Deterministic replay (no API calls)
langgraph-replay replay --db replay.db --graph my_agent:build_graph --thread run-1 --mode deterministic

# Regression replay (real LLM, recorded tools)
langgraph-replay replay --db replay.db --graph my_agent:build_graph --thread run-1 --mode regression

Python API

from langgraph_replay import (
    ReplayCheckpointer,
    ReplayCallbackHandler,
    StateDiffEngine,
    ForkManager,
    RestartEngine,
    ReplayRunner,
    DivergenceReport,
    serve,
)

# Restart from a checkpoint
RestartEngine("replay.db", graph).restart("run-1", from_step=3)

# Deterministic replay
ReplayRunner("replay.db", graph).replay("run-1", mode="deterministic")

# Regression replay with divergence report
report = ReplayRunner("replay.db", graph).replay("run-1", mode="regression")

Examples

See the examples directory for a runnable chat agent with tools (chat_agent.py).

Links

• Repository: https://github.com/devendra116/agent-replay-engine
• Issues: https://github.com/devendra116/agent-replay-engine/issues
• License: MIT