6.7

Subgraphs and multi-agent patterns

A subgraph shares the keys of its parent and runs in its own namespace, and its whole output passes through the parent reducers, which can add old entries twice.

You build one graph that checks a draft and add it as a node of a larger graph. The run works, but the log of steps in the parent holds the first entry twice. Nothing in the subgraph wrote it twice. The parent reducer added the whole output of the subgraph to its own list.

When you finish this section, you can add a graph or an agent as a node and read the namespace of its chunks. You can also pause inside it and choose a pattern for several agents.

A graph as a node

Subgraph: a compiled graph used as a node of another graph. When the two state schemas share keys, the subgraph reads and writes the keys of the parent.

The kit inner graph upper-cases a text and asks if the result is fine. The outer graph adds !, runs the inner graph, and finishes. Both use the schema Inner, whose steps key has the reducer operator.add:

pythonthe inner graph and the outer graphFull log
    inner = StateGraph(Inner)
    inner.add_node("shout", shout)
    inner.add_node("ask_ok", ask_ok)
    inner.add_edge(START, "shout")
    inner.add_edge("shout", "ask_ok")
    inner_app = inner.compile()

    outer = StateGraph(Inner)
    outer.add_node("prepare", lambda s: {"text": s["text"] + "!", "steps": ["outer.prepare"]})
    outer.add_node("inner", inner_app)
    outer.add_node("finish", lambda s: {"steps": ["outer.finish"]})
    outer.add_edge(START, "prepare")
    outer.add_edge("prepare", "inner")
    outer.add_edge("inner", "finish")
    app = outer.compile(checkpointer=InMemorySaver())
The schema and the node functions of the inner graph are cut.

The inner graph has no checkpointer of its own. Only the outer graph gets InMemorySaver. get_graph(xray=True) draws the inner nodes inside a box named inner, with ids such as inner:shout.

Figure 6.10 draws the parent graph both ways, from the Mermaid text of each call.

Fig. 6.10one parent graph, with and without xraycomparison
One parent graph, drawn with and without xray The parent graph of the subgraph example, drawn twice from draw_mermaid output. get_graph() has 5 nodes and shows the subgraph as one node named inner. get_graph(xray=True) has 6 nodes. It draws the subgraph as a box named inner around its nodes inner:shout and inner:ask_ok, and the parent edges go to inner:shout and leave from inner:ask_ok. GET_GRAPH() GET_GRAPH(XRAY=TRUE) 5 nodes, inner is one node 6 nodes, the subgraph opened __start__ prepare inner finish __end__ subgraph inner __start__ prepare finish __end__ ask_ok shout plain edge conditional edge, chosen at run time
get_graph() shows the subgraph as one node named inner, and get_graph(xray=True) opens it into shout and ask_ok inside a box. Read each column from the top. The dashed box on the right is the subgraph. The parent edges reach its first node and leave its last node.

Namespaces

Namespace: the path of a subgraph run inside its parent, such as inner:<task id>. Stream chunks, checkpoints, and state carry it.

stream(..., subgraphs=True) yields pairs of a namespace and a chunk. The root graph has the empty namespace. The interrupt of ask_ok came twice, once from the subgraph and once from the root:

