Alpha Notice: These docs cover the v1-alpha release. Content is incomplete and subject to change.For the latest stable version, see the v0 LangChain Python or LangChain JavaScript docs.
Create tools
Basic tool definition
The simplest way to create a tool is with the@tool
decorator. By default, the function’s docstring becomes the tool’s description that helps the model understand when to use it:
Customize tool properties
Custom tool name
By default, the tool name comes from the function name. Override it when you need something more descriptive:Custom tool description
Override the auto-generated tool description for clearer model guidance:Advanced schema definition
Define complex inputs with Pydantic models or JSON schemas:Use tools with agents
Agents go beyond simple tool binding by adding reasoning loops, state management, and multi-step execution.To see examples of how to use tools with agents, see Agents.
Advanced tool patterns
ToolNode
ToolNode is a prebuilt LangGraph component that handles tool calls within an agent’s workflow. It works seamlessly withcreate_agent()
, offering advanced tool execution control, built in parallelism, and error handling.
Configuration options
ToolNode
accepts the following parameters:
A list of tools that this node can execute. Can include:
- LangChain
@tool
decorated functions - Callable objects (e.g. functions) with proper type hints and a docstring
handle_tool_errors
Controls how tool execution failures are handled.
Can be:
bool
str
Callable[..., str]
type[Exception]
tuple[type[Exception], ...]
_default_handle_tool_errors
Error handling strategies
ToolNode
provides built-in error handling for tool execution through its handle_tool_errors
property.
To customize the error handling behavior, you can configure handle_tool_errors
to either be a boolean, a string, a callable, an exception type, or a tuple of exception types:
True
: Catch all errors and return a ToolMessage with the default error template containing the exception details.str
: Catch all errors and return a ToolMessage with this custom error message string.type[Exception]
: Only catch exceptions with the specified type and return the default error message for it.tuple[type[Exception], ...]
: Only catch exceptions with the specified types and return default error messages for them.Callable[..., str]
: Catch exceptions matching the callable’s signature and return the string result of calling it with the exception.False
: Disable error handling entirely, allowing exceptions to propagate.
handle_tool_errors
defaults to a callable _default_handle_tool_errors
that:
- catches tool invocation errors
ToolInvocationError
(due to invalid arguments provided by the model) and returns a descriptive error message - ignores tool execution errors (they will be re-raised with the template string
TOOL_CALL_ERROR_TEMPLATE = "Error: {error}\n Please fix your mistakes."
)
Use with create_agent()
We recommend that you familiarize yourself with
create_agent()
before covering this section. Read more about agents.ToolNode
directly to create_agent()
:
ToolNode
to create_agent()
, the agent uses your exact configuration including error handling, custom names, and tags. This is useful when you need fine-grained control over tool execution behavior.
State, context, and memory
Accessing agent state inside a tool
Accessing agent state inside a tool
state
: The agent maintains state throughout its execution - this includes messages, custom fields, and any data your tools need to track. State flows through the graph and can be accessed and modified by tools.InjectedState
: An annotation that allows tools to access the current graph state without exposing it to the LLM. This lets tools read information like message history or custom state fields while keeping the tool’s schema simple.InjectedState
annotation:State-injected arguments are hidden from the model. For the example above, the model only sees
pref_name
in the tool schema - preferences
is not included in the request.Updating agent state inside a tool
Updating agent state inside a tool
Command
: A special return type that tools can use to update the agent’s state or control the graph’s execution flow. Instead of just returning data, tools can return Command
s to modify state or direct the agent to specific nodes.Command
to update the agent state:Accessing runtime context inside a tool
Accessing runtime context inside a tool
runtime
: The execution environment of your agent, containing immutable configuration and contextual data that persists throughout the agent’s execution (e.g., user IDs, session details, or application-specific configuration).get_runtime
:Accessing long-term memory inside a tool
Accessing long-term memory inside a tool
store
: LangChain’s persistence layer. An agent’s long-term memory store, e.g. user-specific or application-specific data stored across conversations.get_store
:Updating long-term memory inside a tool
Updating long-term memory inside a tool
To update long-term memory, you can use the
.put()
method of InMemoryStore
. A complete example of persistent memory across sessions: