cacheplane
diff --git a/‎apps/website/content/blog/2026-08-27-langgraph-subgraphs-when-to-split.mdx‎
Lines changed: 223 additions & 0 deletions b/‎apps/website/content/blog/2026-08-27-langgraph-subgraphs-when-to-split.mdx‎
Lines changed: 223 additions & 0 deletions
@@ -0,0 +1,223 @@
+---
+title: 'LangGraph Subgraphs: When to Split a Graph and When Not To'
+description: 'On LangGraph, a subgraph buys you an observable boundary, not a state boundary. Why our own graphs got split, and what the frontend sees while a child runs.'
+date: 2026-08-27
+tags: [langgraph, subgraphs, agents, streaming, angular]
+author: brian
+featured: false
+draft: false
+---
+
+Most people reach for a LangGraph subgraph expecting a _state_ boundary, and what they actually get is an _observable_ one.
+
+If your question is "single agent, approval loop, or multi-agent?", that's an architecture question and the [decision matrix](/docs/langgraph/concepts/agent-architecture) already answers it.
+This post is about the layer underneath: what a subgraph actually changes at runtime, why our own graphs got split, and what the frontend sees while a child is running.
+
+## What does a subgraph actually give you?
+
+Nested execution and namespaced stream events. That's the honest list.
+
+Let's start with the canonical pattern, which is small.
+Compile a child `StateGraph`, then add the compiled graph as a node in the parent:
+
+```python
+research_builder = StateGraph(MessagesState)
+research_builder.add_node("search", search_web)
+research_builder.add_edge(START, "search")
+research_subgraph = research_builder.compile()
+
+builder = StateGraph(MessagesState)
+builder.add_node("research", research_subgraph)  # a compiled graph, used as a node
+```
+
+Two things change.
+The child runs as its own graph, with its own nodes and its own step sequence rather than being flattened into the parent's.
+And LangGraph emits the child's stream events under a namespace, so a consumer can tell parent output from child output.
+
+Here's the part I think gets assumed and shouldn't: state isolation isn't a third.
+
+If parent and child share `MessagesState`, the child appends to the same message list the parent is building.
+Nothing about `add_node` fenced anything off.
+
+Isolation is something you design — give the child its own state schema, then map in at the boundary and map the result back out.
+That's a decision you make and maintain, not a property `compile()` hands you.
+
+We ship one graph that does exactly that, and because it's a capability demo built to show the primitive, it's a clean look at the shape.
+Its child state schema has no `messages` key at all.
+Parent and child share exactly two keys, `research_topic` and `research_brief`, so the child is handed a topic and hands back a brief — it can't read the transcript, and it can't append to one.
+
+That boundary is real, and none of it came from `compile()`.
+It came from writing two `TypedDict`s and being deliberate about what they share.
+
+### What about context windows and error boundaries?
+
+Those are real reasons to split — our own docs lean on them.
+The [subgraphs guide](/docs/langgraph/guides/subgraphs) points at per-task context windows and failure containment as reasons to reach for subagents, and the docstring on our own research child's only node calls it "a focused contractor."
+
+But look at where each one actually comes from.
+A narrow context window is a consequence of what you pass into the child's `ainvoke` — you get it by handing over a topic instead of a transcript.
+An error boundary is a consequence of how the parent handles a failed child call, and a node-level retry wraps any node, plain function or compiled graph alike.
+Reuse across parents is a consequence of the child being a value you can reference twice.
+
+You can have all three without ever compiling a child graph, and you can compile a child graph and get none of them.
+
+There is one more, and it's worth stating because it looks like a counterexample.
+Wire the child in as a node under a parent that has a checkpointer, and the child's steps get checkpointed under its namespace — which is what lets you interrupt and resume at child granularity.
+Notice that's the namespace again, doing a second job.
+
+## Why do people really split?
+
+In our own repo, the honest answer is: so the frontend can see the delegation.
+
+That's a claim about our own graphs, not a law of the framework — and one of them splits for a different reason entirely, which I'll get to.
+But it's a natural experiment rather than a portfolio — nobody wrote these to prove a point about subgraphs, and the constraint that drove them, a frontend that renders per-child progress, isn't specific to us.
+
+Let's look at what we wrote down at the time.
+Here's the comment sitting above the research subagent in our canonical `examples/chat` graph:
+
+```python
+# Research subagent — a small compiled child graph the parent dispatches
+# via the `research` @tool. Running it as an actual subgraph (vs. inline
+# logic) is what causes LangGraph to emit stream events under namespace
+# prefix `tools:<id>` for the child run, which is what the @threadplane/langgraph
+# SubagentTracker keys on to populate `agent.subagents()`.
+```
+
+That's not a state argument. It's a visibility argument.
+
+The design doc for that feature is blunter still. Here's the alternative it rejected:
+
+```text
+Plain `@tool` returning a synthesized "subagent" payload — Simpler graph
+code but does not exercise the SubagentTracker code path: no `tools:`
+namespace events get emitted because no subgraph runs. The card would
+render empty. Rejected.
+```
+
+Then there's the conversion.
+Our `cockpit/chat/subagents` demo originally ran its three specialists as a flat in-process helper, and was rewritten to dispatch a real compiled child graph — because the flat version emitted no namespace events, so `subagents()` stayed empty and no card rendered.
+A working feature was restructured so a UI card would appear.
+
+In both of those graphs the compiled child is invoked from inside a `@tool` body, not wired in as a plain node.
+That's deliberate: the tool call is what the tracker registers, and our own docs are blunt that [plain subgraph nodes](/docs/langgraph/guides/subgraphs) don't show up in that map at all.
+
+Which cuts the other way from how it sounds — plain `add_node` subgraphs make the point sharper, not weaker.
+Those still get a namespace, so they're still observable in the raw stream.
+They just don't get a name, so nothing downstream can attribute them to anything.
+The subgraph is what makes the events observable; the tool call is what gives them an identity.
+
+## What does the frontend see while a child runs?
+
+Namespaced events — and nearly everything interesting downstream follows from that one fact.
+
+### What the wire looks like
+
+Let's take it from the wire inward.
+The event type carries the namespace after a pipe, so the base type is the part before it:
+
+```text
+messages                 # parent
+messages|tools:call-1    # child run dispatched by tool call "call-1"
+```
+
+Our transport requests those child streams by default — `streamSubgraphs` is `true` unless you turn it off.
+That's the LangGraph JS SDK's own option name, passed straight through, and worth knowing if you're coming from the Python API, where the in-process `graph.stream()` equivalent is the `subgraphs=True` kwarg.
+
+### The terminal-event hazard
+
+A child graph terminates before the parent does, and a child's terminal event looks an awful lot like the parent's.
+
+Without a namespace guard, that child terminal marker gets read as "the run finished" and closes out the parent's still-streaming assistant message.
+We guard it by refusing namespaced events as top-level terminal evidence, and there's a test that feeds a namespaced terminal marker in and asserts the parent message settles with outcome `interrupted` rather than success.
+
+If you ever write a transport against this stream yourself, that's the bug you'll hit, and it will look like truncation rather than a namespace bug.
+
+### Where child text goes
+
+Into your main transcript, by default.
+Our `filterSubagentMessages` is off unless you set it, so a child's tokens flow into `messages()` alongside the parent's.
+
+That isn't a quirk of our config.
+Any consumer reading a namespaced stream has to decide what a child's tokens mean, and "append them like everything else" is the path of least resistance — so unless something opts out, child text lands in the parent transcript and the same content renders twice.
+
+### How does a child get attributed?
+
+By id — and this is the part I find well-designed: the namespace segment _is_ the identifier.
+
+`tools:<id>` carries the parent tool call id, so the tracker slices the prefix off and looks the id up directly against what it recorded when the tool call came through.
+Marking a child running and routing its messages need no matching at all.
+
+There is also a description-comparison ladder — exact match on the tool call's `description` argument, then substring either direction, then a last-resort fallback to any unmapped subagent still pending or running.
+It only runs for children whose state opens with a human message, and none of the graphs we ship reach it.
+The ones dispatched through a tool call invoke the child with an empty message list, so the first message in child state is the AI response.
+The one wired in as a plain node doesn't keep a `messages` key in child state at all.
+Treat that path as untested rather than as the mechanism.
+
+The general point survives, though, and it's the one worth carrying to any protocol.
+A consumer mapping child runs onto delegations is doing string matching unless the protocol gives it an id.
+LangGraph gives it an id — which is why the ladder is vestigial here and would be load-bearing in a fan-out graph with look-alike children.
+
+One limit, though: only the _first_ `tools:` segment of a namespace is read.
+A subagent that itself delegates will have its inner events attributed to the outer tool call.
+Nothing in this repo exercises deeper nesting, so don't build on it.
+
+## When should you not split?
+
+When there's no observable boundary to draw and no genuinely divergent state.
+
+The cleanest evidence I have is a control group we didn't set out to build.
+Our `cockpit/ag-ui/subagents` capability ships the same three-subagent feature as the LangGraph one — and it's a LangGraph `StateGraph` too, same framework, same orchestrator-plus-`task`-tool shape, same three roles, same cards in the UI — with no subgraph anywhere.
+Its module docstring says so outright:
+
+```text
+Mirrors cockpit/chat/subagents' orchestrator + `task` tool + `_run_subagent`
+structure, but each dispatch emits `subagent_activity` CUSTOM events
+```
+
+The thing that differs is the transport: AG-UI's already carries a first-class delegation event.
+So so the specialists stayed a flat `async` helper and progress reaches the frontend as a custom event dispatched from the tool body.
+
+The subgraph was never required by the feature. It was required by the transport.
+
+You could dispatch custom events from the LangGraph graph too — nothing stops you, and `adispatch_custom_event` is a LangChain primitive, not an AG-UI one.
+What namespaces buy is that you don't have to.
+The boundary emits its own identity for free, and a transport that reads it works against any graph rather than any graph that remembered to instrument itself.
+
+Staying flat wasn't free.
+There's no separate state schema to isolate anything into, and no child step sequence — every specialist gets the parent's shape, one LLM call wide.
+What it bought was one fewer graph for a feature that renders identically.
+
+That's the test I'd apply.
+If your transport already has a way to say "a child is working right now," or your UI doesn't render per-child progress at all, then a subgraph is a boundary you now have to defend: an extra state schema, mapping at both edges, and one more place to look when a message goes missing.
+
+And splitting because a region of the graph _feels_ like a separate concern isn't a reason on its own.
+A node is already a unit.
+
+### So when does a split earn itself?
+
+When the child really is a different graph — and the repo has exactly one of those, which is the case I owe you after arguing the other side this whole time.
+
+Our `examples/ag-ui` demo runs on that same AG-UI transport, and it emits the same `subagent_activity` events from the tool body.
+So it isn't buying observability; it already had it.
+It compiles a child graph anyway.
+
+Look at what the child is, though.
+It has its own `agent → tools → agent` loop with conditional edges and an iteration cap — a different control flow from the parent's, not a slice of it.
+
+And here's the part that took me a second read to see.
+A custom child state schema doesn't discriminate at all: the two graphs I just used as observability evidence _also_ define their own child `TypedDict`s.
+But both of those children are one node and a straight line, so the schema is really just an argument list with a type on it.
+
+So it's the control flow, not the schema.
+A child that carries a `topic` string is a function call wearing a graph costume.
+A child that loops until it's satisfied is a graph.
+
+## Conclusion
+
+Split when something outside the graph needs to see the child run as its own thing — a card, a progress panel, per-child streaming.
+Split when the child has its own control flow — a loop, a branch, a stopping condition the parent doesn't have — and you're willing to own the mapping at both edges.
+Don't split for tidiness, and don't assume the split isolated state: wire a child in as a node on a shared `MessagesState` and it appends straight to the transcript the parent is building.
+
+The [architecture matrix](/docs/langgraph/concepts/agent-architecture) covers the tiering question, the [subgraphs guide](/docs/langgraph/guides/subgraphs) has the composition and `subagents()` wiring, and [What injectAgent() Actually Returns](/blog/what-inject-agent-returns) walks the signal surface those child streams land in.
+
+If you've split a graph for a third reason — not observability, and not a child that's genuinely its own graph — I'd like to hear it. Those are the two I've been able to justify; I doubt they're the only two that exist.