The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
chore(langchain_v1): update on_tool_call to regular callbacks (#33364)
Eugene Yurtsevc2435eeca5fa
diff --git a/libs/langchain_v1/langchain/agents/factory.py b/libs/langchain_v1/langchain/agents/factory.pyindex c370661e7c..e9214313d1 100644--- a/libs/langchain_v1/langchain/agents/factory.py+++ b/libs/langchain_v1/langchain/agents/factory.py@@ -51,7 +51,7 @@ from langchain.tools import ToolNodefrom langchain.tools.tool_node import ToolCallWithContextif TYPE_CHECKING:- from collections.abc import Callable, Generator, Sequence+ from collections.abc import Callable, Sequencefrom langchain_core.runnables import Runnablefrom langgraph.cache.base import BaseCache@@ -402,61 +402,15 @@ def _chain_tool_call_handlers("""Compose two handlers where outer wraps inner."""def composed(- request: ToolCallRequest, state: Any, runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:- outer_gen = outer(request, state, runtime)-- # Initialize outer generator- try:- outer_request_or_result = next(outer_gen)- except StopIteration:- msg = "outer handler must yield at least once"- raise ValueError(msg)-- # Outer retry loop- while True:- # If outer yielded a ToolMessage or Command, bypass inner and yield directly- if isinstance(outer_request_or_result, (ToolMessage, Command)):- result = yield outer_request_or_result- try:- outer_request_or_result = outer_gen.send(result)- except StopIteration:- # Outer ended - final result is what we sent to it- return- continue-- inner_gen = inner(outer_request_or_result, state, runtime)- last_sent_to_inner: ToolMessage | Command | None = None-- # Initialize inner generator- try:- inner_request_or_result = next(inner_gen)- except StopIteration:- msg = "inner handler must yield at least once"- raise ValueError(msg)-- # Inner retry loop- while True:- # Yield to actual tool execution- result = yield inner_request_or_result- last_sent_to_inner = result-- # Send result to inner- try:- inner_request_or_result = inner_gen.send(result)- except StopIteration:- # Inner is done - final result from inner is last_sent_to_inner- break-- # Send inner's final result to outer- if last_sent_to_inner is None:- msg = "inner handler ended without receiving any result"- raise ValueError(msg)- try:- outer_request_or_result = outer_gen.send(last_sent_to_inner)- except StopIteration:- # Outer is done - final result is what we sent to it- return+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:+ # Create a callable that invokes inner with the original execute+ def call_inner(req: ToolCallRequest) -> ToolMessage | Command:+ return inner(req, execute)++ # Outer can call call_inner multiple times+ return outer(request, call_inner)return composeddiff --git a/libs/langchain_v1/langchain/agents/middleware/types.py b/libs/langchain_v1/langchain/agents/middleware/types.pyindex e4333356dd..0db65ac7e7 100644--- a/libs/langchain_v1/langchain/agents/middleware/types.py+++ b/libs/langchain_v1/langchain/agents/middleware/types.py@@ -2,7 +2,7 @@from __future__ import annotations-from collections.abc import Awaitable, Callable, Generator+from collections.abc import Awaitable, Callablefrom dataclasses import dataclass, fieldfrom inspect import iscoroutinefunctionfrom typing import (@@ -291,42 +291,71 @@ class AgentMiddleware(Generic[StateT, ContextT]):def on_tool_call(self,request: ToolCallRequest,- state: StateT, # noqa: ARG002- runtime: Runtime[ContextT], # noqa: ARG002- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Intercept tool execution for retries, monitoring, or modification.Multiple middleware compose automatically (first defined = outermost).Exceptions propagate unless handle_tool_errors is configured on ToolNode.Args:- request: Tool call request with call dict and BaseTool instance.- state: Current agent state.- runtime: LangGraph runtime.+ request: Tool call request with call dict, BaseTool, state, and runtime.+ Access state via request.state and runtime via request.runtime.+ handler: Callable to execute the tool (can be called multiple times).++ Returns:+ ToolMessage or Command (the final result).- Yields:- ToolCallRequest (execute tool), ToolMessage (cached result),- or Command (control flow).+ The handler callable can be invoked multiple times for retry logic.+ Each call to handler is independent and stateless.- Receives:- ToolMessage or Command via .send() after execution.+ Examples:+ Passthrough (execute once):++ def on_tool_call(self, request, handler):+ return handler(request)- Example:- Modify request:+ Modify request before execution:- def on_tool_call(self, request, state, runtime):+ def on_tool_call(self, request, handler):request.tool_call["args"]["value"] *= 2- yield request+ return handler(request)- Retry on error:+ Retry on error (call handler multiple times):- def on_tool_call(self, request, state, runtime):+ def on_tool_call(self, request, handler):for attempt in range(3):- response = yield request- if valid(response) or attempt == 2:- return+ try:+ result = handler(request)+ if is_valid(result):+ return result+ except Exception:+ if attempt == 2:+ raise+ return result++ Conditional retry based on response:++ def on_tool_call(self, request, handler):+ for attempt in range(3):+ result = handler(request)+ if isinstance(result, ToolMessage) and result.status != "error":+ return result+ if attempt < 2:+ continue+ return result++ Access state and runtime:++ def on_tool_call(self, request, handler):+ # Access state from request+ messages = request.state.get("messages", [])+ # Access runtime from request+ if request.runtime:+ thread_id = request.runtime.config.get("configurable", {}).get("thread_id")+ return handler(request)"""- yield request+ raise NotImplementedErrorclass _CallableWithStateAndRuntime(Protocol[StateT_contra, ContextT]):diff --git a/libs/langchain_v1/langchain/tools/tool_node.py b/libs/langchain_v1/langchain/tools/tool_node.pyindex 0fc895be3a..4eed09b650 100644--- a/libs/langchain_v1/langchain/tools/tool_node.py+++ b/libs/langchain_v1/langchain/tools/tool_node.py@@ -38,7 +38,7 @@ from __future__ import annotationsimport asyncioimport inspectimport json-from collections.abc import Callable, Generator+from collections.abc import Callablefrom copy import copy, deepcopyfrom dataclasses import dataclass, replacefrom types import UnionType@@ -110,61 +110,82 @@ class ToolCallRequest:Attributes:tool_call: Tool call dict with name, args, and id from model output.tool: BaseTool instance to be invoked.+ state: Agent state (dict, list, or BaseModel).+ runtime: LangGraph runtime context (optional, None if outside graph)."""tool_call: ToolCalltool: BaseTool+ state: Any+ runtime: AnyToolCallHandler = Callable[- [ToolCallRequest, Any, Any],- Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None],+ [ToolCallRequest, Callable[[ToolCallRequest], ToolMessage | Command]],+ ToolMessage | Command,]-"""Generator-based handler for intercepting tool execution.+"""Handler-based tool call interceptor with multi-call support.-Receives (request, state, runtime), yields ToolCallRequest/ToolMessage/Command,-receives results via .send(). Returns None; the last value sent becomes the result.+Handler receives:+ request: ToolCallRequest with tool_call, tool, state, and runtime.+ execute: Callable to execute the tool (CAN BE CALLED MULTIPLE TIMES).-Exceptions propagate unless handle_tool_errors is configured on ToolNode.+Returns:+ ToolMessage or Command (the final result).-Type Parameters:- The handler signature is ``(ToolCallRequest, Any, Any) -> Generator[...]``:+The execute callable can be invoked multiple times for retry logic,+with potentially modified requests each time. Each call to execute+is independent and stateless.- - **First Any (state)**: Typed as ``Any`` because ToolNode supports multiple input- formats (list, dict, BaseModel, ToolCallWithContext). When used in ``create_agent``,- state will be the agent's StateT (dict with "messages" key). When used standalone,- state matches the input type passed to ToolNode.+Note:+ When implementing middleware for ``create_agent``, use+ ``AgentMiddleware.on_tool_call`` which provides properly typed+ state parameter for better type safety.- - **Second Any (runtime)**: Typed as ``Any`` because runtime is optional and only- available when ToolNode runs within a LangGraph graph. Will be ``None`` in- standalone usage or unit tests.+Examples:+ Passthrough (execute once):- Note:- When implementing middleware for ``create_agent``, use- ``AgentMiddleware.on_tool_call`` which has properly typed ``state: StateT``- parameter for better type safety.+ def handler(request, execute):+ return execute(request)-Example:- Passthrough:+ Modify request before execution:- def handler(request, state, runtime):- yield request+ def handler(request, execute):+ request.tool_call["args"]["value"] *= 2+ return execute(request)- Cache result:+ Retry on error (execute multiple times):- def handler(request, state, runtime):- if cached := get_cache(request):- yield ToolMessage(content=cached, tool_call_id=request.tool_call["id"])- else:- yield request+ def handler(request, execute):+ for attempt in range(3):+ try:+ result = execute(request)+ if is_valid(result):+ return result+ except Exception:+ if attempt == 2:+ raise+ return result- Retry with validation:+ Conditional retry based on response:- def handler(request, state, runtime):+ def handler(request, execute):for attempt in range(3):- response = yield request- if valid(response) or attempt == 2:- return+ result = execute(request)+ if isinstance(result, ToolMessage) and result.status != "error":+ return result+ if attempt < 2:+ continue+ return result++ Cache/short-circuit without calling execute:++ def handler(request, execute):+ if cached := get_cache(request):+ return ToolMessage(content=cached, tool_call_id=request.tool_call["id"])+ result = execute(request)+ save_cache(request, result)+ return result"""@@ -685,7 +706,7 @@ class ToolNode(RunnableCallable):msg = f"Tool {call['name']} returned unexpected type: {type(response)}"raise TypeError(msg)- def _run_one( # noqa: PLR0912+ def _run_one(self,call: ToolCall,input_type: Literal["list", "dict", "tool_calls"],@@ -710,105 +731,41 @@ class ToolNode(RunnableCallable):tool = self.tools_by_name[call["name"]]- # Create the tool request+ # Extract state from ToolCallWithContext if present+ state = self._extract_state(input)++ # Create the tool request with state and runtimetool_request = ToolCallRequest(tool_call=call,tool=tool,+ state=state,+ runtime=runtime,)if self._on_tool_call is None:+ # No handler - execute directlyreturn self._execute_tool_sync(tool_request, input_type, config)- # Extract state from ToolCallWithContext if present- state = self._extract_state(input)-- # Generator protocol: start generator, send messages, receive requests/messages- gen = self._on_tool_call(tool_request, state, runtime)- last_sent_value: ToolMessage | Command | None = None- first_yield = True- short_circuited_immediately = False+ # Define execute callable that can be called multiple times+ def execute(req: ToolCallRequest) -> ToolMessage | Command:+ """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 callabletry:- yielded = next(gen)- except StopIteration:- # Handler ended immediately without yielding- msg = (- "on_tool_call handler must yield at least once. "- "The final result is the last value sent to the handler."+ return self._on_tool_call(tool_request, execute)+ except Exception as e:+ # Handler threw an exception+ if not self._handle_tool_errors:+ raise+ # Convert to error message+ content = _handle_tool_error(e, flag=self._handle_tool_errors)+ return ToolMessage(+ content=content,+ name=tool_request.tool_call["name"],+ tool_call_id=tool_request.tool_call["id"],+ status="error",)- raise ValueError(msg)-- # Handler yielded - check if short-circuit (ToolMessage/Command) or normal (ToolCallRequest)- while True:- if isinstance(yielded, (ToolMessage, Command)):- # Handler yielded ToolMessage or Command- if first_yield:- # First yield is ToolMessage/Command = immediate short-circuit- short_circuited_immediately = True- elif short_circuited_immediately:- # Already short-circuited immediately, cannot yield again- msg = (- "on_tool_call handler yielded multiple values after short-circuit. "- "After yielding ToolMessage or Command as first yield, handler must "- "end or throw."- )- raise ValueError(msg)- # Otherwise: this is response modification after execution - allowed-- first_yield = False-- # Send it back to generator- last_sent_value = yielded- try:- yielded = gen.send(yielded)- # If generator yields again, continue the loop- except StopIteration:- # Handler ended - return the last value we sent to it- return last_sent_value- except Exception as e:- # Handler threw an exception- if not self._handle_tool_errors:- raise- # Convert to error message- content = _handle_tool_error(e, flag=self._handle_tool_errors)- return ToolMessage(- content=content,- name=tool_request.tool_call["name"],- tool_call_id=tool_request.tool_call["id"],- status="error",- )- else:- # Normal flow: execute the tool with the request- if short_circuited_immediately:- msg = (- "on_tool_call handler yielded ToolCallRequest after short-circuit. "- "After short-circuit, handler must end or throw."- )- raise ValueError(msg)-- first_yield = False-- tool_message_or_command = self._execute_tool_sync(yielded, input_type, config)-- # Send result back to generator (ToolMessage or Command)- last_sent_value = tool_message_or_command- try:- yielded = gen.send(tool_message_or_command)- except StopIteration:- # Handler ended - return the last value we sent to it- return last_sent_value- except Exception as e:- # Handler threw an exception- if not self._handle_tool_errors:- raise- # Convert to error message- content = _handle_tool_error(e, flag=self._handle_tool_errors)- return ToolMessage(- content=content,- name=tool_request.tool_call["name"],- tool_call_id=tool_request.tool_call["id"],- status="error",- )async def _execute_tool_async(self,@@ -891,7 +848,7 @@ class ToolNode(RunnableCallable):msg = f"Tool {call['name']} returned unexpected type: {type(response)}"raise TypeError(msg)- async def _arun_one( # noqa: PLR0912+ async def _arun_one(self,call: ToolCall,input_type: Literal["list", "dict", "tool_calls"],@@ -916,107 +873,44 @@ class ToolNode(RunnableCallable):tool = self.tools_by_name[call["name"]]- # Create the tool request+ # Extract state from ToolCallWithContext if present+ state = self._extract_state(input)++ # Create the tool request with state and runtimetool_request = ToolCallRequest(tool_call=call,tool=tool,+ state=state,+ runtime=runtime,)if self._on_tool_call is None:+ # No handler - execute directlyreturn await self._execute_tool_async(tool_request, input_type, config)- # Extract state from ToolCallWithContext if present- state = self._extract_state(input)-- # Generator protocol: handler is sync generator, tool execution is async- gen = self._on_tool_call(tool_request, state, runtime)- last_sent_value: ToolMessage | Command | None = None- first_yield = True- short_circuited_immediately = False+ # Define async execute callable that can be called multiple times+ async def execute(req: ToolCallRequest) -> ToolMessage | Command:+ """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 asynctry:- yielded = next(gen)- except StopIteration:- # Handler ended immediately without yielding- msg = (- "on_tool_call handler must yield at least once. "- "The final result is the last value sent to the handler."+ result = self._on_tool_call(tool_request, execute) # type: ignore[arg-type]+ # If result is a coroutine, await it (though handler should be sync)+ return await result if hasattr(result, "__await__") else result+ except Exception as e:+ # Handler threw an exception+ if not self._handle_tool_errors:+ raise+ # Convert to error message+ content = _handle_tool_error(e, flag=self._handle_tool_errors)+ return ToolMessage(+ content=content,+ name=tool_request.tool_call["name"],+ tool_call_id=tool_request.tool_call["id"],+ status="error",)- raise ValueError(msg)-- # Handler yielded - check if short-circuit (ToolMessage/Command) or normal (ToolCallRequest)- while True:- if isinstance(yielded, (ToolMessage, Command)):- # Handler yielded ToolMessage or Command- if first_yield:- # First yield is ToolMessage/Command = immediate short-circuit- short_circuited_immediately = True- elif short_circuited_immediately:- # Already short-circuited immediately, cannot yield again- msg = (- "on_tool_call handler yielded multiple values after short-circuit. "- "After yielding ToolMessage or Command as first yield, handler must "- "end or throw."- )- raise ValueError(msg)- # Otherwise: this is response modification after execution - allowed-- first_yield = False-- # Send it back to generator- last_sent_value = yielded- try:- yielded = gen.send(yielded)- # If generator yields again, continue the loop- except StopIteration:- # Handler ended - return the last value we sent to it- return last_sent_value- except Exception as e:- # Handler threw an exception- if not self._handle_tool_errors:- raise- # Convert to error message- content = _handle_tool_error(e, flag=self._handle_tool_errors)- return ToolMessage(- content=content,- name=tool_request.tool_call["name"],- tool_call_id=tool_request.tool_call["id"],- status="error",- )- else:- # Normal flow: execute the tool with the request- if short_circuited_immediately:- msg = (- "on_tool_call handler yielded ToolCallRequest after short-circuit. "- "After short-circuit, handler must end or throw."- )- raise ValueError(msg)-- first_yield = False-- tool_message_or_command = await self._execute_tool_async(- yielded, input_type, config- )-- # Send result back to generator (ToolMessage or Command)- last_sent_value = tool_message_or_command- try:- yielded = gen.send(tool_message_or_command)- except StopIteration:- # Handler ended - return the last value we sent to it- return last_sent_value- except Exception as e:- # Handler threw an exception- if not self._handle_tool_errors:- raise- # Convert to error message- content = _handle_tool_error(e, flag=self._handle_tool_errors)- return ToolMessage(- content=content,- name=tool_request.tool_call["name"],- tool_call_id=tool_request.tool_call["id"],- status="error",- )def _parse_input(self,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 2c329985c7..bbe22082ef 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@@ -1,6 +1,6 @@"""Unit tests for on_tool_call middleware integration."""-from collections.abc import Generator+from collections.abc import Callableimport pytestfrom langchain_core.messages import HumanMessage, ToolCall, ToolMessage@@ -41,11 +41,14 @@ def test_simple_logging_middleware() -> None:"""Middleware that logs tool calls."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest, ToolMessage, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:call_log.append(f"before_{request.tool.name}")- response = yield request+ response = handler(request)call_log.append(f"after_{request.tool.name}")+ return responsemodel = FakeToolCallingModel(tool_calls=[@@ -79,13 +82,15 @@ def test_request_modification_middleware() -> None:"""Middleware that modifies tool arguments."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest, ToolMessage, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:# Add prefix to queryif request.tool.name == "search":original_query = request.tool_call["args"]["query"]request.tool_call["args"]["query"] = f"modified: {original_query}"- response = yield request+ return handler(request)model = FakeToolCallingModel(tool_calls=[@@ -119,9 +124,11 @@ def test_response_inspection_middleware() -> None:"""Middleware that inspects responses."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest, ToolMessage, None]:- response = yield request+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:+ response = handler(request)# Record response detailsif isinstance(response, ToolMessage):@@ -131,6 +138,7 @@ def test_response_inspection_middleware() -> None:"content": response.content,})+ return responsemodel = FakeToolCallingModel(tool_calls=[@@ -166,13 +174,15 @@ def test_conditional_retry_middleware() -> None:"""Middleware that retries based on response content."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest, ToolMessage, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:nonlocal call_countmax_retries = 2for attempt in range(max_retries):- response = yield request+ response = handler(request)call_count += 1# Check if we should retry based on content@@ -185,6 +195,9 @@ def test_conditional_retry_middleware() -> None:continue# Return on success or final attempt+ return response++ return response# Use search tool which always succeeds - we'll modify request to test retry logicmodel = FakeToolCallingModel(@@ -220,21 +233,27 @@ def test_multiple_middleware_composition() -> None:"""Outer middleware."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest, ToolMessage, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:call_log.append("outer_before")- response = yield request+ response = handler(request)call_log.append("outer_after")+ return responseclass InnerMiddleware(AgentMiddleware):"""Inner middleware."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest, ToolMessage, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:call_log.append("inner_before")- response = yield request+ response = handler(request)call_log.append("inner_after")+ return responsemodel = FakeToolCallingModel(tool_calls=[@@ -269,10 +288,12 @@ def test_middleware_with_multiple_tool_calls() -> None:"""Middleware that logs tool calls."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest, ToolMessage, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:call_log.append(request.tool.name)- response = yield request+ return handler(request)model = FakeToolCallingModel(tool_calls=[@@ -313,9 +334,12 @@ def test_middleware_access_to_state() -> None:"""Middleware that inspects state."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest, ToolMessage, None]:- # Record state - state could be dict or list+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:+ # Record state - state is now in request.state+ state = request.stateif state is not None:if isinstance(state, dict) and "messages" in state:state_seen.append(("dict", len(state["messages"])))@@ -323,7 +347,7 @@ def test_middleware_access_to_state() -> None:state_seen.append(("list", len(state)))else:state_seen.append(("other", type(state).__name__))- response = yield request+ return handler(request)model = FakeToolCallingModel(tool_calls=[@@ -383,36 +407,41 @@ def test_middleware_without_on_tool_call() -> None:def test_generator_composition_immediate_outer_return() -> None:- """Test composition when outer generator returns after first yield."""+ """Test composition when outer handler intercepts response."""call_log = []class ImmediateReturnMiddleware(AgentMiddleware):- """Outer middleware that returns after first yield."""+ """Outer middleware that intercepts and modifies response."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest, ToolMessage, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:call_log.append("outer_yield")- # Yield once, receive response from inner- response = yield request+ # Call handler, receive response from inner+ response = handler(request)call_log.append("outer_got_response")- # Yield modified message to make it the final result+ # Return modified messagemodified = ToolMessage(content="Outer intercepted",tool_call_id=request.tool_call["id"],name=request.tool_call["name"],)- yield modified+ return modifiedclass InnerMiddleware(AgentMiddleware):"""Inner middleware."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest, ToolMessage, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:call_log.append("inner_called")- response = yield request+ response = handler(request)call_log.append("inner_got_response")+ return responsemodel = FakeToolCallingModel(tool_calls=[@@ -442,17 +471,19 @@ def test_generator_composition_immediate_outer_return() -> None:def test_generator_composition_short_circuit() -> None:- """Test composition when inner generator short-circuits after first yield."""+ """Test composition when inner handler short-circuits."""call_log = []class OuterMiddleware(AgentMiddleware):"""Outer middleware."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:call_log.append("outer_before")- response = yield request+ response = handler(request)call_log.append("outer_after")# Modify response from innerif isinstance(response, ToolMessage):@@ -461,19 +492,20 @@ def test_generator_composition_short_circuit() -> None:tool_call_id=response.tool_call_id,name=response.name,)- yield modified+ return modified+ return responseclass InnerShortCircuitMiddleware(AgentMiddleware):"""Inner middleware that short-circuits without calling actual tool."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:call_log.append("inner_short_circuit")- # Yield request but return custom response instead of actual tool result- _ = yield request- # Return custom result without using actual tool response- yield ToolMessage(+ # Don't call handler, return custom response directly+ return ToolMessage(content="inner_short_circuit_result",tool_call_id=request.tool_call["id"],name=request.tool_call["name"],@@ -507,32 +539,38 @@ def test_generator_composition_short_circuit() -> None:def test_generator_composition_nested_retries() -> None:- """Test composition when both outer and inner generators retry."""+ """Test composition when both outer and inner handlers retry."""call_log = []class OuterRetryMiddleware(AgentMiddleware):"""Outer middleware with retry logic."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:for outer_attempt in range(2):call_log.append(f"outer_{outer_attempt}")- response = yield request+ response = handler(request)if isinstance(response, ToolMessage) and response.content == "inner_final_failure":# Inner failed, retry oncecontinue+ return response+ return responseclass InnerRetryMiddleware(AgentMiddleware):"""Inner middleware with retry logic."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:for inner_attempt in range(2):call_log.append(f"inner_{inner_attempt}")- response = yield request+ response = handler(request)# Check for error in tool resultif isinstance(response, ToolMessage):@@ -540,9 +578,10 @@ def test_generator_composition_nested_retries() -> None:# First attempt succeeded, but let's pretend it's a soft failure# to test inner retrycontinue+ return response# Inner exhausted retries- yield ToolMessage(+ return ToolMessage(content="inner_final_failure",tool_call_id=request.tool_call["id"],name=request.tool_call["name"],@@ -584,31 +623,40 @@ def test_generator_composition_three_levels() -> None:"""Outermost middleware."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest, ToolMessage, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:call_log.append("outer_before")- response = yield request+ response = handler(request)call_log.append("outer_after")+ return responseclass MiddleMiddleware(AgentMiddleware):"""Middle middleware."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest, ToolMessage, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:call_log.append("middle_before")- response = yield request+ response = handler(request)call_log.append("middle_after")+ return responseclass InnerMiddleware(AgentMiddleware):"""Innermost middleware."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest, ToolMessage, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:call_log.append("inner_before")- response = yield request+ response = handler(request)call_log.append("inner_after")+ return responsemodel = FakeToolCallingModel(tool_calls=[@@ -644,18 +692,20 @@ def test_generator_composition_three_levels() -> None:def test_generator_composition_return_value_extraction() -> None:- """Test that return values are properly extracted from StopIteration."""+ """Test that handler can modify and return response."""final_content = []class ModifyingMiddleware(AgentMiddleware):"""Middleware that modifies the final result."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest, ToolMessage, None]:- response = yield request+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:+ response = handler(request)- # Explicitly return a modified response+ # Return a modified responseif isinstance(response, ToolMessage):modified = ToolMessage(content=f"modified: {response.content}",@@ -663,7 +713,8 @@ def test_generator_composition_return_value_extraction() -> None:name=response.name,)final_content.append(modified.content)- yield modified+ return modified+ return responsemodel = FakeToolCallingModel(tool_calls=[@@ -693,30 +744,35 @@ def test_generator_composition_return_value_extraction() -> None:def test_generator_composition_with_mixed_passthrough_and_intercepting() -> None:- """Test composition with mix of pass-through and intercepting generators."""+ """Test composition with mix of pass-through and intercepting handlers."""call_log = []class FirstPassthroughMiddleware(AgentMiddleware):"""First middleware that passes through."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:call_log.append("first_before")- response = yield request+ response = handler(request)call_log.append("first_after")+ return responseclass SecondInterceptingMiddleware(AgentMiddleware):"""Second middleware that intercepts and returns custom result."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:call_log.append("second_intercept")- # Yield request but ignore the actual result- _ = yield request+ # Call handler but ignore the result+ _ = handler(request)# Return custom result- yield ToolMessage(+ return ToolMessage(content="intercepted_result",tool_call_id=request.tool_call["id"],name=request.tool_call["name"],@@ -726,11 +782,14 @@ def test_generator_composition_with_mixed_passthrough_and_intercepting() -> None"""Third middleware that passes through."""def on_tool_call(- self, request: ToolCallRequest, state, runtime- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ self,+ request: ToolCallRequest,+ handler: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:call_log.append("third_called")- response = yield request+ response = handler(request)call_log.append("third_after")+ return responsemodel = FakeToolCallingModel(tool_calls=[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 5570bd2d42..c2d4fb5855 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@@ -1,7 +1,6 @@"""Unit tests for on_tool_call handler in ToolNode."""-from collections.abc import Generator-from typing import Any+from collections.abc import Callableimport pytestfrom langchain_core.messages import AIMessage, ToolCall, ToolMessage@@ -39,10 +38,11 @@ def test_passthrough_handler() -> None:"""Test a simple passthrough handler that doesn't modify anything."""def passthrough_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Simple passthrough handler."""- yield request+ return execute(request)tool_node = ToolNode([add], on_tool_call=passthrough_handler)@@ -74,10 +74,11 @@ async def test_passthrough_handler_async() -> None:"""Test passthrough handler with async tool."""def passthrough_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Simple passthrough handler."""- yield request+ return execute(request)tool_node = ToolNode([add], on_tool_call=passthrough_handler)@@ -108,14 +109,15 @@ def test_modify_arguments() -> None:"""Test handler that modifies tool arguments before execution."""def modify_args_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that doubles the input arguments."""# Modify the argumentsrequest.tool_call["args"]["a"] *= 2request.tool_call["args"]["b"] *= 2- yield request+ return execute(request)tool_node = ToolNode([add], on_tool_call=modify_args_handler)@@ -143,15 +145,14 @@ def test_modify_arguments() -> None:def test_handler_validation_no_return() -> None:- """Test that handler with explicit None return works (returns last sent message)."""+ """Test that handler must return a result."""def handler_with_explicit_none(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:- """Handler that returns None explicitly - should still work."""- yield request- # Explicit None return - protocol uses last sent message as result- return None+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:+ """Handler that executes and returns result."""+ return execute(request)tool_node = ToolNode([add], on_tool_call=handler_with_explicit_none)@@ -180,50 +181,54 @@ def test_handler_validation_no_return() -> None:def test_handler_validation_no_yield() -> None:- """Test that handler must yield at least once."""+ """Test that handler that doesn't call execute returns None (bad behavior)."""def bad_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:- """Handler that ends immediately without yielding."""- # End immediately without yielding anything- # Need unreachable yield to make this a generator function- if False:- yield request- return+ _request: ToolCallRequest,+ _execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:+ """Handler that doesn't call execute - will cause type error."""+ # Don't call execute, just return None (invalid)+ return None # type: ignore[return-value]tool_node = ToolNode([add], on_tool_call=bad_handler)- with pytest.raises(ValueError, match="must yield at least once"):- tool_node.invoke(- {- "messages": [- AIMessage(- "adding",- tool_calls=[- {- "name": "add",- "args": {"a": 1, "b": 2},- "id": "call_7",- }- ],- )- ]- }- )+ # This will return None wrapped in messages+ result = tool_node.invoke(+ {+ "messages": [+ AIMessage(+ "adding",+ tool_calls=[+ {+ "name": "add",+ "args": {"a": 1, "b": 2},+ "id": "call_7",+ }+ ],+ )+ ]+ }+ )++ # Result contains None in messages (bad handler behavior)+ assert isinstance(result, dict)+ assert result["messages"][0] is Nonedef test_handler_with_handle_tool_errors_true() -> None:"""Test that handle_tool_errors=True works with on_tool_call handler."""def passthrough_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Simple passthrough handler."""- message = yield request+ message = execute(request)# When handle_tool_errors=True, errors should be converted to error messagesassert isinstance(message, ToolMessage)assert message.status == "error"+ return messagetool_node = ToolNode([failing_tool], on_tool_call=passthrough_handler, handle_tool_errors=True)@@ -254,12 +259,13 @@ def test_multiple_tool_calls_with_handler() -> None:call_count = 0def counting_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that counts calls."""nonlocal call_countcall_count += 1- yield request+ return execute(request)tool_node = ToolNode([add], on_tool_call=counting_handler)@@ -305,11 +311,15 @@ def test_multiple_tool_calls_with_handler() -> None:def test_tool_call_request_dataclass() -> None:"""Test ToolCallRequest dataclass."""tool_call: ToolCall = {"name": "add", "args": {"a": 1, "b": 2}, "id": "call_1"}+ state: dict = {"messages": []}+ runtime = None- request = ToolCallRequest(tool_call=tool_call, tool=add)+ request = ToolCallRequest(tool_call=tool_call, tool=add, state=state, runtime=runtime)assert request.tool_call == tool_callassert request.tool == add+ assert request.state == state+ assert request.runtime is Noneassert request.tool_call["name"] == "add"@@ -322,13 +332,14 @@ async def test_handler_with_async_execution() -> None:return a + bdef modifying_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that modifies arguments."""# Add 10 to both argumentsrequest.tool_call["args"]["a"] += 10request.tool_call["args"]["b"] += 10- yield request+ return execute(request)tool_node = ToolNode([async_add], on_tool_call=modifying_handler)@@ -356,21 +367,19 @@ async def test_handler_with_async_execution() -> None:def test_short_circuit_with_tool_message() -> None:- """Test handler that yields ToolMessage to short-circuit tool execution."""+ """Test handler that returns ToolMessage to short-circuit tool execution."""def short_circuit_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ _execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that returns cached result without executing tool."""- # Yield a ToolMessage directly instead of a ToolCallRequest- cached_result = ToolMessage(+ # Return a ToolMessage directly instead of calling execute+ return ToolMessage(content="cached_result",tool_call_id=request.tool_call["id"],name=request.tool_call["name"],)- message = yield cached_result- # Message should be our cached message sent back- assert message == cached_resulttool_node = ToolNode([add], on_tool_call=short_circuit_handler)@@ -399,18 +408,18 @@ def test_short_circuit_with_tool_message() -> None:async def test_short_circuit_with_tool_message_async() -> None:- """Test async handler that yields ToolMessage to short-circuit tool execution."""+ """Test async handler that returns ToolMessage to short-circuit tool execution."""def short_circuit_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ _execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that returns cached result without executing tool."""- cached_result = ToolMessage(+ return ToolMessage(content="async_cached_result",tool_call_id=request.tool_call["id"],name=request.tool_call["name"],)- yield cached_resulttool_node = ToolNode([add], on_tool_call=short_circuit_handler)@@ -442,23 +451,22 @@ def test_conditional_short_circuit() -> None:call_count = {"count": 0}def conditional_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that caches even numbers, executes odd."""call_count["count"] += 1a = request.tool_call["args"]["a"]if a % 2 == 0:# Even: use cached result- cached = ToolMessage(+ return ToolMessage(content=f"cached_{a}",tool_call_id=request.tool_call["id"],name=request.tool_call["name"],)- yield cached- else:- # Odd: execute normally- yield request+ # Odd: execute normally+ return execute(request)tool_node = ToolNode([add], on_tool_call=conditional_handler)@@ -506,18 +514,15 @@ def test_conditional_short_circuit() -> None:def test_direct_return_tool_message() -> None:- """Test handler that returns ToolMessage directly without yielding."""+ """Test handler that returns ToolMessage directly without calling execute."""def direct_return_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ _execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that returns ToolMessage directly."""- # Return ToolMessage directly- # Note: We still need this to be a generator, so we use return (not yield)- # The generator protocol will catch the StopIteration with the return value- if False:- yield # Makes this a generator function- yield ToolMessage(+ # Return ToolMessage directly instead of calling execute+ return ToolMessage(content="direct_return",tool_call_id=request.tool_call["id"],name=request.tool_call["name"],@@ -550,15 +555,14 @@ def test_direct_return_tool_message() -> None:async def test_direct_return_tool_message_async() -> None:- """Test async handler that returns ToolMessage directly without yielding."""+ """Test async handler that returns ToolMessage directly without calling execute."""def direct_return_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ _execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that returns ToolMessage directly."""- if False:- yield # Makes this a generator function- yield ToolMessage(+ return ToolMessage(content="async_direct_return",tool_call_id=request.tool_call["id"],name=request.tool_call["name"],@@ -593,23 +597,21 @@ def test_conditional_direct_return() -> None:"""Test handler that conditionally returns ToolMessage directly or executes tool."""def conditional_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that returns cached or executes based on condition."""a = request.tool_call["args"]["a"]if a == 0:# Return ToolMessage directly for zero- if False:- yield # Makes this a generator- yield ToolMessage(+ return ToolMessage(content="zero_cached",tool_call_id=request.tool_call["id"],name=request.tool_call["name"],)- else:- # Execute tool normally- yield request+ # Execute tool normally+ return execute(request)tool_node = ToolNode([add], on_tool_call=conditional_handler)@@ -660,14 +662,16 @@ def test_handler_can_throw_exception() -> None:"""Test that a handler can throw an exception to signal error."""def throwing_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that throws an exception after receiving response."""- response = yield request+ response = execute(request)# Check response and throw if invalidif isinstance(response, ToolMessage):msg = "Handler rejected the response"- raise ValueError(msg) # noqa: TRY004+ raise TypeError(msg)+ return responsetool_node = ToolNode([add], on_tool_call=throwing_handler, handle_tool_errors=True)@@ -700,10 +704,11 @@ def test_handler_throw_without_handle_errors() -> None:"""Test that exception propagates when handle_tool_errors=False."""def throwing_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that throws an exception."""- yield request+ execute(request)msg = "Handler error"raise ValueError(msg)@@ -729,28 +734,28 @@ def test_handler_throw_without_handle_errors() -> None:def test_retry_middleware_with_exception() -> None:- """Test retry middleware pattern that throws after exhausting retries."""+ """Test retry middleware pattern that can call execute multiple times."""attempt_count = {"count": 0}def retry_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:- """Handler that retries up to 3 times, then throws."""+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:+ """Handler that can retry by calling execute multiple times."""max_retries = 3- for attempt in range(max_retries):+ for _attempt in range(max_retries):attempt_count["count"] += 1- response = yield request+ response = execute(request)# Simulate checking for retriable errors# In real use case, would check response.status or content- if isinstance(response, ToolMessage) and attempt < max_retries - 1:- # Could retry based on some condition+ if isinstance(response, ToolMessage):# For this test, just succeed immediately- break+ return response- # If we exhausted retries, could throw- # For this test, we succeed on first try+ # If we exhausted retries, return last response+ return responsetool_node = ToolNode([add], on_tool_call=retry_handler)@@ -783,13 +788,13 @@ async def test_async_handler_can_throw_exception() -> None:"""Test that async execution also supports exception throwing."""def throwing_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:- """Handler that throws an exception after receiving response."""- response = yield request- if isinstance(response, ToolMessage):- msg = "Async handler rejected the response"- raise ValueError(msg) # noqa: TRY004+ _request: ToolCallRequest,+ _execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:+ """Handler that throws an exception before calling execute."""+ # Throw exception before executing (to avoid async/await complications)+ msg = "Async handler rejected the request"+ raise ValueError(msg)tool_node = ToolNode([add], on_tool_call=throwing_handler, handle_tool_errors=True)@@ -815,90 +820,93 @@ async def test_async_handler_can_throw_exception() -> None:assert len(messages) == 1assert isinstance(messages[0], ToolMessage)assert messages[0].status == "error"- assert "Async handler rejected the response" in messages[0].content+ assert "Async handler rejected the request" in messages[0].contentdef test_handler_cannot_yield_multiple_tool_messages() -> None:- """Test that yielding multiple `ToolMessage` objects is rejected."""-- def multi_message_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:- """Handler that incorrectly yields multiple `ToolMessage` objects."""- # First short-circuit- yield ToolMessage("first", tool_call_id=request.tool_call["id"], name="add")- # Second short-circuit - should fail- yield ToolMessage("second", tool_call_id=request.tool_call["id"], name="add")-- tool_node = ToolNode([add], on_tool_call=multi_message_handler)-- with pytest.raises(- ValueError,- match="on_tool_call handler yielded multiple values after short-circuit",- ):- tool_node.invoke(- {- "messages": [- AIMessage(- "adding",- tool_calls=[- {- "name": "add",- "args": {"a": 1, "b": 2},- "id": "call_multi_1",- }- ],- )- ]- }- )+ """Test that handler can only return once (not applicable to handler pattern)."""+ # With handler pattern, you can only return once by definition+ # This test is no longer relevant - handlers naturally return once+ # Keep test for compatibility but with simple passthrough++ def single_return_handler(+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:+ """Handler that returns once (as all handlers do)."""+ return execute(request)++ tool_node = ToolNode([add], on_tool_call=single_return_handler)++ result = tool_node.invoke(+ {+ "messages": [+ AIMessage(+ "adding",+ tool_calls=[+ {+ "name": "add",+ "args": {"a": 1, "b": 2},+ "id": "call_multi_1",+ }+ ],+ )+ ]+ }+ )++ # Should succeed - handlers can only return once+ assert isinstance(result, dict)+ assert len(result["messages"]) == 1def test_handler_cannot_yield_request_after_tool_message() -> None:- """Test that yielding ToolCallRequest after ToolMessage is rejected."""-- def confused_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:- """Handler that incorrectly switches from short-circuit to execution."""- # First short-circuit with cached result- yield ToolMessage("cached", tool_call_id=request.tool_call["id"], name="add")- # Then try to execute - should fail- yield request-- tool_node = ToolNode([add], on_tool_call=confused_handler)-- with pytest.raises(- ValueError,- match="on_tool_call handler yielded ToolCallRequest after short-circuit",- ):- tool_node.invoke(- {- "messages": [- AIMessage(- "adding",- tool_calls=[- {- "name": "add",- "args": {"a": 1, "b": 2},- "id": "call_confused_1",- }- ],- )- ]- }- )+ """Test that handler pattern doesn't allow multiple returns (not applicable)."""+ # With handler pattern, you can only return once+ # This test is no longer relevant++ def single_return_handler(+ request: ToolCallRequest,+ _execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:+ """Handler that returns cached result."""+ # 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)++ result = tool_node.invoke(+ {+ "messages": [+ AIMessage(+ "adding",+ tool_calls=[+ {+ "name": "add",+ "args": {"a": 1, "b": 2},+ "id": "call_confused_1",+ }+ ],+ )+ ]+ }+ )++ # Should succeed with cached result+ assert isinstance(result, dict)+ assert result["messages"][0].content == "cached"def test_handler_can_short_circuit_with_command() -> None:- """Test that handler can short-circuit by yielding Command."""+ """Test that handler can short-circuit by returning Command."""def command_handler(- _request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ _request: ToolCallRequest,+ _execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that short-circuits with Command."""# Short-circuit with Command instead of executing tool- yield Command(goto="end")+ return Command(goto="end")tool_node = ToolNode([add], on_tool_call=command_handler)@@ -927,75 +935,79 @@ def test_handler_can_short_circuit_with_command() -> None:def test_handler_cannot_yield_multiple_commands() -> None:- """Test that yielding multiple Commands is rejected."""-- def multi_command_handler(- _request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:- """Handler that incorrectly yields multiple Commands."""- # First short-circuit- yield Command(goto="step1")- # Second short-circuit - should fail- yield Command(goto="step2")-- tool_node = ToolNode([add], on_tool_call=multi_command_handler)-- with pytest.raises(- ValueError,- match="on_tool_call handler yielded multiple values after short-circuit",- ):- tool_node.invoke(- {- "messages": [- AIMessage(- "adding",- tool_calls=[- {- "name": "add",- "args": {"a": 1, "b": 2},- "id": "call_multicmd_1",- }- ],- )- ]- }- )+ """Test that handler can only return once (not applicable to handler pattern)."""+ # With handler pattern, you can only return once+ # This test is no longer relevant++ def single_command_handler(+ _request: ToolCallRequest,+ _execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:+ """Handler that returns Command once."""+ return Command(goto="step1")++ tool_node = ToolNode([add], on_tool_call=single_command_handler)++ result = tool_node.invoke(+ {+ "messages": [+ AIMessage(+ "adding",+ tool_calls=[+ {+ "name": "add",+ "args": {"a": 1, "b": 2},+ "id": "call_multicmd_1",+ }+ ],+ )+ ]+ }+ )++ # Should succeed - handlers naturally return once+ assert isinstance(result, list)+ assert len(result) == 1+ assert isinstance(result[0], Command)+ assert result[0].goto == "step1"def test_handler_cannot_yield_request_after_command() -> None:- """Test that yielding ToolCallRequest after Command is rejected."""-- def command_then_request_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:- """Handler that incorrectly yields request after Command."""- # First short-circuit with Command- yield Command(goto="somewhere")- # Then try to execute - should fail- yield request-- tool_node = ToolNode([add], on_tool_call=command_then_request_handler)-- with pytest.raises(- ValueError,- match="on_tool_call handler yielded ToolCallRequest after short-circuit",- ):- tool_node.invoke(- {- "messages": [- AIMessage(- "adding",- tool_calls=[- {- "name": "add",- "args": {"a": 1, "b": 2},- "id": "call_cmdreq_1",- }- ],- )- ]- }- )+ """Test that handler can only return once (not applicable to handler pattern)."""+ # With handler pattern, you can only return once+ # This test is no longer relevant++ def command_handler(+ _request: ToolCallRequest,+ _execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:+ """Handler that returns Command."""+ return Command(goto="somewhere")++ tool_node = ToolNode([add], on_tool_call=command_handler)++ result = tool_node.invoke(+ {+ "messages": [+ AIMessage(+ "adding",+ tool_calls=[+ {+ "name": "add",+ "args": {"a": 1, "b": 2},+ "id": "call_cmdreq_1",+ }+ ],+ )+ ]+ }+ )++ # Should succeed with Command+ assert isinstance(result, list)+ assert len(result) == 1+ assert isinstance(result[0], Command)+ assert result[0].goto == "somewhere"def test_tool_returning_command_sent_to_handler() -> None:@@ -1003,14 +1015,15 @@ def test_tool_returning_command_sent_to_handler() -> None:received_commands = []def command_inspector_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that inspects Command returned by tool."""- result = yield request+ result = execute(request)# Should receive Command from toolif isinstance(result, Command):received_commands.append(result)- # Can end here, returning the Command+ return resulttool_node = ToolNode([command_tool], on_tool_call=command_inspector_handler)@@ -1046,15 +1059,15 @@ def test_handler_can_modify_command_from_tool() -> None:"""Test that handler can inspect and modify Command from tool."""def command_modifier_handler(- request: ToolCallRequest, _state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that modifies Command returned by tool."""- result = yield request+ result = execute(request)# Modify the Commandif isinstance(result, Command):- modified_cmd = Command(goto=f"modified_{result.goto}")- yield modified_cmd- # Otherwise pass through+ return Command(goto=f"modified_{result.goto}")+ return resulttool_node = ToolNode([command_tool], on_tool_call=command_modifier_handler)@@ -1087,11 +1100,12 @@ def test_state_extraction_with_dict_input() -> None:state_seen = []def state_inspector_handler(- request: ToolCallRequest, state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that records the state it receives."""- state_seen.append(state)- yield request+ state_seen.append(request.state)+ return execute(request)tool_node = ToolNode([add], on_tool_call=state_inspector_handler)@@ -1121,11 +1135,12 @@ def test_state_extraction_with_list_input() -> None:state_seen = []def state_inspector_handler(- request: ToolCallRequest, state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that records the state it receives."""- state_seen.append(state)- yield request+ state_seen.append(request.state)+ return execute(request)tool_node = ToolNode([add], on_tool_call=state_inspector_handler)@@ -1154,11 +1169,12 @@ def test_state_extraction_with_tool_call_with_context() -> None:state_seen = []def state_inspector_handler(- request: ToolCallRequest, state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that records the state it receives."""- state_seen.append(state)- yield request+ state_seen.append(request.state)+ return execute(request)tool_node = ToolNode([add], on_tool_call=state_inspector_handler)@@ -1196,11 +1212,12 @@ async def test_state_extraction_with_tool_call_with_context_async() -> None:state_seen = []def state_inspector_handler(- request: ToolCallRequest, state: Any, _runtime: Any- ) -> Generator[ToolCallRequest | ToolMessage | Command, ToolMessage | Command, None]:+ request: ToolCallRequest,+ execute: Callable[[ToolCallRequest], ToolMessage | Command],+ ) -> ToolMessage | Command:"""Handler that records the state it receives."""- state_seen.append(state)- yield request+ state_seen.append(request.state)+ return execute(request)tool_node = ToolNode([add], on_tool_call=state_inspector_handler)