Multi-Agent Patterns

## The two things a node does Every LangGraph node does at most two things: it produces a partial state update, and it causes control to move somewhere. Classically those are separate mechanisms. The update is the dict the node returns, merged into the graph's state channels by each channel's reducer. The movement is declared at build time with `add_edge("a", "b")`, or decided by a separate routing function you attach to the graph, which reads the state the node just wrote and returns a node name. That separation is fine for a pipeline. It is awkward for agents. When a research agent concludes "I have enough, the writer should take over", the decision and the evidence for it are produced by the same reasoning step, and splitting them forces you to smuggle the decision through state — write `state["next"] = "writer"`, then have a second function read `state["next"]` back out and return it. That indirection is the thing `Command` removes. ## What Command is `Command` is a dataclass in `langgraph.types`. The fields that matter for multi-agent composition are: - `update` — the same partial-state dict a node would otherwise return. It is not special-cased: it flows through the channel reducers exactly as a plain return value would, so an `add_messages` channel still appends and de-duplicates by message id. - `goto` — the name of the next node, or a list of node names, or `END`. Resolved at runtime, when the node returns. - `graph` — set to `Command.PARENT` to resolve `goto` against the parent graph instead of the graph the node lives in. A node returning `Command(update={...}, goto="writer")` therefore performs the state write and the transition atomically from the caller's point of view: the update lands, then `writer` runs against the updated state. ## Why the Literal annotation matters When routing lives in `goto`, the compiled graph has no static outgoing edge for that node, so `graph.get_graph().draw_mermaid()` would show a node with no successors and reviewers lose the topology. The convention is to type the return as `Command[Literal["writer", "__end__"]]`; LangGraph reads those literals to render the candidate destinations. Treat it as documentation the toolchain can see, not as a runtime constraint — it is the thing that keeps a Command-heavy graph readable six months later. ## Handoff from inside a subgraph Multi-agent graphs are usually nested: each agent is itself a compiled graph attached as a node. A node deep inside the research subgraph that wants to hand off to the `writer` node — a sibling of the whole research subgraph in the parent — cannot name it in a plain `goto`, because `goto` resolves within the current graph. `Command(goto="writer", graph=Command.PARENT)` is the escape hatch: the update applies to the subgraph's state (and propagates upward through whatever keys parent and child share), and control resumes at `writer` in the parent. This is the mechanism behind swarm-style handoffs, where any agent can pass control to any other without a central router. ## Tools can return Command too The prebuilt tool-executing node recognises a `Command` returned by a tool function and applies it, rather than wrapping it as a tool result string. That is how a handoff *tool* is built: the model calls `transfer_to_writer`, the tool returns `Command(goto="writer", update={...}, graph=Command.PARENT)`, and the transfer becomes an ordinary tool call the model already knows how to emit. The alternative — a supervisor node that reads structured output and routes — puts the decision in a dedicated LLM call instead of inside the worker's own turn. ## When not to use it `Command` is not a replacement for edges. If a node always goes to exactly one place, `add_edge` says so declaratively, is visible in the drawn graph, and cannot drift. Scattering `goto` through a dozen nodes rebuilds a control-flow graph that only exists at runtime, which is precisely what LangGraph's static topology was meant to make inspectable. The rule of thumb: use `Command` where the transition is a *decision the node makes*, and edges where the transition is *structure*. ## Failure modes A `goto` naming a node that does not exist is a runtime failure, not a build-time one, so a typo in an agent name survives `compile()`. Keep the destination names in one module-level constant list shared by the annotation and the routing logic. And remember that `update` is still merged, not assigned: returning `Command(update={"messages": [...]})` on a channel with an appending reducer appends — it does not replace the history.