What is .add_node()?
.add_node() is the first method you call when building a LangGraph StateGraph — it registers a Python callable as a named processing step in the graph. The callable receives the graph's state dict as its only argument and returns a dict of state field updates. LangGraph merges these updates into the shared state using the registered reducers for each field.
Node functions do not modify state in place. Instead, they return only the fields they want to change. LangGraph's state management applies these partial updates using the reducer for each annotated field — for example, add_messages for the messages field, or simple replacement for primitive fields. This immutable-update pattern makes nodes easy to test in isolation: call the node function directly with a mock state dict and inspect the returned dict without running the full graph.
Starting in LangGraph 0.2, add_node() accepts a shorthand form where the function name is used as the node name: graph.add_node(my_function). This is convenient but can cause confusion when the function is a lambda or closure. For production graphs, prefer explicit string names. LangGraph also supports async node functions — define with async def and LangGraph awaits them automatically.
Use Cases
- • Build graph workflows
- • Add processing steps
- • Multi-step agents
- • Decision trees
- • Workflow nodes
- • State transitions
Key Features
- ✓ Register nodes
- ✓ Function wrapping
- ✓ State handling
- ✓ Multiple nodes
- ✓ Node composition
- ✓ Flexible execution
When NOT to Use
For simple linear chains—use LCEL.
Notes
Node functions return partial state updates
Return only the fields you want to change, not the entire state. Returning None is equivalent to returning {} — a no-op update. Keys not in the state TypedDict are silently ignored.
Async nodes work without extra configuration
Define your node with async def and LangGraph detects the coroutine and awaits it automatically. Mixing sync and async nodes in the same graph is fully supported.
Node names must be unique within a graph
Each node name must be unique. Re-registering a name raises ValueError. Use descriptive, namespaced names like agent_reason and agent_act rather than generic names like step1 to avoid collisions in complex graphs.
Subgraphs can be registered as nodes
graph.add_node('sub', subgraph.compile()) registers a compiled subgraph as a single node. The subgraph receives the parent state projected to its own schema and returns updates. This enables graph-of-graphs composition for modular agent architectures.
Method Signature
graph.add_node(name, function)Parameters
| Parameter | Type | Required | Purpose |
|---|---|---|---|
| name | str | Yes | Unique node name |
Return Value
Type:
StateGraph
Description:
Graph with node added
Example Output:
graphCode Examples
Register nodes by name
from langgraph.graph import StateGraph
graph = StateGraph(AgentState)
graph.add_node('agent', agent_function)
graph.add_node('tool', tool_function)Async node function
from typing import TypedDict
from langgraph.graph import StateGraph, START, END
class State(TypedDict):
text: str
summary: str
async def summarize(state: State):
result = await llm.ainvoke(f"Summarize: {state['text']}")
return {"summary": result.content}
graph = StateGraph(State)
graph.add_node('summarize', summarize) # async node
graph.add_edge(START, 'summarize')
graph.add_edge('summarize', END)
compiled = graph.compile()Subgraph as node for graph-of-graphs composition
from langgraph.graph import StateGraph, START, END
# Register a compiled subgraph as a node
inner_graph = StateGraph(InnerState)
inner_graph.add_node('inner_step', inner_fn)
inner_graph.add_edge(START, 'inner_step')
inner_graph.add_edge('inner_step', END)
inner_compiled = inner_graph.compile()
outer_graph = StateGraph(OuterState)
outer_graph.add_node('sub', inner_compiled) # subgraph as nodeCommon Mistakes
❌ Node name same as function name confusion
✅ graph.add_node('agent', my_agent_fn) # Different
Related LangChain References
Browse the full LangChain API reference index to explore more classes, methods, and decorators, or start with the LangChain introduction tutorial for end-to-end context on building with .add_node() and the wider framework.
.add_node() FAQ
What does .add_node() do in LangChain?
Add a node to the graph. .add_node() is the first method you call when building a LangGraph StateGraph — it registers a Python callable as a named processing step in the graph. The callable receives the graph's state dict as its only argument and returns a dict of state field updates. LangGraph merges these updates into the shared state using the registered reducers for each field. Node functions do not modify state in place. Instead, they return only the fields they want to change. LangGraph's stat…
Which LangChain classes support .add_node()?
.add_node() is available on StateGraph. Pin your installed LangChain version and verify the method exists in that release before deploying.
When should I use .add_node()?
Use .add_node() when your LangChain chains, agents, or pipelines need the behavior described in this guide.
What does .add_node() return?
.add_node() returns a StateGraph. Graph with node added
Does .add_node() have an async equivalent?
.add_node() does not have a documented async variant. Avoid .add_node() For simple linear chains—use LCEL.
Where can I explore more LangChain API reference pages?
Open the LangChain API reference index on DevShelfHub to browse classes, methods, and decorators, each with runnable examples, parameters, common mistakes, and cross-links.