Compose LangGraph 1.0 subgraphs correctly — shared state key propagation,
Send / Command(graph=...) dispatch, callback scoping, per-subgraph recursion
budgets, and testing each subgraph in isolation. Use when building a planner +
executor, a nested agent team, or a reusable subgraph library. Trigger with
"langgraph subgraph", "langgraph composition", "langgraph send",
"nested agents", "langgraph state propagation", "Command(graph=...)",
"langgraph subgraph callbacks".
Instrucciones de origen · Vista previa de solo lectura
name
langchain-langgraph-subgraphs
description
Compose LangGraph 1.0 subgraphs correctly — shared state key propagation,
Send / Command(graph=...) dispatch, callback scoping, per-subgraph recursion
budgets, and testing each subgraph in isolation. Use when building a planner +
executor, a nested agent team, or a reusable subgraph library. Trigger with
"langgraph subgraph", "langgraph composition", "langgraph send",
"nested agents", "langgraph state propagation", "Command(graph=...)",
"langgraph subgraph callbacks".
Designed for Claude Code, also compatible with Codex
LangGraph Subgraphs and Composition (Python)
Overview
A parent StateGraph invokes a compiled child subgraph as a node. The child
node writes state["answer"] = "42" and returns. The parent's next node reads
state["answer"] and gets None. No error, no warning, no deprecation notice —
just a silent None that surfaces as a wrong answer three nodes later when the
router picks the "couldn't find it" branch.
The cause is pain-catalog entry P21: LangGraph subgraphs run on an
independent state schema. Only keys declared in both the parent's
TypedDict and the child's TypedDict propagate across the subgraph boundary.
answer existed in the child schema but not the parent schema, so it was
discarded on return. The fix is to declare answer in both schemas (with
matching reducers, if the field is a list) or to use explicit
Command(graph=ParentGraph, update={"answer": "42"}) to bubble it up.
The second silent failure waits one step further. Attach a tracing callback to
the parent runnable via parent.with_config(callbacks=[tracer]) and invoke.
The tracer fires on parent nodes and never on child tool calls. This is
pain-catalog entry P28: LangGraph creates a fresh runtime per subgraph, so
callbacks bound at definition time do not inherit. The fix is to pass
callbacks at invocation time via config["callbacks"], which does propagate.
This skill walks through the shared-state contract, three dispatch patterns
(compiled subgraph as a node, Send fan-out, Command(graph=Parent) bubble-up),
callback scoping, per-subgraph recursion_limit budgets, and a testing pattern
that exercises every subgraph in isolation before composition. Pin:
langgraph 1.0.x, langchain-core 1.0.x. Pain-catalog anchors: P21, P28,
with supporting references to P18 (reducers), P19 (stream modes on nested
graphs), and P55 (recursion budget).
A planner-executor is typically 1 parent + 2-4 subgraphs; a hierarchical
agent team with a supervisor and N specialists is 1 parent + N subgraphs.
Each subgraph has its own independent recursion_limit (default 25) — a parent
at step 20 can still invoke a child that runs 25 of its own steps.
Test tooling: pytest, langchain_core.language_models.fake_chat_models.FakeListChatModel
Instructions
Step 1 — Declare the shared-state contract explicitly
The single most important decision when composing subgraphs is: which keys
cross the boundary? Every key that must survive the call must appear in
both TypedDict schemas with compatible types and reducers.
from typing import Annotated, TypedDict
from langchain_core.messages import AnyMessage
from langgraph.graph.message import add_messages
# Keys both schemas declare -> these propagate# Keys only in parent -> invisible to child# Keys only in child -> discarded on return (P21)classParentState(TypedDict):
# Shared with every subgraph
messages: Annotated[list[AnyMessage], add_messages] # P18 reducer required
session_id: str# Parent-only coordination fields
plan: list[str]
current_step: intclassExecutorState(TypedDict):
# Shared with parent — must match reducer exactly (P18)
messages: Annotated[list[AnyMessage], add_messages]
session_id: str# Executor-only scratch — parent never sees these
tool_result: dict | None
retries: int
If messages on the child used a different reducer (or no reducer), list
updates would silently replace instead of append on one side of the boundary
(P18). The messages + session_id pair is the propagation contract. Everything
else is private to its owner.
See State Contract for the full
state-propagation matrix and the "subset rule" for schema inheritance.
Step 2 — Pick the dispatch pattern
Three ways a parent can invoke a subgraph, and each solves a different problem.
A. Compiled subgraph as a node — Simplest. Subgraph runs, returns a state
update, parent continues.
Only messages and session_id cross the boundary in either direction (from
Step 1). tool_result stays inside the child; plan stays inside the parent.
B. Send(graph, state) for fan-out — One parent step spawns N parallel
subgraph invocations, each with a different slice of state.
from langgraph.types import Send
defdispatch_specialists(state: ParentState) -> list[Send]:
return [
Send("specialist_graph", {"messages": state["messages"],
"session_id": state["session_id"],
"topic": topic})
for topic in state["plan"]
]
Use Send when the number of subgraph calls depends on runtime state.
Reducers on shared keys merge the parallel results.
C. Command(graph=ParentGraph, update=...) to bubble up — A subgraph node
jumps control back to the parent with an explicit state update, skipping the
rest of the subgraph.
from langgraph.types import Command
defspecialist_early_exit(state: ExecutorState) -> Command:
if state.get("tool_result") and state["tool_result"].get("done"):
return Command(
graph=Command.PARENT,
update={"messages": [AIMessage("done")]},
goto="finalize",
)
return {"retries": state.get("retries", 0) + 1}
Command(graph=Command.PARENT) is the explicit opposite of P21 — it forces a
field up to the parent scope regardless of schema overlap.
See Dispatch Patterns for the full decision
tree (inline function vs subgraph-as-node vs Send vs Command vs separate
service) and a sizing guide.
Step 3 — Scope callbacks at invocation time, not definition time
# WRONG — callbacks bind at definition time and do NOT propagate to subgraphs (P28)
traced_parent = parent_graph.with_config(callbacks=[tracer])
traced_parent.invoke({"messages": [HumanMessage("...")], "session_id": "s1"})
# tracer fires on parent nodes only. Child tool calls are invisible.# RIGHT — callbacks pass via config at invocation time, propagating into every subgraph
parent_graph.invoke(
{"messages": [HumanMessage("...")], "session_id": "s1"},
config={
"configurable": {"thread_id": "s1"},
"callbacks": [tracer],
},
)
# tracer fires on parent nodes AND every child tool, LLM, and chain event.
Every production invocation path — API handler, batch worker, test harness —
should pass callbacks via config["callbacks"]. Lint for
with_config(callbacks= on compiled graphs in CI and flag it.
See Callback Scoping for the debugging
playbook when a callback "should be firing but isn't."
Step 4 — Budget recursion per subgraph
LangGraph's recursion_limit (default 25 supersteps) is per-graph, not
global. A parent graph at superstep 20 invoking a subgraph resets the counter
inside that subgraph to zero. Pros: one runaway subgraph cannot starve the
parent. Cons: adding subgraphs does not reduce your global budget — a poorly
bounded specialist can still rack up 25 of its own steps while the parent
thinks it spent only one.
# Parent gets 10 steps of its own planning.# Each executor call gets its own 15-step budget, independent of the parent's 10.
parent_graph.invoke(
initial_state,
config={
"configurable": {"thread_id": "s1"},
"recursion_limit": 10,
},
)
executor_graph.invoke(
sub_state,
config={"recursion_limit": 15},
)
For a parent that dispatches N specialists via Send, worst-case step count
is parent_limit + N * specialist_limit. Monitor the actual distribution with
a callback on on_chain_start / on_chain_end at each graph boundary —
GraphRecursionError with no obvious loop is P55 in the pain catalog, and
subgraph composition is the most common cause.
Step 5 — Test every subgraph in isolation before composing
A subgraph that works alone and breaks in composition is almost always a
state-contract bug (Step 1) or a callback-scoping bug (Step 3). Catch both by
unit-testing each subgraph with a FakeListChatModel and an in-memory
checkpointer before wiring it into a parent.
from langchain_core.language_models.fake_chat_models import FakeListChatModel
from langgraph.checkpoint.memory import MemorySaver
deftest_executor_subgraph_standalone():
fake = FakeListChatModel(responses=['{"done": true, "result": 42}'])
graph = build_executor(llm=fake).compile(checkpointer=MemorySaver())
out = graph.invoke(
{"messages": [HumanMessage("do the thing")],
"session_id": "test",
"tool_result": None,
"retries": 0},
config={"configurable": {"thread_id": "test"},
"recursion_limit": 5},
)
# Assert the shared-contract fields (Step 1) are present on returnassert"messages"in out
assert out["session_id"] == "test"# Assert child-only field is scoped correctlyassert out["tool_result"] == {"done": True, "result": 42}
See Testing Subgraphs for the full isolation
pattern — fixtures, state-shape assertions per node, and how to assert callback
propagation with a capturing handler.
Step 6 — Version subgraphs independently of the parent
A reusable subgraph should ship with its own semantic version and a pinned
schema contract. Breaking either the shared-state contract (Step 1) or the
dispatch signature (Step 2) is a major-version bump; adding a new private
child-only field is a patch.
Parents pin executor_subgraph>=1.2.0,<2.0.0. A v2.0.0 that renames session_id
forces every parent to re-sync its TypedDict. This is how you catch P21 at
pip install time instead of at runtime.
Output
ParentState + per-subgraph child TypedDicts with the shared-key contract
declared explicitly; every shared list field has a matching reducer
Dispatch pattern chosen per subgraph (node vs Send vs Command(graph=PARENT))
with rationale recorded in code comments
Every invocation path (API, batch, test) passes callbacks via
config["callbacks"] so observability propagates into every subgraph
recursion_limit set explicitly on parent and each subgraph, with the
worst-case superstep count documented
Unit tests for each subgraph in isolation, asserting shared-contract fields
on return and callback propagation via a capturing handler
Reusable subgraphs ship with their own __version__ and a frozen
SHARED_KEYS set
Error Handling
Error / Symptom
Cause
Fix
Parent reads state["foo"] and gets None after subgraph call
Key declared only in child schema; discarded on return (P21)
Add foo to parent TypedDict; use matching reducer; or return Command(graph=Command.PARENT, update={"foo": ...})
Tracer attached to parent never fires on child tool calls
Callback bound at definition time via .with_config(callbacks=[...]) (P28)
Pass callbacks=[tracer] in config at each invoke() / ainvoke() call
TypeError: unhashable type from the message reducer in the parent after a Send fan-out
Child schema used list instead of Annotated[list, add_messages] (P18)
Match reducers on both sides of the boundary
GraphRecursionError: Recursion limit of 25 reached inside a subgraph only
Subgraph has its own 25-step budget; long sub-loop (P55)
Set config={"recursion_limit": N} explicitly or restructure subgraph
Subgraph returns state but parent sees empty messages
List field not using add_messages reducer on the parent side (P18)
messages: Annotated[list[AnyMessage], add_messages] in both TypedDicts
Command(goto="next_node") halts instead of continuing
Command did not set graph=Command.PARENT — tried to goto a parent node from inside the child scope
Use Command(graph=Command.PARENT, goto="next_node", update=...)
Subgraph runs but thread state never persists
Checkpointer attached only to parent; child invoke() without thread_id
Compile subgraphs with checkpointer too, or invoke with a thread_id matching the parent
The prototypical 1 + 2-4 composition: a planner writes a step list, an executor
runs each step, a finalizer summarizes. messages and session_id cross every
boundary; plan is parent-only; tool_result and retries are executor-only.
Uses a compiled-subgraph-as-node dispatch (Step 2A). See
Dispatch Patterns for the full worked example.
Hierarchical agent team — supervisor fans out to N specialists
A supervisor picks which specialists to invoke and calls Send("specialist", ...) in parallel. Each specialist runs its own subgraph with its own recursion
budget. Results merge via the messages reducer. See
Dispatch Patterns for the Send-based
fan-out and the callback propagation pattern needed to trace the team.
Reusable subgraph library — pinned contract with versioned exports
An executor_subgraph package exports build_executor(llm) and a frozen
SHARED_KEYS set, ships with a semantic version, and its CI fails if
SHARED_KEYS changes without a major-version bump. See
State Contract for the schema-pinning pattern.
Testing a specialist with a capturing callback
A CaptureHandler subclasses BaseCallbackHandler, appends every on_* event
to a list, and asserts both parent and child events are present after a single
parent_graph.invoke(..., config={"callbacks": [handler]}). Catches P28 at PR
review. See Testing Subgraphs for the full
fixture and assertion pattern.
