Graph Workflows

Build stateful workflows as graphs — conditional routing, fan-out/fan-in, checkpointing, and resumable pipelines.

📄️ Graph Workflows Overview

Graph Workflows let you define async pipelines as directed graphs. Nodes are async functions; edges wire them together. The engine executes nodes wave by wave — parallel nodes run concurrently via asyncio.gather(). Cycles are supported for iterative workflows, and state can be checkpointed for resumability.

📄️ StateGraph

StateGraph is the fluent builder used to define your graph before compiling it.

📄️ Nodes

A node is any callable that takes the current graph state and returns a partial state to be merged in.

📄️ Edges

Edges connect nodes and determine the execution order.

📄️ CompiledGraph

CompiledGraph is the runnable object returned by StateGraph.compile(). It exposes three execution modes and a Mermaid diagram helper.

📄️ Cycles

By default, StateGraph.compile() raises GraphConfigError if it detects a cycle in static edges. This protects against accidental infinite loops.

📄️ Checkpointing

Checkpointing lets you persist graph state after each execution wave. This enables resuming interrupted runs and inspecting intermediate state.

📄️ Mermaid Export

CompiledGraph.get_mermaid() returns a Mermaid flowchart string for your graph. Use it to visualize pipelines in Markdown, Notion, GitHub, or Jupyter.