langgraph-replay

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

agent-replay.mp4

---

Why langgraph-replay?

LLM agents are non-deterministic. A prompt tweak or model upgrade can silently break routing logic, and you only find out in production. langgraph-replay gives you a local, zero-config way to:

• See exactly what happened — every LangGraph step stored in a single SQLite file with full state snapshots.
• Replay without burning tokens — deterministic mode substitutes recorded LLM responses and tool outputs. No API calls, instant execution.
• Catch regressions — regression mode sends real prompts to your LLM but uses recorded tool outputs. If the agent takes a different path, you'll know.
• Fork and explore — branch from any checkpoint, tweak inputs, and re-run downstream steps.

One pip install, one .db file, a built-in dashboard. No infrastructure.

Install

pip install langgraph-replay

Requires Python 3.10+.

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 --graph my_agent:build_graph
# → http://127.0.0.1:8777

Features

Feature	Description
Checkpoint timeline	Every LangGraph step persisted to SQLite with full state and metadata
State diffs	Message-level and tool-call diffs between any two steps
Fork	Branch from any checkpoint and re-execute with modified inputs
Re-run / Restart	Re-execute from step 0 or any mid-run checkpoint with current code
Deterministic replay	Recorded LLM + tools — no API calls, instant verification
Regression replay	Live LLM + recorded tools — detect routing drift after prompt changes
Built-in dashboard	React UI for timeline visualization, diffs, forking, and replay

Examples

make examples
cd examples
cp .env.example .env   # OpenAI-compatible API key
poetry run python chat_agent.py
poetry run langgraph-replay dev --db chat_replay.db --graph chat_agent:build_graph
# → http://127.0.0.1:8777

Or from the repo root after the agent run: make dev.

See examples/ for a chat agent with tools and replay walkthrough.

Development

make help          # available targets
make install-dev   # editable SDK install with dev extras
make lint          # ruff + dashboard typecheck
make test          # pytest
make build         # UI bundle + Python wheel

Release

Push a semver tag (v0.1.0, v1.2.3, …) → GitHub Actions builds the dashboard, packages the wheel, and publishes to PyPI via trusted publishing.

See packages/sdk/PUBLISHING.md for setup details.

Repo layout

Path	Description
packages/sdk/	Python package published to PyPI — full API reference in its README
packages/dashboard/	React debugger UI (bundled into the wheel)
examples/	Sample agents you can run immediately

License

MIT — see LICENSE.