Struct TimeTravelHandle 

pub struct TimeTravelHandle<'g> { /* private fields */ }

Available on crate feature graph only.

Handle for time-travel operations on a graph thread.

TimeTravelHandle provides methods to navigate, replay, and fork graph execution history. It holds a reference to the compiled graph and uses the associated checkpointer to access historical state.

Create a handle via CompiledGraph::time_travel.

Example

use adk_graph::prelude::*;
use adk_graph::time_travel::TimeTravelHandle;

let graph = StateGraph::new(StateSchema::simple(&["count"]))
    .add_node("increment", increment_fn)
    .add_edge(START, "increment")
    .add_edge("increment", END)
    .compile(Some(checkpointer.clone()));

// Create a time-travel handle
let handle = graph.time_travel("my_thread");

// Inspect execution history
let steps = handle.steps().await?;
println!("Thread has {} steps", steps.len());

// Fork at step 1 to explore an alternative path
handle.fork_at(1, "alternative_thread").await?;

Implementations

impl<'g> TimeTravelHandle<'g>

pub fn new( graph: &'g CompiledGraph, thread_id: &str, checkpointer: Arc<dyn Checkpointer>, ) -> TimeTravelHandle<'g>

Available on crate feature time-travel only.

Create a new TimeTravelHandle for the given thread.

Arguments

• graph - Reference to the compiled graph
• thread_id - The thread whose history to navigate
• checkpointer - The checkpointer for accessing historical state

Example

use adk_graph::time_travel::TimeTravelHandle;

let handle = TimeTravelHandle::new(&graph, "thread_1", checkpointer.clone());

pub async fn steps(&self) -> Result<Vec<StepInfo>, GraphError>

Available on crate feature time-travel only.

List all checkpointed steps for this thread, ordered by step number.

Returns a StepInfo for each checkpoint, providing metadata about the execution state at that point in time.

Errors

Returns GraphError if the checkpointer fails to list checkpoints.

Example

let handle = graph.time_travel("thread_1").unwrap();
let steps = handle.steps().await?;

for step in &steps {
    println!(
        "Step {}: {} (pending: {:?})",
        step.step, step.checkpoint_id, step.pending_nodes
    );
}

pub async fn resume_from( &self, step: usize, config: ExecutionConfig, ) -> Result<HashMap<String, Value>, GraphError>

Available on crate feature time-travel only.

Resume graph execution from the checkpoint at the specified step.

Loads the state from the checkpoint at step and re-executes the graph from that point forward using the provided execution configuration.

Arguments

• step - The step number to resume from
• config - Execution configuration for the resumed run

Errors

Returns GraphError if:

• No checkpoint exists at the specified step
• The graph execution fails after resuming

Example

let handle = graph.time_travel("thread_1").unwrap();

// Resume from step 3
let config = ExecutionConfig::new("thread_1");
let final_state = handle.resume_from(3, config).await?;
println!("Resumed execution produced: {:?}", final_state);

pub async fn fork_at( &self, step: usize, new_thread_id: &str, ) -> Result<(), GraphError>

Available on crate feature time-travel only.

Fork the thread at a specific step into a new independent thread.

Loads the checkpoint at step and saves it under new_thread_id, creating a new execution branch. The original thread remains unchanged.

Arguments

• step - The step number to fork from
• new_thread_id - The identifier for the new forked thread

Errors

Returns GraphError if:

• No checkpoint exists at the specified step
• The checkpointer fails to save the forked checkpoint

Example

let handle = graph.time_travel("thread_1").unwrap();

// Fork at step 2 to explore an alternative execution path
handle.fork_at(2, "thread_1_experiment").await?;

// The original thread_1 is unaffected
let original_steps = handle.steps().await?;

pub async fn state_history( &self, from_step: usize, to_step: Option<usize>, ) -> Result<Vec<(usize, HashMap<String, Value>)>, GraphError>

Available on crate feature time-travel only.

Returns the stored state at each checkpointed step in a range.

This reads checkpoints; it does not execute anything. No node runs, no event is regenerated, and no side effect is repeated — the states returned are the snapshots that were saved when the graph originally ran. Use it to inspect how state evolved, not to reproduce a decision.

To re-run from a point in history, fork that checkpoint with fork_at and invoke the graph on the forked thread.

Arguments

• from_step - First step to include
• to_step - Last step to include, or None for the last checkpointed step

Errors

Returns GraphError when no checkpoint exists at from_step.

Example

let handle = graph.time_travel("thread_1").unwrap();

// The stored state at steps 1 through 4
let transitions = handle.state_history(1, Some(4)).await?;
for (step, state) in &transitions {
    println!("Step {}: {:?}", step, state.keys().collect::<Vec<_>>());
}

// From step 2 to the last checkpoint
let all_remaining = handle.state_history(2, None).await?;