mirror of
https://github.com/langchain-ai/langgraph.git
synced 2026-08-25 00:52:25 +02:00
Sydney RunkleandGitHub
51cbdbd5cd
# Fix: Create fork checkpoint on subgraph time travel
## Problem
When time-traveling to a subgraph checkpoint that has an interrupt, and
then resuming, the resume would load the **wrong state** — it would pick
up the original execution's latest checkpoint instead of the
time-traveled one.
This happened because replaying from a subgraph checkpoint never created
a new parent checkpoint. If the replay hit an interrupt before
`after_tick()` ran, no checkpoint was written at all, so the parent's
"latest" checkpoint was still the old one from the original execution.
## Fix
When the loop detects a time-travel replay (not an `update_state` fork),
it now **eagerly writes a fork checkpoint** at the start of the tick.
This ensures:
1. The parent thread's latest checkpoint points to the replayed state
2. Subsequent `Command(resume=...)` calls find the correct checkpoint
3. Stale `INTERRUPT` pending writes from the old checkpoint are cleared
(they reference old task IDs)
Additionally, the subgraph replay logic now uses the **parent checkpoint
ID** (from `prev_checkpoint_config`) when resolving subgraph checkpoints
during time-travel, matching the existing behavior for `update_state`
forks.
## Checkpoint flow diagrams
### Before fix: time travel leaves no fork
```
Original execution:
C0 (start) --> C1 (step_a) --> C2 (ask_1 interrupt) --> C3 (resume) --> C4 (ask_2 interrupt) --> C5 (done)
Time travel to C2 (subgraph config):
Replay runs... hits interrupt... no new checkpoint written.
Parent "latest" is still C5.
Command(resume="new_answer"):
Loads C5 (wrong!) instead of the replayed C2 state.
```
### After fix: time travel creates a fork
```
Original execution:
C0 --> C1 --> C2 --> C3 --> C4 --> C5 (done)
Time travel to C2 (subgraph config):
C0 --> C1 --> C2 --> C3 --> C4 --> C5
\
F1 (fork, source="fork") <-- new latest
Command(resume="new_answer"):
Loads F1 (correct!) --> resumes from the right state.
After full resume:
C0 --> C1 --> C2 --> C3 --> C4 --> C5
\
F1 --> F2 (ask_1 result) --> F3 (ask_2 interrupt) --> F4 (done)
```
### Manual fork via `update_state` (unchanged)
```
C0 --> C1 --> C2 --> C3
\
U1 (source="update") <-- created by update_state()
This path already worked. The fix skips update/fork sources
so existing behavior is preserved.
```
## Changes
- **`libs/langgraph/langgraph/pregel/_loop.py`**:
- Extract `is_time_traveling` flag from the existing replay detection
logic for reuse
- Write a fork checkpoint (`source="fork"`) eagerly at the start of a
time-travel tick, before execution begins
- Clear stale `INTERRUPT` pending writes when creating the fork (they
reference old task IDs that won't match the new checkpoint)
- Unify subgraph replay ID resolution: check `source in ("update",
"fork")` instead of a separate `is_time_traveling` condition, since the
new fork checkpoint now has `source="fork"`
- **`libs/langgraph/tests/test_time_travel.py`** and
**`test_time_travel_async.py`**: Added 4 new test cases (sync + async):
- `test_replay_from_before_interrupt_then_resume` — replays from a
checkpoint before an interrupt, resumes with a new answer, and verifies
the full checkpoint history (source, next, values) at each stage
- `test_subgraph_time_travel_resume_from_first_interrupt` — time-travels
to a subgraph's first interrupt, resumes both interrupts with new
answers, and verifies the fork creates a new branch while preserving the
original
- `test_subgraph_time_travel_resume_from_second_interrupt` —
time-travels to a subgraph's second interrupt, resumes with a new
answer, and verifies the first interrupt's original answer is preserved
- `test_subgraph_time_travel_checkpoint_pattern` — verifies the fork
checkpoint branches from the correct replay point and that the full
checkpoint tree is correct after resume
- **`libs/langgraph/tests/test_pregel.py`** /
**`test_pregel_async.py`**: Updated existing
`test_weather_subgraph_state` to account for the new fork checkpoint
appearing in history (history length increases by 1)
Low-level orchestration framework for building stateful agents.
Trusted by companies shaping the future of agents – including Klarna, Replit, Elastic, and more – LangGraph is a low-level orchestration framework for building, managing, and deploying long-running, stateful agents.
pip install -U langgraph
If you're looking to quickly build agents with LangChain's create_agent (built on LangGraph), check out the LangChain Agents documentation.
Note
Looking for the JS/TS library? Check out LangGraph.js and the JS docs.
Why use LangGraph?
LangGraph provides low-level supporting infrastructure for any long-running, stateful workflow or agent:
- Durable execution — Build agents that persist through failures and can run for extended periods, automatically resuming from exactly where they left off.
- Human-in-the-loop — Seamlessly incorporate human oversight by inspecting and modifying agent state at any point during execution.
- Comprehensive memory — Create truly stateful agents with both short-term working memory for ongoing reasoning and long-term persistent memory across sessions.
- Debugging with LangSmith — Gain deep visibility into complex agent behavior with visualization tools that trace execution paths, capture state transitions, and provide detailed runtime metrics.
- Production-ready deployment — Deploy sophisticated agent systems confidently with scalable infrastructure designed to handle the unique challenges of stateful, long-running workflows.
Tip
For developing, debugging, and deploying AI agents and LLM applications, see LangSmith.
LangGraph ecosystem
While LangGraph can be used standalone, it also integrates seamlessly with any LangChain product, giving developers a full suite of tools for building agents.
To improve your LLM application development, pair LangGraph with:
- Deep Agents (new!) – Build agents that can plan, use subagents, and leverage file systems for complex tasks.
- LangChain – Provides integrations and composable components to streamline LLM application development.
- LangSmith – Helpful for agent evals and observability. Debug poor-performing LLM app runs, evaluate agent trajectories, gain visibility in production, and improve performance over time.
- LangSmith Deployment – Deploy and scale agents effortlessly with a purpose-built deployment platform for long-running, stateful workflows. Discover, reuse, configure, and share agents across teams – and iterate quickly with visual prototyping in LangSmith Studio.
Documentation
- docs.langchain.com – Comprehensive documentation, including conceptual overviews and guides
- reference.langchain.com/python/langgraph – API reference docs for LangGraph packages
- LangGraph Quickstart – Get started building with LangGraph
- Chat LangChain – Chat with the LangChain documentation and get answers to your questions
Discussions: Visit the LangChain Forum to connect with the community and share all of your technical questions, ideas, and feedback.
Additional resources
- Guides – Quick, actionable code snippets for topics such as streaming, adding memory & persistence, and design patterns (e.g. branching, subgraphs, etc.).
- LangChain Academy – Learn the basics of LangGraph in our free, structured course.
- Case studies – Hear how industry leaders use LangGraph to ship AI applications at scale.
- Contributing Guide – Learn how to contribute to LangChain projects and find good first issues.
- Code of Conduct – Our community guidelines and standards for participation.
Acknowledgements
LangGraph is inspired by Pregel and Apache Beam. The public interface draws inspiration from NetworkX. LangGraph is built by LangChain Inc, the creators of LangChain, but can be used without LangChain.