ToolNode, InjectedState, InjectedStore, ToolRuntime, ToolCallTransformer — API reference
The prebuilt ToolNode executor, state/store injection annotations, ToolRuntime context, tools_condition router, ToolCallRequest interceptor, and ToolCallTransformer/ToolCallStream for per-tool streaming — with source-verified signatures.
Verified against langgraph==1.2.22 / langgraph-prebuilt==1.1.2 (modules: langgraph.prebuilt.tool_node, langgraph.prebuilt.tool_validator, langgraph.prebuilt._tool_call_transformer, langgraph.prebuilt._tool_call_stream).
ToolNode is LangGraph’s prebuilt executor that takes a list of tools, reads the last AI message in state, runs every pending tool call in parallel, and writes back ToolMessage results. The surrounding helpers — InjectedState, InjectedStore, ToolRuntime, tools_condition, ToolCallRequest, ToolCallTransformer, and ToolCallStream — let tools read graph state, access the long-term store, stream partial output, intercept calls before execution, and consume per-tool-call streaming results in a structured way.
langgraph.prebuilt.tool_node (also re-exported from langgraph.prebuilt)
tools_condition
langgraph.prebuilt.tool_node (also re-exported from langgraph.prebuilt)
InjectedState
langgraph.prebuilt.tool_node (also re-exported from langgraph.prebuilt)
InjectedStore
langgraph.prebuilt.tool_node (also re-exported from langgraph.prebuilt)
ToolRuntime
langgraph.prebuilt
ToolCallRequest
langgraph.prebuilt.tool_node
ToolCallTransformer
langgraph.prebuilt (defined in langgraph.prebuilt._tool_call_transformer)
ToolCallStream
langgraph.prebuilt._tool_call_stream
ValidationNode
langgraph.prebuilt.tool_validator (deprecated)
MessagesState
langgraph.graph.message
The top-level langgraph.prebuilt.__init__ re-exports ToolNode, tools_condition, InjectedState, InjectedStore, ToolRuntime, ToolCallTransformer, ValidationNode and the deprecated create_react_agent. ToolCallRequest and ToolCallStream must be imported from their sub-modules.
tools — list of BaseTool instances or plain callables decorated with @tool. Callables are wrapped automatically.
name — node name as registered in the graph. Defaults to "tools".
tags — LangChain run tags forwarded to each tool invocation for tracing.
handle_tool_errors — controls exception handling; see the table below. The default catches only invalid-argument errors; exceptions raised inside a tool propagate.
messages_key — the state key that holds the message list. Only relevant when state is a dict; ignored for list/direct-tool-call input formats.
wrap_tool_call — sync interceptor called for every tool call before execution; receives a ToolCallRequest and an execute callable.
awrap_tool_call — async variant of wrap_tool_call. Falls back to wrap_tool_call when not set.
When any tool returns a Command, the node returns a list that may mix ToolMessage and Command objects. The graph runtime handles routing those commands to the appropriate next nodes.
Catch only ToolInvocationError (the model’s arguments failed schema validation) and return the validation message so the model can retry. Every other exception propagates.
True
Catch all exceptions; return a default error string in a ToolMessage
str
Catch all exceptions; return this exact string as the error ToolMessage content
type[Exception]
Only catch this exception type; all others propagate
tuple[type[Exception], ...]
Only catch these exception types; all others propagate
Callable[..., str]
Catch the exception types named in the formatter’s first-parameter annotation (all exceptions if unannotated); its return value is the error string
False
Disable error handling entirely; all exceptions propagate to the graph
With True, a tuple or an exception type, the content is "Error: {repr(exc)}\n Please fix your mistakes." and the ToolMessage has status="error". The default handler returns the ToolInvocationError message instead, which lists the invalid fields.
The execute callable runs the original tool and returns a ToolMessage | Command. You may call it, skip it, or replace it entirely. awrap_tool_call is used when the graph runs in async mode. If awrap_tool_call is not set, async execution falls back to wrap_tool_call.
Returns a new ToolCallRequest with the specified fields replaced. Direct attribute assignment on ToolCallRequest instances is deprecated — use override instead:
When state is a dict, messages_key controls which key holds the list (default "messages"). When state is a list, it is used directly. Otherwise the messages_key attribute is read (for a Pydantic or dataclass state). With no messages at all it raises ValueError.
Important:tools_condition always returns the literal string "tools" or "__end__". Your ToolNode must be registered with name="tools" (the default). If you name the node differently, add a path_map to remap the return value:
Annotates a tool parameter so that ToolNode injects the current graph state automatically. The argument is hidden from the model’s tool schema — the LLM never sees or fills it.
When InjectedState("foo") is used, the tool receives state["foo"] directly, not the full dict. No Annotated nesting beyond the outer annotation is needed.
Annotates a tool parameter so that ToolNode injects the long-term BaseStore compiled into the graph. Like InjectedState, the parameter is hidden from the model’s schema.
The graph must be compiled with store=, e.g. builder.compile(store=InMemoryStore()). Without one, ToolNode raises ValueError: Cannot inject store into tools with InjectedStore annotations - please compile your graph with a store. when the tool is called. (ToolRuntime.store, by contrast, is simply None.)
A dataclass injected into tools that declare a parameter annotated ToolRuntime (conventionally named runtime). No Annotated wrapper is needed: the annotation alone marks it as injected, and it is left out of the schema the model sees.
state — the full current graph state, same as InjectedState().
context — the run-level context passed to invoke(context=...) (from context_schema).
config — the RunnableConfig for the current run (thread_id, callbacks, etc.).
stream_writer — callable that writes to stream_mode="custom", like get_stream_writer(). For partial tool output on the "tools" mode, use emit_output_delta instead.
tool_call_id — the id field of the tool call currently being executed.
store — the BaseStore compiled into the graph, or None.
tools — the list of tools registered with this ToolNode.
execution_info — ExecutionInfo with checkpoint_id, thread_id, run_id, node_attempt, node_first_attempt_time. Populated whenever the tool runs inside a graph.
server_info — ServerInfo, set only when running in the LangGraph Agent Server; None otherwise.
Streams a partial output chunk to the tools channel. Callers consuming stream_mode="tools" will receive each delta as it is emitted. This is a no-op if the graph was not invoked with stream_mode="tools" (or a superset that includes it).
ToolRuntime is tool-specific. It is distinct from Runtime (from langgraph.runtime), which is injected into graph nodes. Do not annotate node parameters with ToolRuntime.
from langgraph.prebuilt.tool_validator import ValidationNode
Deprecated since v1.0. Validates tool call schemas without executing the tools. It was designed for structured output and extraction workflows where the LLM needs to be re-prompted when its tool arguments fail schema validation.
Two migration paths:
ToolNode(handle_tool_errors=True) with a pydantic args_schema on the tool — the node catches argument-validation failures and converts them to ToolMessage error replies. Important: unlike ValidationNode, ToolNodeexecutes every call whose arguments are valid. This is unsafe in validate-only workflows (e.g. before a human-approval step) where side effects such as sending email or charging a payment must not occur during validation.
Custom validation node — for schema-only validation without execution, call tool.args_schema.model_validate(tc["args"]) for each tool call and return a ToolMessage for every call — a success message when arguments are valid, an error message when they are not — without invoking the tool. Every tool_call in the preceding AIMessage must have a matching ToolMessage; omitting results for successful calls leaves the history malformed and the provider will reject the next model call. This is the only safe migration path when execution must not happen during validation.
The error_handler= parameter on StateGraph.add_node provides node-level fallback handling after all retries are exhausted — it is separate from per-call validation. (handle_tool_errors is a ToolNode constructor argument, not an add_node keyword; langchain.agents.create_agent exists in the separate langchain package, not in langgraph.)
Injected parameters can sit next to ordinary ones. The model sees and fills only the ordinary ones, so the tool call’s args hold just action and resource here, and permissions come from state the model can’t forge:
override() returns a new ToolCallRequest with selected fields replaced. Use this to sanitize, normalise, or augment tool arguments without mutating the original:
from langchain_core.tools import tool
from langchain_core.messages import ToolMessage
from langgraph.prebuilt.tool_node import ToolNode, ToolCallRequest
The request.tool attribute gives you the fully resolved BaseTool instance — including its schema, description, and metadata — before the call is dispatched:
import json
from langchain_core.tools import tool
from langchain_core.messages import ToolMessage
from langgraph.prebuilt.tool_node import ToolNode, ToolCallRequest
@tool
def search(query:str)->str:
"""Search the web for a query."""
returnf"Results for: {query}"
import threading
# Keyed by (tool_name, thread_id) so each conversation gets its own quota.
ToolCallTransformer (module: langgraph.prebuilt._tool_call_transformer) is a built-in StreamTransformer that turns the raw tools-channel protocol events emitted during graph streaming into convenient ToolCallStream handles — one per tool invocation. It lets you consume per-tool incremental output (delta streaming), final output, and errors in a structured way without parsing raw event dicts.
Note:ToolCallTransformer is not a base class to subclass; it is a concrete transformer you register with compile(). Its run.tool_calls projection is consumed through stream_events(..., version="v3") (experimental); plain stream(stream_mode="tools") always yields the raw protocol event dicts — see also the Streaming modes reference.
After registration, stream_events(..., version="v3") returns a GraphRunStream whose run.tool_calls projection yields ToolCallStream objects. (You can also pass transformers=[ToolCallTransformer] to stream_events per call.) Plain graph.stream(..., stream_mode="tools") is unaffected and still yields raw event dicts.
Input arguments as received by the tool (from on_tool_start). None if not captured.
output_deltas
StreamChannel[Any]
Channel of incremental delta chunks. Iterate sync or async as they arrive.
output
Any
Terminal output from tool-finished. For a ToolNode tool this is the ToolMessage content as a string (a tool returning 42 gives '42'). None until the tool completes successfully.
error
str | None
Terminal error message from tool-error. None until the tool fails.
completed
bool
True once either tool-finished or tool-error has been observed.
langgraph.prebuilt.create_react_agent is deprecated since LangGraph 1.0: it warns with LangGraphDeprecatedSinceV10 (a DeprecationWarning subclass, so it is hidden unless warnings are enabled, for example under pytest) and is due for removal in 2.0. Use langchain.agents.create_agent, which builds the same model-and-tools loop and adds middleware (Chapter 2). For an agent you control step by step, build a StateGraph with ToolNode and tools_condition as in the minimal example at the top of this page.
Mapping of the old arguments (prompt, pre_model_hook, post_model_hook, state_schema, interrupt_before, response_format) to create_agent: Chapter 8 — Migrating from create_react_agent hooks. A custom state_schema for create_react_agent must include remaining_steps: RemainingSteps, or the call raises ValueError: Missing required key(s) {'remaining_steps'}.
InjectedState / InjectedStore parameters are invisible to the model. They are stripped from the JSON schema before it is sent to the LLM. Do not prompt the model to fill them in.
InjectedStore requires store= on compile. Without it, the tool call fails with ValueError: Cannot inject store into tools with InjectedStore annotations - please compile your graph with a store.
ToolRuntime is detected by its type annotation. Any parameter name works (rt: ToolRuntime is injected too); runtime is the convention. Without the annotation, the parameter becomes a normal argument the model must fill.
ToolRuntime is not Runtime.Runtime (from langgraph.runtime) is injected into graph nodes; ToolRuntime is injected into tools by ToolNode. Mixing them up causes type errors at runtime.
emit_output_delta is a no-op outside stream_mode="tools". If you invoke the graph without streaming or with a mode that excludes "tools", calls to emit_output_delta do nothing and do not raise.
Direct attribute assignment on ToolCallRequest is deprecated. Always use request.override(...) to produce a modified copy.
wrap_tool_call runs synchronously even in async mode unless you also provide awrap_tool_call. Synchronous wrappers that do I/O in an async context will block the event loop.
handle_tool_errors=False means zero protection. Any exception raised by a tool propagates directly into the graph and can halt execution. Use this only when you handle errors in the tool itself or upstream.
ToolNode runs all tool calls in the last AIMessage in parallel. Tool ordering is not guaranteed. If your tools have side effects that must be sequenced, fan them out to separate nodes or serialise them in a custom wrapper.
messages_key must match your state schema. If your messages key is not "messages", set messages_key= on ToolNode and also pass messages_key= to tools_condition.
ToolRuntime.emit_output_delta(), ToolCallTransformer and ToolCallStream added (used with the "tools" stream mode of langgraph 1.2.0).
1.0.2 (prebuilt)
ToolRuntime and ToolCallRequest.override() introduced; direct attribute assignment on ToolCallRequest deprecated.
1.0.0 (prebuilt)
ValidationNode deprecated (planned removal v2.0.0) — no drop-in replacement: ToolNode(handle_tool_errors=True) with a pydantic args_schema when tool execution is acceptable; use a custom validation node (tool.args_schema.model_validate(tc["args"])) for validate-only workflows where tools must not execute. AgentState / AgentStatePydanticdeprecated — top-level re-export removed from langgraph.prebuilt.__init__, but still importable from langgraph.prebuilt.chat_agent_executor; scheduled for removal in v2.0.0. Use MessagesState or a custom TypedDict for new code.