Advanced11 min

Subgraphs

Compose graphs from smaller graphs. Parent-child state communication, shared keys, and encapsulation.

Quick Reference

→Subgraph: a compiled graph added as a node inside a parent graph via add_node()
→State mapping: parent and child can have different state schemas — map keys at the boundary
→Shared keys: keys with the same name and type are automatically passed between parent and child
→Encapsulation: subgraph internals are hidden from the parent — clean separation of concerns
→Nested checkpointing: each subgraph gets its own checkpoint namespace within the parent thread

What Are Subgraphs?

Subgraph = compiled graph as a node

A subgraph is a compiled graph added as a node inside a parent graph. It runs as an isolated unit with its own state, but communicates through mapped keys.

Subgraphs encapsulate reusable logic — state maps at the boundary

Adding a compiled subgraph as a node

The parent graph treats the subgraph as a single opaque node. When execution reaches 'research_agent', the entire child graph runs to completion (START through END), then control returns to the parent. The parent never sees the child's internal nodes -- it only sees the final state output from the child.

State Mapping

Shared keys — same name and type pass automatically

Nested Checkpointing

Each subgraph gets its own checkpoint namespace within the parent thread. The parent's checkpoints and the child's checkpoints are stored separately but linked. This means you can inspect the subgraph's internal state at any point during execution, even though the parent treats it as a single opaque node. The child's checkpoints are namespaced under the parent's checkpoint_id, so there is no collision between different subgraph invocations or between parent and child state.

Sign in to read this article

This is a premium article. Sign in with your Google account to continue.