Skip to content

The agent engineering platform.

chore(langchain_v1): update on_tool_call to wrap_tool (#33410)

Eugene Yurtsev74983f8a96c0
diff --git a/libs/langchain_v1/langchain/agents/factory.py b/libs/langchain_v1/langchain/agents/factory.py
index 84aaa60a8b..daca6aeb56 100644
--- a/libs/langchain_v1/langchain/agents/factory.py
+++ b/libs/langchain_v1/langchain/agents/factory.py
@@ -59,7 +59,7 @@ if TYPE_CHECKING:
from langgraph.store.base import BaseStore
from langgraph.types import Checkpointer
- from langchain.tools.tool_node import ToolCallHandler, ToolCallRequest
+ from langchain.tools.tool_node import ToolCallRequest, ToolCallWrapper
STRUCTURED_OUTPUT_ERROR_TEMPLATE = "Error: {error}\n Please fix your mistakes."
@@ -403,30 +403,30 @@ def _handle_structured_output_error(
return False, ""
-def _chain_tool_call_handlers(
- handlers: Sequence[ToolCallHandler],
-) -> ToolCallHandler | None:
- """Compose handlers into middleware stack (first = outermost).
+def _chain_tool_call_wrappers(
+ wrappers: Sequence[ToolCallWrapper],
+) -> ToolCallWrapper | None:
+ """Compose wrappers into middleware stack (first = outermost).
Args:
- handlers: Handlers in middleware order.
+ wrappers: Wrappers in middleware order.
Returns:
- Composed handler, or None if empty.
+ Composed wrapper, or None if empty.
Example:
- handler = _chain_tool_call_handlers([auth, cache, retry])
+ wrapper = _chain_tool_call_wrappers([auth, cache, retry])
# Request flows: auth -> cache -> retry -> tool
# Response flows: tool -> retry -> cache -> auth
"""
- if not handlers:
+ if not wrappers:
return None
- if len(handlers) == 1:
- return handlers[0]
+ if len(wrappers) == 1:
+ return wrappers[0]
- def compose_two(outer: ToolCallHandler, inner: ToolCallHandler) -> ToolCallHandler:
- """Compose two handlers where outer wraps inner."""
+ def compose_two(outer: ToolCallWrapper, inner: ToolCallWrapper) -> ToolCallWrapper:
+ """Compose two wrappers where outer wraps inner."""
def composed(
request: ToolCallRequest,
@@ -441,10 +441,10 @@ def _chain_tool_call_handlers(
return composed
- # Chain all handlers: first -> second -> ... -> last
- result = handlers[-1]
- for handler in reversed(handlers[:-1]):
- result = compose_two(handler, result)
+ # Chain all wrappers: first -> second -> ... -> last
+ result = wrappers[-1]
+ for wrapper in reversed(wrappers[:-1]):
+ result = compose_two(wrapper, result)
return result
@@ -582,10 +582,10 @@ def create_agent( # noqa: PLR0915
]
# Chain all wrap_tool_call handlers into a single composed handler
- wrap_tool_call_handler = None
+ wrap_tool_call_wrapper = None
if middleware_w_wrap_tool_call:
- handlers = [m.wrap_tool_call for m in middleware_w_wrap_tool_call]
- wrap_tool_call_handler = _chain_tool_call_handlers(handlers)
+ wrappers = [m.wrap_tool_call for m in middleware_w_wrap_tool_call]
+ wrap_tool_call_wrapper = _chain_tool_call_wrappers(wrappers)
# Setup tools
tool_node: ToolNode | None = None
@@ -598,7 +598,7 @@ def create_agent( # noqa: PLR0915
# Only create ToolNode if we have client-side tools
tool_node = (
- ToolNode(tools=available_tools, on_tool_call=wrap_tool_call_handler)
+ ToolNode(tools=available_tools, wrap_tool_call=wrap_tool_call_wrapper)
if available_tools
else None
)
diff --git a/libs/langchain_v1/langchain/tools/tool_node.py b/libs/langchain_v1/langchain/tools/tool_node.py
index d856aef94a..fc00fd6b40 100644
--- a/libs/langchain_v1/langchain/tools/tool_node.py
+++ b/libs/langchain_v1/langchain/tools/tool_node.py
@@ -120,13 +120,13 @@ class ToolCallRequest:
runtime: Any
-ToolCallHandler = Callable[
+ToolCallWrapper = Callable[
[ToolCallRequest, Callable[[ToolCallRequest], ToolMessage | Command]],
ToolMessage | Command,
]
-"""Handler-based tool call interceptor with multi-call support.
+"""Wrapper for tool call execution with multi-call support.
-Handler receives:
+Wrapper receives:
request: ToolCallRequest with tool_call, tool, state, and runtime.
execute: Callable to execute the tool (CAN BE CALLED MULTIPLE TIMES).
@@ -499,7 +499,7 @@ class ToolNode(RunnableCallable):
| type[Exception]
| tuple[type[Exception], ...] = _default_handle_tool_errors,
messages_key: str = "messages",
- on_tool_call: ToolCallHandler | None = None,
+ wrap_tool_call: ToolCallWrapper | None = None,
) -> None:
"""Initialize ToolNode with tools and configuration.
@@ -509,10 +509,9 @@ class ToolNode(RunnableCallable):
tags: Optional metadata tags.
handle_tool_errors: Error handling configuration.
messages_key: State key containing messages.
- on_tool_call: Generator handler to intercept tool execution. Receives
- ToolCallRequest, yields requests, messages, or Commands; receives
- ToolMessage or Command via .send(). Final result is last value sent to
- handler. Enables retries, caching, request modification, and control flow.
+ wrap_tool_call: Wrapper function to intercept tool execution. Receives
+ ToolCallRequest and execute callable, returns ToolMessage or Command.
+ Enables retries, caching, request modification, and control flow.
"""
super().__init__(self._func, self._afunc, name=name, tags=tags, trace=False)
self._tools_by_name: dict[str, BaseTool] = {}
@@ -520,7 +519,7 @@ class ToolNode(RunnableCallable):
self._tool_to_store_arg: dict[str, str | None] = {}
self._handle_tool_errors = handle_tool_errors
self._messages_key = messages_key
- self._on_tool_call = on_tool_call
+ self._wrap_tool_call = wrap_tool_call
for tool in tools:
if not isinstance(tool, BaseTool):
tool_ = create_tool(cast("type[BaseTool]", tool))
@@ -714,7 +713,7 @@ class ToolNode(RunnableCallable):
input: list[AnyMessage] | dict[str, Any] | BaseModel,
runtime: Any,
) -> ToolMessage | Command:
- """Execute single tool call with on_tool_call handler if configured.
+ """Execute single tool call with wrap_tool_call wrapper if configured.
Args:
call: Tool call dict.
@@ -742,8 +741,8 @@ class ToolNode(RunnableCallable):
runtime=runtime,
)
- if self._on_tool_call is None:
- # No handler - execute directly
+ if self._wrap_tool_call is None:
+ # No wrapper - execute directly
return self._execute_tool_sync(tool_request, input_type, config)
# Define execute callable that can be called multiple times
@@ -751,11 +750,11 @@ class ToolNode(RunnableCallable):
"""Execute tool with given request. Can be called multiple times."""
return self._execute_tool_sync(req, input_type, config)
- # Call handler with request and execute callable
+ # Call wrapper with request and execute callable
try:
- return self._on_tool_call(tool_request, execute)
+ return self._wrap_tool_call(tool_request, execute)
except Exception as e:
- # Handler threw an exception
+ # Wrapper threw an exception
if not self._handle_tool_errors:
raise
# Convert to error message
@@ -856,7 +855,7 @@ class ToolNode(RunnableCallable):
input: list[AnyMessage] | dict[str, Any] | BaseModel,
runtime: Any,
) -> ToolMessage | Command:
- """Execute single tool call asynchronously with on_tool_call handler if configured.
+ """Execute single tool call asynchronously with wrap_tool_call wrapper if configured.
Args:
call: Tool call dict.
@@ -884,8 +883,8 @@ class ToolNode(RunnableCallable):
runtime=runtime,
)
- if self._on_tool_call is None:
- # No handler - execute directly
+ if self._wrap_tool_call is None:
+ # No wrapper - execute directly
return await self._execute_tool_async(tool_request, input_type, config)
# Define async execute callable that can be called multiple times
@@ -893,14 +892,14 @@ class ToolNode(RunnableCallable):
"""Execute tool with given request. Can be called multiple times."""
return await self._execute_tool_async(req, input_type, config)
- # Call handler with request and execute callable
- # Note: handler is sync, but execute callable is async
+ # Call wrapper with request and execute callable
+ # Note: wrapper is sync, but execute callable is async
try:
- result = self._on_tool_call(tool_request, execute) # type: ignore[arg-type]
- # If result is a coroutine, await it (though handler should be sync)
+ result = self._wrap_tool_call(tool_request, execute) # type: ignore[arg-type]
+ # If result is a coroutine, await it (though wrapper should be sync)
return await result if hasattr(result, "__await__") else result
except Exception as e:
- # Handler threw an exception
+ # Wrapper threw an exception
if not self._handle_tool_errors:
raise
# Convert to error message
@@ -972,7 +971,7 @@ class ToolNode(RunnableCallable):
input: The input which may be raw state or ToolCallWithContext.
Returns:
- The actual state to pass to on_tool_call handlers.
+ The actual state to pass to wrap_tool_call wrappers.
"""
if isinstance(input, dict) and input.get("__type") == "tool_call_with_context":
return input["state"]
diff --git a/libs/langchain_v1/tests/unit_tests/agents/test_on_tool_call_middleware.py b/libs/langchain_v1/tests/unit_tests/agents/test_on_tool_call_middleware.py
index bdd01ed700..f9dbd4278c 100644
--- a/libs/langchain_v1/tests/unit_tests/agents/test_on_tool_call_middleware.py
+++ b/libs/langchain_v1/tests/unit_tests/agents/test_on_tool_call_middleware.py
@@ -368,15 +368,15 @@ def test_middleware_access_to_state() -> None:
{"configurable": {"thread_id": "test"}},
)
- # Middleware should have seen state (state is passed to on_tool_call)
+ # Middleware should have seen state (state is passed to wrap_tool)
assert len(state_seen) >= 1
-def test_middleware_without_on_tool_call() -> None:
- """Test that middleware without on_tool_call hook works normally."""
+def test_middleware_without_wrap_tool() -> None:
+ """Test that middleware without wrap_tool hook works normally."""
class NoOpMiddleware(AgentMiddleware):
- """Middleware without on_tool_call."""
+ """Middleware without wrap_tool."""
def before_model(self, state, runtime):
"""Just a dummy hook."""
diff --git a/libs/langchain_v1/tests/unit_tests/tools/test_on_tool_call.py b/libs/langchain_v1/tests/unit_tests/tools/test_on_tool_call.py
index f683e7909d..b67c689522 100644
--- a/libs/langchain_v1/tests/unit_tests/tools/test_on_tool_call.py
+++ b/libs/langchain_v1/tests/unit_tests/tools/test_on_tool_call.py
@@ -44,7 +44,7 @@ def test_passthrough_handler() -> None:
"""Simple passthrough handler."""
return execute(request)
- tool_node = ToolNode([add], on_tool_call=passthrough_handler)
+ tool_node = ToolNode([add], wrap_tool_call=passthrough_handler)
result = tool_node.invoke(
{
@@ -80,7 +80,7 @@ async def test_passthrough_handler_async() -> None:
"""Simple passthrough handler."""
return execute(request)
- tool_node = ToolNode([add], on_tool_call=passthrough_handler)
+ tool_node = ToolNode([add], wrap_tool_call=passthrough_handler)
result = await tool_node.ainvoke(
{
@@ -119,7 +119,7 @@ def test_modify_arguments() -> None:
return execute(request)
- tool_node = ToolNode([add], on_tool_call=modify_args_handler)
+ tool_node = ToolNode([add], wrap_tool_call=modify_args_handler)
result = tool_node.invoke(
{
@@ -154,7 +154,7 @@ def test_handler_validation_no_return() -> None:
"""Handler that executes and returns result."""
return execute(request)
- tool_node = ToolNode([add], on_tool_call=handler_with_explicit_none)
+ tool_node = ToolNode([add], wrap_tool_call=handler_with_explicit_none)
result = tool_node.invoke(
{
@@ -191,7 +191,7 @@ def test_handler_validation_no_yield() -> None:
# Don't call execute, just return None (invalid)
return None # type: ignore[return-value]
- tool_node = ToolNode([add], on_tool_call=bad_handler)
+ tool_node = ToolNode([add], wrap_tool_call=bad_handler)
# This will return None wrapped in messages
result = tool_node.invoke(
@@ -230,7 +230,9 @@ def test_handler_with_handle_tool_errors_true() -> None:
assert message.status == "error"
return message
- tool_node = ToolNode([failing_tool], on_tool_call=passthrough_handler, handle_tool_errors=True)
+ tool_node = ToolNode(
+ [failing_tool], wrap_tool_call=passthrough_handler, handle_tool_errors=True
+ )
result = tool_node.invoke(
{
@@ -267,7 +269,7 @@ def test_multiple_tool_calls_with_handler() -> None:
call_count += 1
return execute(request)
- tool_node = ToolNode([add], on_tool_call=counting_handler)
+ tool_node = ToolNode([add], wrap_tool_call=counting_handler)
result = tool_node.invoke(
{
@@ -341,7 +343,7 @@ async def test_handler_with_async_execution() -> None:
request.tool_call["args"]["b"] += 10
return execute(request)
- tool_node = ToolNode([async_add], on_tool_call=modifying_handler)
+ tool_node = ToolNode([async_add], wrap_tool_call=modifying_handler)
result = await tool_node.ainvoke(
{
@@ -381,7 +383,7 @@ def test_short_circuit_with_tool_message() -> None:
name=request.tool_call["name"],
)
- tool_node = ToolNode([add], on_tool_call=short_circuit_handler)
+ tool_node = ToolNode([add], wrap_tool_call=short_circuit_handler)
result = tool_node.invoke(
{
@@ -421,7 +423,7 @@ async def test_short_circuit_with_tool_message_async() -> None:
name=request.tool_call["name"],
)
- tool_node = ToolNode([add], on_tool_call=short_circuit_handler)
+ tool_node = ToolNode([add], wrap_tool_call=short_circuit_handler)
result = await tool_node.ainvoke(
{
@@ -468,7 +470,7 @@ def test_conditional_short_circuit() -> None:
# Odd: execute normally
return execute(request)
- tool_node = ToolNode([add], on_tool_call=conditional_handler)
+ tool_node = ToolNode([add], wrap_tool_call=conditional_handler)
# Test with even number (should be cached)
result1 = tool_node.invoke(
@@ -528,7 +530,7 @@ def test_direct_return_tool_message() -> None:
name=request.tool_call["name"],
)
- tool_node = ToolNode([add], on_tool_call=direct_return_handler)
+ tool_node = ToolNode([add], wrap_tool_call=direct_return_handler)
result = tool_node.invoke(
{
@@ -568,7 +570,7 @@ async def test_direct_return_tool_message_async() -> None:
name=request.tool_call["name"],
)
- tool_node = ToolNode([add], on_tool_call=direct_return_handler)
+ tool_node = ToolNode([add], wrap_tool_call=direct_return_handler)
result = await tool_node.ainvoke(
{
@@ -613,7 +615,7 @@ def test_conditional_direct_return() -> None:
# Execute tool normally
return execute(request)
- tool_node = ToolNode([add], on_tool_call=conditional_handler)
+ tool_node = ToolNode([add], wrap_tool_call=conditional_handler)
# Test with zero (should return directly)
result1 = tool_node.invoke(
@@ -673,7 +675,7 @@ def test_handler_can_throw_exception() -> None:
raise TypeError(msg)
return response
- tool_node = ToolNode([add], on_tool_call=throwing_handler, handle_tool_errors=True)
+ tool_node = ToolNode([add], wrap_tool_call=throwing_handler, handle_tool_errors=True)
result = tool_node.invoke(
{
@@ -712,7 +714,7 @@ def test_handler_throw_without_handle_errors() -> None:
msg = "Handler error"
raise ValueError(msg)
- tool_node = ToolNode([add], on_tool_call=throwing_handler, handle_tool_errors=False)
+ tool_node = ToolNode([add], wrap_tool_call=throwing_handler, handle_tool_errors=False)
with pytest.raises(ValueError, match="Handler error"):
tool_node.invoke(
@@ -757,7 +759,7 @@ def test_retry_middleware_with_exception() -> None:
# If we exhausted retries, return last response
return response
- tool_node = ToolNode([add], on_tool_call=retry_handler)
+ tool_node = ToolNode([add], wrap_tool_call=retry_handler)
result = tool_node.invoke(
{
@@ -796,7 +798,7 @@ async def test_async_handler_can_throw_exception() -> None:
msg = "Async handler rejected the request"
raise ValueError(msg)
- tool_node = ToolNode([add], on_tool_call=throwing_handler, handle_tool_errors=True)
+ tool_node = ToolNode([add], wrap_tool_call=throwing_handler, handle_tool_errors=True)
result = await tool_node.ainvoke(
{
@@ -836,7 +838,7 @@ def test_handler_cannot_yield_multiple_tool_messages() -> None:
"""Handler that returns once (as all handlers do)."""
return execute(request)
- tool_node = ToolNode([add], on_tool_call=single_return_handler)
+ tool_node = ToolNode([add], wrap_tool_call=single_return_handler)
result = tool_node.invoke(
{
@@ -873,7 +875,7 @@ def test_handler_cannot_yield_request_after_tool_message() -> None:
# Return cached result (short-circuit)
return ToolMessage("cached", tool_call_id=request.tool_call["id"], name="add")
- tool_node = ToolNode([add], on_tool_call=single_return_handler)
+ tool_node = ToolNode([add], wrap_tool_call=single_return_handler)
result = tool_node.invoke(
{
@@ -908,7 +910,7 @@ def test_handler_can_short_circuit_with_command() -> None:
# Short-circuit with Command instead of executing tool
return Command(goto="end")
- tool_node = ToolNode([add], on_tool_call=command_handler)
+ tool_node = ToolNode([add], wrap_tool_call=command_handler)
result = tool_node.invoke(
{
@@ -946,7 +948,7 @@ def test_handler_cannot_yield_multiple_commands() -> None:
"""Handler that returns Command once."""
return Command(goto="step1")
- tool_node = ToolNode([add], on_tool_call=single_command_handler)
+ tool_node = ToolNode([add], wrap_tool_call=single_command_handler)
result = tool_node.invoke(
{
@@ -984,7 +986,7 @@ def test_handler_cannot_yield_request_after_command() -> None:
"""Handler that returns Command."""
return Command(goto="somewhere")
- tool_node = ToolNode([add], on_tool_call=command_handler)
+ tool_node = ToolNode([add], wrap_tool_call=command_handler)
result = tool_node.invoke(
{
@@ -1025,7 +1027,7 @@ def test_tool_returning_command_sent_to_handler() -> None:
received_commands.append(result)
return result
- tool_node = ToolNode([command_tool], on_tool_call=command_inspector_handler)
+ tool_node = ToolNode([command_tool], wrap_tool_call=command_inspector_handler)
result = tool_node.invoke(
{
@@ -1069,7 +1071,7 @@ def test_handler_can_modify_command_from_tool() -> None:
return Command(goto=f"modified_{result.goto}")
return result
- tool_node = ToolNode([command_tool], on_tool_call=command_modifier_handler)
+ tool_node = ToolNode([command_tool], wrap_tool_call=command_modifier_handler)
result = tool_node.invoke(
{
@@ -1107,7 +1109,7 @@ def test_state_extraction_with_dict_input() -> None:
state_seen.append(request.state)
return execute(request)
- tool_node = ToolNode([add], on_tool_call=state_inspector_handler)
+ tool_node = ToolNode([add], wrap_tool_call=state_inspector_handler)
input_state = {
"messages": [
@@ -1142,7 +1144,7 @@ def test_state_extraction_with_list_input() -> None:
state_seen.append(request.state)
return execute(request)
- tool_node = ToolNode([add], on_tool_call=state_inspector_handler)
+ tool_node = ToolNode([add], wrap_tool_call=state_inspector_handler)
input_state = [
AIMessage(
@@ -1176,7 +1178,7 @@ def test_state_extraction_with_tool_call_with_context() -> None:
state_seen.append(request.state)
return execute(request)
- tool_node = ToolNode([add], on_tool_call=state_inspector_handler)
+ tool_node = ToolNode([add], wrap_tool_call=state_inspector_handler)
# Simulate ToolCallWithContext as used by create_agent with Send API
actual_state = {
@@ -1219,7 +1221,7 @@ async def test_state_extraction_with_tool_call_with_context_async() -> None:
state_seen.append(request.state)
return execute(request)
- tool_node = ToolNode([add], on_tool_call=state_inspector_handler)
+ tool_node = ToolNode([add], wrap_tool_call=state_inspector_handler)
# Simulate ToolCallWithContext as used by create_agent with Send API
actual_state = {