jsonchunks with their namespacesFull log
  "namespace": [],
  "chunk": {
    "prepare": {
…
  "namespace": [
    "inner:<uuid-1>"
  ],
  "chunk": {
    "shout": {
…
  "namespace": [
    "inner:<uuid-1>"
  ],
  "chunk": {
    "__interrupt__": [
…
  "namespace": [],
  "chunk": {
    "__interrupt__": [
The four chunks of the first run, cut to the namespace and the first key.

While the run waits, get_state(config, subgraphs=True) shows both levels. The parent waits on the node inner, and the subgraph waits on ask_ok. The state of the task holds the values inside the subgraph. A resume with "yes" on the parent thread reached ask_ok and finished both graphs.

The output passes through the parent reducer

This is the final state after the resume:

jsonthe final state of the outer graphFull log
{
  "text": "HELLO!",
  "steps": [
    "outer.prepare",
    "outer.prepare",
    "inner.shout",
    "inner.ask_ok=yes",
    "outer.finish"
  ]
}

outer.prepare appears twice, and no node wrote it twice. The subgraph started with steps set to ["outer.prepare"] and added its two entries. It returned all three as its output. The parent applied that output as one update, and operator.add joined it to the list that already held outer.prepare. Figure 6.11 follows the list through the run.

Fig. 6.11the steps list through a subgraphflow
The steps list through a subgraph Five rows from top to bottom, each a node and the steps list after it. prepare writes outer.prepare. Inside the namespace of the subgraph inner, shout adds inner.shout and ask_ok adds inner.ask_ok=yes, so the subgraph returns three entries. The parent applies that output with operator.add to its list that already holds outer.prepare, so outer.prepare appears twice. finish adds outer.finish, and the final list has five entries. NODE STEPS AFTER THE NODE namespace inner:<uuid-1> prepare outer outer.prepare shout inner outer.prepare inner.shout ask_ok inner outer.prepare inner.shout inner.ask_ok=yes operator.add parent update outer.prepare + outer.prepare inner.shout inner.ask_ok=yes finish outer outer.prepare outer.prepare inner.shout inner.ask_ok=yes outer.finish The rose entry is the copy that operator.add in the parent added to its own list.
The subgraph returns the whole steps list it was given, and operator.add in the parent joins it again, so outer.prepare appears twice. Read from left to right. Each box shows steps after one node, and the dashed frame is the subgraph namespace. The rose entry is the copy that the parent reducer added.

Any reducer that only appends adds the copy. add_messages replaces a message that has the same id, as section 6.1 showed, so its copies replace the originals.

Two changes avoid the copy. Call the subgraph inside a node and return only its new entries, or give the subgraph a schema without the shared key. The subgraphs page describes the first as the way for schemas that share no keys. The kit does not run either change, or a subgraph with add_messages, yet. Captures of them come in the next edition, with the other open items of section 8.8.

Persistence of a subgraph

compile of a subgraph takes checkpointer=None, True, or False. None, the default, gives each call of the subgraph its own fresh state, and it uses the checkpointer of the parent for interrupts. True keeps the state of the subgraph across calls on the thread, and False turns checkpoints off. The kit used None, and the interrupt inside the subgraph paused and resumed through the parent. The kit does not run True or False yet. They come in the next edition, with the other open items of section 8.8.

An agent as a node

A create_agent graph is a compiled graph, so it can be a node. The kit adds an agent named adder to a graph with MessagesState. The stream with subgraphs=True showed the three node runs of the agent in its own namespace, then one chunk for adder in the root:

jsonan agent in a parent graphFull log
{
  "namespace": [
    "adder:<uuid-1>"
  ],
  "nodes": [
    "model"
  ]
}
…
{
  "namespace": [],
  "nodes": [
    "adder"
  ]
}
The first and the last of four chunks.

The approval lab of section 6.5 also ran a Qwen3 4B agent in per-call mode as a subgraph, 3 runs. Two calls that needed approval were answered one at a time, and each tool ran once.

Patterns for several agents

The multi-agent page of the docs names five patterns: subagents, handoffs, skills, a router, and a custom workflow. It also says that one agent with the right tools and prompt often does as well as several agents. The subagents page says that the langgraph-supervisor package is no longer maintained.

Subagent: an agent that another agent calls as a tool. The caller sees only the last message of the subagent.

Deep Agents gives every agent a task tool that starts a subagent. In the kit run, the main agent called task with a description that it wrote, and the subagent answered in one sentence:

jsonthe task call and its answerFull log
        "name": "task",
        "args": {
          "description": "Verify that 2 + 3 equals 5 by performing a mathematical calculation and confirming the result.",
          "subagent_type": "general-purpose"
        },
        "id": "<uuid-11>",
        "type": "tool_call"
…
    "type": "ToolMessage",
    "content": "2 + 3 equals 5. This is a basic arithmetic fact and can be verified through direct calculation: 2 plus 3 is indeed 5.",
    "name": "task",
The fourth model call of the main agent and the ToolMessage that answered it.

The model call of the subagent was the fifth of six calls. It got two messages, its own system prompt and the description, and its tools had no task. The main agent saw one ToolMessage with the answer of the subagent. So a subagent keeps its work out of the context of its caller. Part 7 covers Deep Agents.

Five patterns on one task suite

We measured the five patterns on the 30-task subset of section 1.2, with langchain 1.5.0 and deepagents 0.7.38. Five domain agents split the tools of the suite: shop, orders_db, docs, files, and notes. The patterns were: Raw runs

  • single: one agent with all tools and the five domain guides in its prompt.
  • subagents: a Deep Agents coordinator that calls each domain agent through task.
  • handoffs: the domain agents as graph nodes, with a transfer_to_<agent> tool that returns Command(goto=..., graph=Command.PARENT).
  • skills: one agent with a load_skill tool that adds a domain guide to its prompt.
  • router: a classifier that sends parallel requests to the domain agents, then a synthesizer agent.

Claude Haiku 5.5 ran through the API from the Mac. Qwen3 14B ran on Ollama 0.31.1 on the same Mac, at temperature 0 and seed 42. Each cell is one run for each of 30 tasks.

The Mac was shared. The load average was between 2.7 and 9.1 in the six samples we logged. The Ollama server was busy with other jobs. We stopped a run of gpt-oss 20B before its first task, so it has no row.

PatternHaiku passedHaiku callsHaiku prompt tokensHaiku dollars14B passed14B calls14B prompt tokens
single30160521,013$0.013022140251,620
subagents302711,247,292$0.038017164425,288
handoffs30187373,993$0.013419151163,200
skills30194314,352$0.012915159151,631
router25226317,648$0.023718187105,174

On Haiku, four patterns passed 30 of 30, and the router passed 25. The router lost 3 chain tasks and 1 each in sql and retrieval, all with the category wrong_final_state. The cost differs more than the score. The subagent pattern used 2.4 times the prompt tokens of the single agent and cost 2.9 times the dollars. The handoffs and skills patterns cost the same as the single agent. Figure 6.12 shows one chain task in each pattern.

Fig. 6.12one chain task in each of five patterns on Haikutimeline
One recorded run of chain01 through each pattern Five swim-lane panels, one per pattern, for task chain01 on Claude Haiku 5.5, on a shared time axis of 10 seconds. Each lane is one agent, each plum box is one model call, and each triangle is one tool call. single agent: 5 model calls, 15764 input tokens, 5.4 s, pass; subagents (Deep Agents): 7 model calls, 32426 input tokens, 9.7 s, pass; agent transfers: 5 model calls, 10526 input tokens, 6.4 s, pass; skills: 6 model calls, 10627 input tokens, 6.1 s, pass; router: 6 model calls, 9577 input tokens, 7.0 s, fail. single agent 5 model calls, 15.8k tokens in, pass agent 1 2 3 4 5 subagents (Deep Agents) 7 model calls, 32.4k tokens in, pass coordinator shop 1 2 3 4 5 6 7 agent transfers 5 model calls, 10.5k tokens in, pass shop 1 2 3 4 5 skills 6 model calls, 10.6k tokens in, pass agent 1 2 3 4 5 6 router 6 model calls, 9.6k tokens in, fail router shop 1 2 3 4 5 6 0 s 2 s 4 s 6 s 8 s 10 s model call, numbered in order domain tool task, transfer, skill, submit
On one chain task the five patterns used 5 to 7 model calls, and the subagent pattern ran two agents one after the other. Each box is one model call, numbered in order, in the lane of the agent that made it. Triangles mark tool calls.

A task with three user turns shows the cost of a pattern more clearly. On multi07 every pattern passed. The single agent made 9 model calls and read 30.2k prompt tokens. The subagent pattern made 16 calls and read 72.6k, and the router made 18 calls. Figure 6.13 draws the five runs, with the start of each user turn.

Fig. 6.13a three-turn task in each of five patterns on Haikutimeline
One recorded run of multi07 through each pattern Five swim-lane panels, one per pattern, for task multi07 on Claude Haiku 5.5, on a shared time axis of 25 seconds. Each lane is one agent, each plum box is one model call, and each triangle is one tool call. single agent: 9 model calls, 30163 input tokens, 10.2 s, pass; subagents (Deep Agents): 16 model calls, 72604 input tokens, 19.1 s, pass; agent transfers: 12 model calls, 26932 input tokens, 11.5 s, pass; skills: 13 model calls, 26216 input tokens, 13.2 s, pass; router: 18 model calls, 23455 input tokens, 23.1 s, pass. single agent 9 model calls, 30.2k tokens in, pass agent 1 2 3 4 5 6 7 8 9 subagents (Deep Agents) 16 model calls, 72.6k tokens in, pass coordinator notes shop 1 2 3 4 5 6 7 8 9 11 12 agent transfers 12 model calls, 26.9k tokens in, pass shop notes 1 3 4 5 6 7 8 9 skills 13 model calls, 26.2k tokens in, pass agent 1 2 3 4 5 6 7 8 9 router 18 model calls, 23.5k tokens in, pass router notes shop synth 1 2 3 4 5 6 7 8 9 11 12 13 15 16 17 18 0 s 5 s 10 s 15 s 20 s 25 s model call, numbered in order domain tool task, transfer, skill, submit start of the next user turn
On a three-turn task the single agent made 9 model calls, and the other patterns made 12 to 18. Each box is one model call, numbered in order, in the lane of the agent that made it. Dashed lines mark the start of a user turn.

On Qwen3 14B the picture is different. The single agent passed 22 of 30, and no pattern did better. Subagents passed 17 and skills passed 15. Both passed 0 of 6 file tasks and 0 of 6 multiturn tasks. Subagents failed 13 tasks and skills failed 15, most with wrong_final_state. The intervals of all five cells overlap, so only those zeros are clear.

Each 14B cell is one run per task on a loaded shared Mac, so a second run can move single tasks.

The 14B wall time per task ran from 91 s to 315 s, and it says more about the load than about the pattern.

LangChain (Python): langchain, langchain-core, langgraph, deepagents, langsmith 1.5.0 · c2f4036 · 2026-11-11 · Edition 2026.11