Graph Runtime

Graph Runtime

The graph runtime is the deterministic execution layer underneath agent workflows. It owns state transitions, routing, checkpoints, interrupts, and topology. Model and tool calls live in the harness, which graph nodes can invoke when needed.

Core Model

flowchart TD
    Start((START)) --> A[Node A]
    A -->|route x| B[Node B]
    A -->|route y| C[Node C]
    B --> D[Reducer / Next State]
    C --> D
    D --> End((END))

Loading

A compiled graph has:

• typed state
• typed updates
• reducers that merge updates into state
• named nodes
• static edges
• conditional edges
• virtual START and END
• runtime context for node execution

Building A Graph

Use GraphBuilder::<State, Update>::overwrite() when each node returns the full next state as its update:

let graph = GraphBuilder::<AgentState, AgentState>::overwrite()
    .add_node("agent", agent_node)
    .add_node("tool", tool_node)
    .set_entry("agent")
    .add_edge("tool", "agent")
    .compile()?;

Use a custom reducer when nodes produce partial updates that need to be merged into state.

Routing

Static edges always route from one node to another. Conditional edges compute a route name from the current state and map that route to a destination:

.add_conditional_edges(
    "agent",
    |state: &AgentState| {
        if state.needs_tool { "tool".to_string() } else { "done".to_string() }
    },
    [("tool", "tool"), ("done", END)],
)

This keeps nondeterministic work inside nodes while routing remains explicit and inspectable.

Node Results

Nodes return NodeResult values. The common case is an update:

Ok(NodeResult::Update(next_state))

Commands, interrupts, and other graph-control results let nodes participate in more advanced durable workflows without turning the graph into an implicit loop.

Harness Boundary

Graph nodes can call an AgentHarness, but the graph does not know whether the harness uses OpenAI, Anthropic, Ollama, a mock model, a tool loop, or a sub-agent. This keeps graph execution durable and provider-neutral:

flowchart LR
    GraphNode[Graph Node] --> Harness[AgentHarness]
    Harness --> Model[ChatModel]
    Harness --> Tool[ToolRegistry]
    Harness --> Events[EventSink]

Loading

When To Use Graphs

Use the graph runtime when the workflow needs:

• explicit state transitions
• branch routing
• loops with guardrails
• checkpointing or resume
• inspectable topology
• deterministic tests around model calls
• sub-agent orchestration
• human review and interrupt points

For a single model call, use the harness directly. For agent products with stateful workflows, use a graph and call the harness from graph nodes.