Time Travel: Debugging and Forking Graph States

Because LangGraph records a snapshot of the graph's state at every step, your application can traverse backward in time. Time Travel allows you to inspect past execution values, update historical data, and fork new execution branches from any historical checkpoint.

1. What is Forking?

Forking is the process of selecting a past checkpoint, updating its state values, and calling invoke() again. The graph will resume execution from that point in time, branching off onto a new path without deleting the original execution timeline.

graph TD
    A[Node 1: Init] --> B[Node 2: RunTool]
    B --> C[Node 3: FinalAnswer]
    
    subgraph Time Travel Fork
        B -->|Fork with updated state| D[Node 3: AlternateAnswer]
    end

2. Replaying and Forking in Node.js

Let us load a past checkpoint, update its parameters, and trigger a fork:

// src/services/timeTravel.ts
import { persistentApp } from "./persistentGraph";

const threadConfig = { configurable: { thread_id: "order_99" } };

export async function travelInTimeAndFork() {
  // 1. Retrieve all history checkpoints
  const historyRecords = [];
  for await (const stateRecord of persistentApp.getStateHistory(threadConfig)) {
    historyRecords.push(stateRecord);
  }

  // Pick a target checkpoint from the past (e.g. index 2)
  const targetRecord = historyRecords[2];
  if (!targetRecord) return;

  const targetCheckpointId = targetRecord.config.configurable.checkpoint_id;
  console.log("Traveling back to checkpoint:", targetCheckpointId);

  // 2. Fork by updating the state targeting that specific checkpoint ID
  await persistentApp.updateState(
    {
      configurable: {
        thread_id: "order_99",
        checkpoint_id: targetCheckpointId, // Target checkpoint ID
      },
    },
    {
      status: "manual-override-applied", // Overwrite value
    }
  );

  // 3. Invoke the graph to continue execution along the new fork branch
  const finalForkResult = await persistentApp.invoke(null, {
    configurable: {
      thread_id: "order_99",
      // Do not specify checkpoint_id here; LangGraph will automatically use the latest fork tip
    },
  });

  console.log("Fork branch output:", finalForkResult);
  return finalForkResult;
}

3. Practical Use Cases

• Customer Care Overrides: If an agent recommends an incorrect shipping fee, a support agent can roll back the transaction state, manually correct the shipping cost, and resume the checkout process.
• Testing and Debugging: Rather than running a 5-step agent loop from scratch to test Step 5, jump directly back to the Step 4 checkpoint, update the prompt parameter, and run Step 5 again.
• History Rewinding: Allow users to click "Undo" on an action, restoring the agent state to the previous step checkpoint.