Struct StateGraph 

pub struct StateGraph {
    pub name: String,
    pub nodes: BTreeMap<String, GraphNode>,
    pub edges: BTreeMap<String, Vec<GraphEdge>>,
    pub entry_point: String,
    pub terminal_nodes: Vec<String>,
}

A directed graph that supports cyclic edges for agent workflows.

Unlike DAGs, StateGraphs can contain cycles, enabling ReAct loops and other iterative patterns to be modeled as explicit graph structures. This makes the state machine visible, inspectable, and interruptable.

Example: ReAct as a StateGraph (diagram):

think_node (LLMInfer) → [HasToolCalls] → tool_node (ToolCall) → think_node (cycle!) think_node (LLMInfer) → [IsFinalAnswer] → end_node

Fields

name: String

The graph name/identifier.

nodes: BTreeMap<String, GraphNode>

All nodes in the graph, keyed by node ID.

BTreeMap (not HashMap) makes iteration order deterministic across runs — important for reproducible rendering, snapshot tests, and stable edge-fan-out ordering.

edges: BTreeMap<String, Vec<GraphEdge>>

All edges in the graph, keyed by source node ID. Each source node can have multiple outgoing edges (with conditions). BTreeMap for deterministic source-node iteration order.

entry_point: String

The entry point node ID (where execution starts).

terminal_nodes: Vec<String>

Terminal node IDs (where execution ends).

Implementations

impl StateGraph

pub fn new(name: impl Into<String>, entry_point: impl Into<String>) -> Self

Create a new StateGraph with a name and entry point.

pub fn add_node(&mut self, node: GraphNode)

Add a node to the graph.

pub fn add_edge(&mut self, edge: GraphEdge)

Add an edge to the graph.

pub fn add_terminal(&mut self, node_id: impl Into<String>)

Add a terminal node (execution ends here).

pub fn get_node(&self, id: &str) -> Option<&GraphNode>

Get a node by ID.

pub fn get_edges_from(&self, node_id: &str) -> Vec<&GraphEdge>

Get outgoing edges from a node.

pub fn node_count(&self) -> usize

Get the number of nodes.

pub fn edge_count(&self) -> usize

Get the number of edges.

pub fn has_cycles(&self) -> bool

Check if the graph contains any cycles.

Unlike DAGs, cycles are ALLOWED in StateGraphs (they’re the mechanism for ReAct loops). This method is for diagnostics, not validation.

Trait Implementations

impl Clone for StateGraph

fn clone(&self) -> Self

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for StateGraph

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

Formats the value using the given formatter.

impl<'de> Deserialize<'de> for StateGraph

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for StateGraph

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.