Struct CompiledGraph 

pub struct CompiledGraph<S: StateSchema> { /* private fields */ }

CompiledGraph - Ready-to-execute graph

Created from StateGraph.compile(). Handles:

• State management and updates
• Edge routing (fixed and conditional)
• Execution with recursion limits
• Checkpointing for persistence

Implementations

impl<S: StateSchema> CompiledGraph<S>

pub fn with_checkpointer<C: Checkpointer<S> + 'static>( self, checkpointer: C, ) -> Self

Attach a checkpointer to this graph for state persistence.

pub fn with_recursion_limit(self, limit: usize) -> Self

Set the maximum recursion depth before execution aborts.

pub fn with_interrupt_before(self, nodes: Vec<String>) -> Self

Set the node names before which execution should be interrupted.

pub fn with_interrupt_after(self, nodes: Vec<String>) -> Self

Set the node names after which execution should be interrupted.

pub fn node_names(&self) -> Vec<String>

Return the names of all static nodes registered in the graph.

pub fn get_edges(&self) -> &[GraphEdge]

Return the graph’s fixed edges.

pub fn entry_point(&self) -> &str

Return the entry point node name.

pub fn recursion_limit(&self) -> usize

Return the configured recursion limit.

pub fn interrupt_before(&self) -> &[String]

Return the nodes that interrupt execution before running.

pub fn interrupt_after(&self) -> &[String]

Return the nodes that interrupt execution after running.

pub async fn last_checkpoint_state(&self) -> Option<(S, usize)>

Get the last checkpoint state (for interrupt recovery), together with the recursion budget consumed up to that checkpoint.

H5: no longer guesses “most recent” from list()’s HashMap order + ids.last(); instead the checkpointer’s last() returns the truly newest checkpoint by (timestamp, seq).

pub async fn get_state_history(&self) -> GraphResult<Vec<CheckpointInfo<S>>>

State history: every step’s checkpoint snapshot, oldest first. This is the “agent 当时为什么这么决策” inspection primitive — each snapshot exposes the state, ordering keys, and recursion budget at that point in the run.

pub async fn fork_from( &self, checkpoint_id: &str, continue_at_node: impl Into<String>, override_state: Option<S>, ) -> GraphResult<GraphInvocation<S>>

Time-travel: fork a fresh execution timeline from an old checkpoint.

• checkpoint_id: the snapshot to branch from (see get_state_history).
• continue_at_node: the node the forked run resumes at — normally the next_node recorded in the history step immediately after that snapshot.
• override_state: optionally replace the snapshot state with new input (“改输入、从那条线分叉重跑”) before running forward.

The fork is seeded as a NEW checkpoint so the original history is untouched (its own lineage), continues counting against the snapshot’s recursion budget, and — because it starts at continue_at_node and only runs FORWARD via invoke_from_node — never replays side effects emitted before the fork point.

pub async fn create_resume_execution( &self, interrupted_node: &str, ) -> Option<GraphExecution<S>>

Create a resume execution context (from the last checkpoint) interrupted_node may be “node_name” or “after_node_name”

pub async fn resume_with_value( &self, interrupted_node: &str, value: Value, ) -> GraphResult<GraphInvocation<S>>

Resume from a runtime interrupt at interrupted_node, feeding the human’s value back into that node.

The interrupted node is re-entered (LangGraph-style) and the value is injected into its NodeConfig.metadata under crate::node::INTERRUPT_RESUME_KEY, so an crate::node::InterruptibleNode closure can branch on Some(decision) to continue past the suspension without re-running side effects. Requires a checkpointer with the checkpoint that was persisted when the interrupt fired.

pub fn submit_task( &self, description: impl Into<String>, ) -> Result<(), GraphError>

Submit a new task for dynamic planning mid-execution.

Returns an error instead of silently dropping the task when the inbox lock is contended (previously a failed try_lock swallowed it, so a task could vanish without any signal).

pub async fn inject_node( &self, name: &str, node: Arc<dyn GraphNode<S>>, ) -> GraphResult<()>

Inject a runtime node directly

pub async fn inject_edge(&self, source: &str, target: &str) -> GraphResult<()>

Inject a runtime edge directly

pub async fn inject_subgraph<SubS: StateSchema + 'static>( &self, name: &str, subgraph: CompiledGraph<SubS>, input_mapper: impl Fn(&S) -> SubS + Send + Sync + 'static, output_mapper: impl Fn(&SubS, &mut S) + Send + Sync + 'static, ) -> GraphResult<()>

Inject a subgraph as a runtime node

impl<S: StateSchema> CompiledGraph<S>

pub async fn invoke(&self, input: S) -> GraphResult<GraphInvocation<S>>

Run the graph from its entry point with the given input state.

pub async fn invoke_with_execution( &self, execution: GraphExecution<S>, ) -> GraphResult<GraphInvocation<S>>

Continue execution from a saved GraphExecution (e.g. after an interrupt).

pub async fn resume( &self, execution: GraphExecution<S>, ) -> GraphResult<GraphInvocation<S>>

Resume execution from the given execution context.

pub async fn invoke_from_node( &self, start_node: String, input: S, ) -> GraphResult<GraphInvocation<S>>

Run the graph starting from the given node with the given input state.

impl<S: StateSchema> CompiledGraph<S>

pub async fn invoke_parallel( &self, input: S, ) -> GraphResult<ParallelInvocation<S>>

Run the graph while capturing parallel fan-out branches into a ParallelInvocation.

pub async fn invoke_dynamic( &self, input: S, planner: &dyn DynamicPlanner<S>, ) -> GraphResult<GraphInvocation<S>>

Execute the graph with dynamic task injection support.

After each node completes, checks the task_inbox for newly submitted tasks. If tasks are found, uses the provided planner to convert them into new nodes/edges and injects them into the runtime registries before continuing.

impl<S: StateSchema + Send + Sync + 'static> CompiledGraph<S>

pub fn stream( &self, input: S, ) -> Pin<Box<dyn Stream<Item = Result<StreamEvent<S>, GraphError>> + Send>>

Stream graph execution as a true async stream.

Each StreamEvent is emitted as soon as it occurs (node entry, node completion, state update), enabling real-time consumption.

This is the preferred streaming API. For the old all-at-once behavior, use stream_collected().

pub async fn stream_collected( &self, input: S, ) -> GraphResult<Vec<StreamEvent<S>>>

Collect all stream events into a Vec (backward-compatible API).

This is the old stream() behavior. Prefer stream() for real-time consumption.

impl<S: StateSchema> CompiledGraph<S>

pub fn validate(&self) -> GraphResult<()>

Validate the graph structure: node references, duplicate edges, unreachable nodes, and cycles with no path to END.

impl<S: StateSchema> CompiledGraph<S>

pub fn visualize_ascii(&self) -> String

Visualize the graph structure in ASCII format

pub fn visualize_mermaid(&self) -> String

Visualize the graph structure in Mermaid format

pub fn visualize_json(&self) -> Value

Visualize the graph structure as JSON

pub fn to_definition(&self) -> GraphDefinition

Convert the graph into a portable GraphDefinition.

Trait Implementations

impl<S: Clone + StateSchema> Clone for CompiledGraph<S>

fn clone(&self) -> CompiledGraph<S>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S: StateSchema> Debug for CompiledGraph<S>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.