docs: add Command/GraphCommand docs

docs/docs/concepts/low_level.md

@@ -322,6 +322,52 @@ def continue_to_jokes(state: OverallState):
 graph.add_conditional_edges("node_a", continue_to_jokes)
 ```
 
+## `GraphCommand`
+
+Typically, LangGraph separates control flow (edges) from state updates (nodes). However, it is often beneficial to combine the two. For example, you might want to BOTH perform state updates AND decide which node to go next in the SAME node. LangGraph provides a way to combine control flow and node state updates using [`GraphCommand`][langgraph.graph.state.GraphCommand]. To do so, you can return a `GraphCommand` object from a node instead of a state update or `Send` objects.
+
+`GraphCommand` has the following properties:
+
+  - `goto`: optional, name of the node to navigate to next.
+        If not specified, the graph will halt after executing the current superstep.
+  - `graph`: optional, graph to send the command to. Supported values are:
+    - `None`: the current graph (default)
+    - `GraphCommand.PARENT`: parent graph.
+  - `update`: optional, state update to apply to the graph's state at the current superstep.
+  - `send`: optional, list of [`Send`](#send) objects to send to other nodes.
+  - `resume`: optional, value to resume execution with. Will be used when `interrupt()` is called.
+
+```python
+from langgraph.graph import GraphCommand, StateGraph, START
+from typing_extensions import TypedDict, Literal
+
+class State(TypedDict):
+    foo: str
+
+def my_node(state: State) -> GraphCommand[Literal["my_other_node"]]:
+    return GraphCommand(update={"foo": "bar"}, goto="my_other_node")
+
+def my_other_node(state: State):
+    return {"foo": state["foo"] + "baz"}
+
+builder = StateGraph(State)
+builder.add_edge(START, "my_node")
+builder.add_node("my_node", my_node)
+builder.add_node("my_other_node", my_other_node)
+
+graph = builder.compile()
+```
+
+With `GraphCommand` you can also achieve dynamic control flow behavior (identical to [conditional edges](#conditional-edges)):
+
+```python
+def my_node(state: State) -> GraphCommand[Literal["my_other_node", "__end__"]]:
+    if state["foo"] == "bar":
+        return GraphCommand(update={"foo": "baz"}, goto="my_other_node")
+    else:
+        return GraphCommand(goto="__end__")
+```
+
 ## Persistence
 
 LangGraph provides built-in persistence for your agent's state using [checkpointers][langgraph.checkpoint.base.BaseCheckpointSaver]. Checkpointers save snapshots of the graph state at every superstep, allowing resumption at any time. This enables features like human-in-the-loop interactions, memory management, and fault-tolerance. You can even directly manipulate a graph's state after its execution using the

docs/docs/how-tos/index.md

@@ -20,6 +20,7 @@ These how-to guides show how to achieve that controllability.
 - [How to create branches for parallel execution](branching.ipynb)
 - [How to create map-reduce branches for parallel execution](map-reduce.ipynb)
 - [How to control graph recursion limit](recursion-limit.ipynb)
+- [How to combine control flow and state updates with GraphCommand](graph-command.ipynb)
 
 ### Persistence
 

docs/docs/reference/graphs.md

@@ -11,6 +11,7 @@
       members:
         - StateGraph
         - CompiledStateGraph
+        - GraphCommand
 
 ::: langgraph.graph.message
     options:

docs/docs/reference/types.md

@@ -13,3 +13,4 @@
         - PregelExecutableTask
         - StateSnapshot
         - Send
+        - Command

docs/mkdocs.yml

@@ -151,6 +151,7 @@ nav:
             - how-tos/branching.ipynb
             - how-tos/map-reduce.ipynb
             - how-tos/recursion-limit.ipynb
+            - how-tos/graph-command.ipynb
         - Persistence:
             - Persistence: how-tos#persistence
             - how-tos/persistence.ipynb

libs/langgraph/langgraph/graph/state.py

@@ -86,7 +86,18 @@ def _get_node_name(node: RunnableLike) -> str:
 
 @dataclasses.dataclass(**_DC_KWARGS)
 class GraphCommand(Generic[N], Command[N]):
-    """One or more commands to update a StateGraph's state and go to, or send messages to nodes."""
+    """One or more commands to update a StateGraph's state and go to, or send messages to nodes.
+
+    Args:
+        goto: name of the node to navigate to next.
+            If not specified, the graph will halt after executing the current superstep.
+        graph: graph to send the command to. Supported values are:
+            - None: the current graph (default)
+            - GraphCommand.PARENT: closest parent graph
+        update: state update to apply to the graph's state at the current superstep.
+        send: list of `Send` objects to send to other nodes.
+        resume: value to resume execution with. Will be used when `interrupt()` is called.
+    """
 
     goto: Union[str, Sequence[str]] = ()
 

libs/langgraph/langgraph/types.py

@@ -239,7 +239,16 @@ N = TypeVar("N", bound=Hashable)
 
 @dataclasses.dataclass(**_DC_KWARGS)
 class Command(Generic[N]):
-    """One or more commands to update the graph's state and send messages to nodes."""
+    """One or more commands to update the graph's state and send messages to nodes.
+
+    Args:
+        graph: graph to send the command to. Supported values are:
+            - None: the current graph (default)
+            - GraphCommand.PARENT: closest parent graph
+        update: state update to apply to the graph's state at the current superstep.
+        send: list of `Send` objects to send to other nodes.
+        resume: value to resume execution with. Will be used when `interrupt()` is called.
+    """
 
     graph: Optional[str] = None
     update: Optional[dict[str, Any]] = None