The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
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.pyindex 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 BaseStorefrom langgraph.types import Checkpointer- from langchain.tools.tool_node import ToolCallHandler, ToolCallRequest+ from langchain.tools.tool_node import ToolCallRequest, ToolCallWrapperSTRUCTURED_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 = Noneif 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 toolstool_node: ToolNode | None = None@@ -598,7 +598,7 @@ def create_agent( # noqa: PLR0915# Only create ToolNode if we have client-side toolstool_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_toolselse None)diff --git a/libs/langchain_v1/langchain/tools/tool_node.py b/libs/langchain_v1/langchain/tools/tool_node.pyindex 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_errorsself._messages_key = messages_key- self._on_tool_call = on_tool_call+ self._wrap_tool_call = wrap_tool_callfor 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 directlyreturn 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 callabletry:- 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 exceptionif 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 directlyreturn 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 asynctry:- 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 resultexcept Exception as e:- # Handler threw an exception+ # Wrapper threw an exceptionif 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.pyindex 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.pyindex 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 messagesresult = 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 += 1return 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"] += 10return 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 normallyreturn 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 normallyreturn 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 responsereturn 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 toolreturn 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 APIactual_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 APIactual_state = {