Command API
Command lets nodes decide routing at runtime — atomic state update plus goto in one return value. This guide covers all four parameters (goto, update, resume, graph), type annotations that preserve graph visualization, fan-out patterns, multi-agent handoff with loop guards, and the interrupt/resume pattern for human-in-the-loop workflows.
Quick Reference
- →Command(goto='node'): route to a named node from inside the current node — no separate edge function needed
- →Command(update={'key': val}): update state atomically with the routing decision in a single return
- →Command(goto=['a', 'b']): fan out to multiple nodes simultaneously — all receive the same shared state
- →Command(resume=value): resume execution after interrupt() — passes value back to the paused node
- →Command(graph=Command.PARENT): route to a node in the closest parent graph from inside a subgraph
- →Command[Literal['node_a', 'node_b']]: return type annotation that preserves graph visualization in edgeless graphs
- →goto typos are runtime errors — target node names are never validated at compile time
- →Always track hop count in state when using multi-agent handoff — Command has no built-in cycle detection
When to Use Command (and When Not To)
Command is the right choice when the routing decision is a direct consequence of computation done inside the node — when the node that does the work is also the one best positioned to say what happens next. The opposite case — routing logic that is independent of any single node's computation — belongs in add_conditional_edges.
| Situation | Use | Why |
|---|---|---|
| Routing depends on the node's own output | Command | Keeps routing co-located with the computation that drives it |
| Fixed routing — always the same next node | add_edge | More explicit; visible in graph diagram with no annotations needed |
| Routing logic is independent of node computation | add_conditional_edges | Separates concerns; routing function is reusable across nodes |
| Multi-agent handoff — active agent picks successor | Command | Natural fit: the agent that finishes a task knows who handles the result |
| Branch on a state flag set by a different node | add_conditional_edges | No single node owns the decision — keep it in the edge function |
Do not use Command for simple fixed routing — add_edge is clearer. Do not use Command when the routing decision is independent of the node's computation — that belongs in a conditional edge function. Do not mix Command returns and add_conditional_edges on the same node — LangGraph raises a ValueError. Do not build edgeless graphs without Command[Literal[...]] annotations if you rely on draw_mermaid() for graph visualization.