Home > Wiki > Toolchain > Langgraph > Guides > Using Subgraphs

Using Subgraphs

Status: ACTIVE (pulled from docs.langchain.com) Source: https://docs.langchain.com/oss/python/langgraph/use-subgraphs Timestamp: 2026-05-11

A subgraph is a graph used as a node in another graph. Useful for multi-agent systems, reusing node sets, and distributed development.

Two Communication Patterns

Pattern	When to Use	State Schemas
Call subgraph inside a node	Parent and subgraph have different state schemas	Write wrapper function to map state
Add subgraph as a node	Parent and subgraph share state keys	Pass compiled subgraph directly to add_node

Call Subgraph Inside a Node

class SubgraphState(TypedDict):
    bar: str

subgraph = subgraph_builder.compile()

class State(TypedDict):
    foo: str

def call_subgraph(state: State):
    output = subgraph.invoke({"bar": state["foo"]})
    return {"foo": output["bar"]}

builder.add_node("node_1", call_subgraph)

Add Subgraph as a Node (shared state)

class State(TypedDict):
    foo: str

# Subgraph uses same state
subgraph = subgraph_builder.compile()

# Parent adds compiled subgraph directly
builder.add_node("node_1", subgraph)

Subgraph Persistence

Mode	checkpointer=	Behavior
Per-invocation (default)	None	Each call starts fresh, inherits parent's checkpointer for interrupts. No cross-call memory.
Per-thread	True	State accumulates across calls on same thread. Multi-turn memory.
Stateless	False	No checkpointing at all. Plain function call.

Feature Comparison

Feature	Per-invocation	Per-thread	Stateless
Interrupts (HITL)	Yes	Yes	No
Multi-turn memory	No	Yes	No
Multiple calls (different subgraphs)	Yes	Warning	Yes
Multiple calls (same subgraph)	Yes	No	Yes
State inspection	Warning	Yes	No

Per-Thread Example

fruit_agent = create_agent(
    model="gpt-5.4-mini",
    tools=[fruit_info],
    prompt="You are a fruit expert.",
    checkpointer=True,  # Per-thread persistence
)

@tool
def ask_fruit_expert(question: str) -> str:
    response = fruit_agent.invoke(
        {"messages": [{"role": "user", "content": question}]},
    )
    return response["messages"][-1].content

Viewing Subgraph State

subgraph_state = graph.get_state(config, subgraphs=True).tasks[0].state

Streaming Subgraph Outputs

for chunk in graph.stream(
    {"foo": "foo"},
    subgraphs=True,
    stream_mode="updates",
    version="v2",
):
    if chunk["type"] == "updates":
        print(chunk["ns"], chunk["data"])