Advanced agents · Chapter 4 of 10
Time travel
Every superstep saves a checkpoint, so you can read a run's history, replay from a past step, edit a past state and fork a second ending.
Goals
- Run a five-node graph on a thread and read its checkpoint history.To do
- Rewind to step 3 and replay from it.To do
- Edit the state at step 3, fork, and compare both endings.To do
- Put the steps of a fork in order.To do
Step 1 of 4: The read
A thread is a timeline
Compile a graph with a checkpointer, run it with a thread_id, and LangGraph saves a checkpoint of the whole state after every superstep, as in the Agent systems path. Each checkpoint has its own checkpoint_id, a step and a source in its metadata (step -1 is the input), and a parentConfig that names the checkpoint before it. Linked by their parents, a thread's checkpoints form a timeline, and a timeline can branch.
Read the past
getStateHistory({ configurable: { thread_id } }) lists every checkpoint of the thread, newest first. Each item is a state snapshot: values, next (the nodes due to run), config and metadata. getState with a checkpoint_id in its config reads one of them. That is rewinding: you look at a past state and change nothing.
Replay and fork
invoke(null, config), with a config that names a past checkpoint, replays from it. Nodes before that checkpoint do not run again; the nodes after it do, so a real model may answer differently the second time. The new checkpoints grow on a new branch that starts with a copy whose source is fork. The old ones stay.
updateState(config, values, asNode) changes the past without erasing it. It writes a new checkpoint, source update, on top of the one config names, as if the node asNode had returned values, and returns the new checkpoint's config. Run invoke(null, thatConfig) and the thread forks: the first ending stays in the history and a second one grows from your edit. getState without a checkpoint_id reads the newest checkpoint, which is now the end of the fork.
Durability
A run's durability option decides when checkpoints are written. "async", the default, saves each one while the next superstep runs; "sync" saves it before the next superstep starts; "exit" saves only when the run ends. "exit" writes the least, but it leaves no past step to rewind to, and nothing to resume from if the process crashes halfway.
In this lab
Halden's refund check for ticket T-48213 runs five nodes in a row: read_ticket, classify, list_charges, decide and draft_reply. LangGraph.js 1.5.1 and its MemorySaver run in this page, and classify, decide and draft_reply ask a scripted model. The browser build of LangGraph.js has no AsyncLocalStorage, so each node passes its config to the model explicitly.
Step 2 of 4: Try it: A checkpoint rail
A checkpoint rail
Three steps: run the graph and read its checkpoints, rewind to step 3 and replay, then edit step 3, fork, and compare both endings.
Mode:RealSimulatedReal: LangGraph.js 1.5.1 runs in this page, with its MemorySaver, getStateHistory, getState, updateState and replay. Simulated: the model's decisions are scripted, and the ticket and charges are fictional.
Step 3 of 4: Check
Check
Put the steps of forking a run from a past checkpoint in order.
Drag the items, or use the arrow buttons, to put them in order.
- Position 1: Run the graph with a checkpointer and a thread_id.
- Position 2: Call invoke(null, config) with the config updateState returned.
- Position 3: Pick the checkpoint to go back to by its checkpoint_id.
- Position 4: List the thread's checkpoints with getStateHistory.
- Position 5: Compare the fork's ending with the first one, still in the history.
- Position 6: Call updateState on that checkpoint's config with the new values.
Step 4 of 4: What you can do now
What you can do now
- Read a thread's checkpoints with getStateHistory, and one of them with getState and its checkpoint_id.
- Replay a run from a past checkpoint, and say which nodes run again.
- Edit a past state with updateState, fork the thread, and compare both endings.
- Choose a durability mode, knowing what each one leaves you to rewind to.