Intermediate14 min
ToolNode & ToolRuntime
ToolNode is the prebuilt LangGraph node that handles tool execution — parallelism, error routing, and ToolMessage creation included. ToolRuntime is the parameter that gives any tool inside that node access to the agent's state, context, and store without those values leaking into the schema the model sees.
Quick Reference
- →from langgraph.prebuilt import ToolNode, tools_condition
- →ToolNode handles parallel execution, error handling, and ToolMessage creation automatically
- →from langchain.tools import ToolRuntime — injected by ToolNode, hidden from the model schema
- →runtime.state: current graph state (messages + custom fields)
- →runtime.context: immutable per-run config (user ID, tenant) — pass via context_schema
- →runtime.store: cross-session persistence; runtime.stream_writer: real-time progress events
- →Return Command(update={...}) from a tool to write back to agent state
When to Use ToolNode (and When Not To)
| Situation | Use | Why |
|---|---|---|
| Custom LangGraph StateGraph | ToolNode | Handles parallelism, error routing, ToolMessage creation — you'd rewrite all of this by hand otherwise |
| Starting a new agent quickly | create_agent() | Includes ToolNode internally, wires the graph for you |
| Need custom tool execution logic | Manual node | Only when you need to intercept or transform results before they hit state |
| LCEL chains (not StateGraph) | Neither | Tool calling in LCEL doesn't use graph nodes — bind_tools + invoke does it inline |
create_agent already includes ToolNode
If you're using create_agent() from langchain.agents, ToolNode is wired inside automatically. You only need to configure it explicitly when building a custom StateGraph.