A node for executing tools in LangGraph workflows.
Handles tool execution patterns including function calls, state injection, persistent storage, and control flow. Manages parallel execution, error handling.
Use ToolNode when building custom workflows that require fine-grained control over
tool execution—for example, custom routing logic, specialized error handling, or
non-standard agent architectures.
For standard ReAct-style agents, use create_agent
instead. It uses ToolNode internally with sensible defaults for the agent loop,
conditional routing, and error handling.
ToolNode(
self,
tools: Sequence[BaseTool | Callable],
*,
name: str = 'tools',
tags: list[str] | None = None,
handle_tool_errors: bool | str | Callable[..., str] | type[Exception] | tuple[type[Exception], ...] = _default_handle_tool_errors,
messages_key: str = 'messages',
wrap_tool_call: ToolCallWrapper | None = None,
awrap_tool_call: AsyncToolCallWrapper | None = None
)Input Formats:
Graph state with messages key that has a list of messages:
messages_key parameterMessage List: [AIMessage(..., tool_calls=[...])]
Direct Tool Calls: [{"name": "tool", "args": {...}, "id": "1", "type": "tool_call"}]
Output Formats:
Output format depends on input type and tool behavior:
For Regular tools:
{"messages": [ToolMessage(...)]}[ToolMessage(...)]For Command tools:
[Command(...)] or mixed list with regular tool outputsCommand can update state, trigger navigation, or send messages| Name | Type | Description |
|---|---|---|
tools* | Sequence[BaseTool | Callable] | A sequence of tools that can be invoked by this node. Supports:
|
name | str | Default: 'tools'The name identifier for this node in the graph. Used for debugging and visualization. |
tags | list[str] | None | Default: NoneOptional metadata tags to associate with the node for filtering and organization. |
handle_tool_errors | bool | str | Callable[..., str] | type[Exception] | tuple[type[Exception], ...] | Default: _default_handle_tool_errorsConfiguration for error handling during tool execution. Supports multiple strategies:
Defaults to a callable that:
|
messages_key | str | Default: 'messages'The key in the state dictionary that contains the message list.
This same key will be used for the output Allows custom state schemas with different message field names. |