How do you reuse subgraphs or compose graphs for larger systems?

What you need to know

Two ways to attach

1# 1. Shared keys: add the compiled subgraph as a node2parent.add_node("assessment", assessment_graph)34# 2. Different schema: wrap it in a node that translates5def research(state: ParentState) -> dict:6    out = research_graph.invoke({"query": state["question"], "results": []})7    return {"documents": out["results"]}89parent.add_node("research", research)

Persistence and interrupts

• Compile only the parent with a checkpointer. The subgraph uses the parent's automatically, even when it is called inside a wrapper node.
• An interrupt() inside a subgraph pauses the whole run; Command(resume=...) on the parent resumes it.
• Compile a subgraph with checkpointer=True only when it must keep its own memory across calls, for example an agent that remembers its own previous turns.

Seeing inside

graph.stream(inputs, config, stream_mode="updates", subgraphs=True) yields (namespace, update) pairs. The namespace, such as ("assessment:<task id>",), tells you which subgraph produced the event. Without subgraphs=True the whole subgraph looks like one step.

A reducer trap

If parent and subgraph share a key with an appending reducer like operator.add, the subgraph returns its whole list, and the parent's reducer appends it again, so items are duplicated. Use add_messages (which de-duplicates by id), a separate output key, or an output_schema on the subgraph.

A real-life example

A general insurer builds a claims system from three subgraphs owned by three teams: intake (document OCR and field extraction), assessment (fraud scoring and an adjuster approval with interrupt()) and settlement (payout and letters). The parent graph is only intake → assessment → settlement, compiled with a Postgres checkpointer. Each team tests its subgraph on its own with fake inputs. When a claim above Rs 2 lakh pauses inside assessment for three days, the parent run is paused too, and resuming it with the adjuster's decision continues straight into settlement.

Follow-up questions to expect

• "Why not one big graph?" — Ownership and testing. Each subgraph has a narrow contract and its own tests, and a change in one stage cannot break another's internal wiring.
• "Can a node inside a subgraph jump to a node in the parent?" — Yes, by returning Command(goto="node_name", graph=Command.PARENT). This is how agent handoffs work.
• "Can you deploy a subgraph separately?" — You can deploy it as its own graph on Agent Server and call it remotely, at the cost of a network hop.