langchain 1.0.0a12__py3-none-any.whl → 1.0.0a13__py3-none-any.whl

langchain/agents/middleware/types.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Callable
+from collections.abc import Awaitable, Callable
 from dataclasses import dataclass, field
 from inspect import iscoroutinefunction
 from typing import (
@@ -16,16 +16,19 @@ from typing import (
     overload,
 )
 
-from langchain_core.runnables import run_in_executor
-
 if TYPE_CHECKING:
     from collections.abc import Awaitable
 
+    from langchain.tools.tool_node import ToolCallRequest
+
 # needed as top level import for pydantic schema generation on AgentState
-from langchain_core.messages import AnyMessage  # noqa: TC002
+from typing import TypeAlias
+
+from langchain_core.messages import AIMessage, AnyMessage, BaseMessage, ToolMessage  # noqa: TC002
 from langgraph.channels.ephemeral_value import EphemeralValue
 from langgraph.channels.untracked_value import UntrackedValue
 from langgraph.graph.message import add_messages
+from langgraph.types import Command  # noqa: TC002
 from langgraph.typing import ContextT
 from typing_extensions import NotRequired, Required, TypedDict, TypeVar
 
@@ -33,7 +36,6 @@ if TYPE_CHECKING:
     from langchain_core.language_models.chat_models import BaseChatModel
     from langchain_core.tools import BaseTool
     from langgraph.runtime import Runtime
-    from langgraph.types import Command
 
     from langchain.agents.structured_output import ResponseFormat
 
@@ -42,6 +44,7 @@ __all__ = [
     "AgentState",
     "ContextT",
     "ModelRequest",
+    "ModelResponse",
     "OmitFromSchema",
     "PublicAgentState",
     "after_agent",
@@ -50,7 +53,7 @@ __all__ = [
     "before_model",
     "dynamic_prompt",
     "hook_config",
-    "modify_model_request",
+    "wrap_tool_call",
 ]
 
 JumpTo = Literal["tools", "model", "end"]
@@ -69,9 +72,36 @@ class ModelRequest:
     tool_choice: Any | None
     tools: list[BaseTool | dict]
     response_format: ResponseFormat | None
+    state: AgentState
+    runtime: Runtime[ContextT]  # type: ignore[valid-type]
     model_settings: dict[str, Any] = field(default_factory=dict)
 
 
+@dataclass
+class ModelResponse:
+    """Response from model execution including messages and optional structured output.
+
+    The result will usually contain a single AIMessage, but may include
+    an additional ToolMessage if the model used a tool for structured output.
+    """
+
+    result: list[BaseMessage]
+    """List of messages from model execution."""
+
+    structured_response: Any = None
+    """Parsed structured output if response_format was specified, None otherwise."""
+
+
+# Type alias for middleware return type - allows returning either full response or just AIMessage
+ModelCallResult: TypeAlias = "ModelResponse | AIMessage"
+"""Type alias for model call handler return value.
+
+Middleware can return either:
+- ModelResponse: Full response with messages and optional structured output
+- AIMessage: Simplified return for simple use cases
+"""
+
+
 @dataclass
 class OmitFromSchema:
     """Annotation used to mark state attributes as omitted from input or output schemas."""
@@ -154,24 +184,6 @@ class AgentMiddleware(Generic[StateT, ContextT]):
     ) -> dict[str, Any] | None:
         """Async logic to run before the model is called."""
 
-    def modify_model_request(
-        self,
-        request: ModelRequest,
-        state: StateT,  # noqa: ARG002
-        runtime: Runtime[ContextT],  # noqa: ARG002
-    ) -> ModelRequest:
-        """Logic to modify request kwargs before the model is called."""
-        return request
-
-    async def amodify_model_request(
-        self,
-        request: ModelRequest,
-        state: StateT,
-        runtime: Runtime[ContextT],
-    ) -> ModelRequest:
-        """Async logic to modify request kwargs before the model is called."""
-        return await run_in_executor(None, self.modify_model_request, request, state, runtime)
-
     def after_model(self, state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None:
         """Logic to run after the model is called."""
 
@@ -180,53 +192,106 @@ class AgentMiddleware(Generic[StateT, ContextT]):
     ) -> dict[str, Any] | None:
         """Async logic to run after the model is called."""
 
-    def retry_model_request(
+    def wrap_model_call(
         self,
-        error: Exception,  # noqa: ARG002
-        request: ModelRequest,  # noqa: ARG002
-        state: StateT,  # noqa: ARG002
-        runtime: Runtime[ContextT],  # noqa: ARG002
-        attempt: int,  # noqa: ARG002
-    ) -> ModelRequest | None:
-        """Logic to handle model invocation errors and optionally retry.
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelCallResult:
+        """Intercept and control model execution via handler callback.
+
+        The handler callback executes the model request and returns a ModelResponse.
+        Middleware can call the handler multiple times for retry logic, skip calling
+        it to short-circuit, or modify the request/response. Multiple middleware
+        compose with first in list as outermost layer.
 
         Args:
-            error: The exception that occurred during model invocation.
-            request: The original model request that failed.
-            state: The current agent state.
-            runtime: The langgraph runtime.
-            attempt: The current attempt number (1-indexed).
+            request: Model request to execute (includes state and runtime).
+            handler: Callback that executes the model request and returns ModelResponse.
+                     Call this to execute the model. Can be called multiple times
+                     for retry logic. Can skip calling it to short-circuit.
 
         Returns:
-            ModelRequest: Modified request to retry with.
-            None: Propagate the error (re-raise).
+            ModelCallResult
+
+        Examples:
+            Retry on error:
+            ```python
+            def wrap_model_call(self, request, handler):
+                for attempt in range(3):
+                    try:
+                        return handler(request)
+                    except Exception:
+                        if attempt == 2:
+                            raise
+            ```
+
+            Rewrite response:
+            ```python
+            def wrap_model_call(self, request, handler):
+                response = handler(request)
+                ai_msg = response.result[0]
+                return ModelResponse(
+                    result=[AIMessage(content=f"[{ai_msg.content}]")],
+                    structured_response=response.structured_response,
+                )
+            ```
+
+            Error to fallback:
+            ```python
+            def wrap_model_call(self, request, handler):
+                try:
+                    return handler(request)
+                except Exception:
+                    return ModelResponse(result=[AIMessage(content="Service unavailable")])
+            ```
+
+            Cache/short-circuit:
+            ```python
+            def wrap_model_call(self, request, handler):
+                if cached := get_cache(request):
+                    return cached  # Short-circuit with cached result
+                response = handler(request)
+                save_cache(request, response)
+                return response
+            ```
+
+            Simple AIMessage return (converted automatically):
+            ```python
+            def wrap_model_call(self, request, handler):
+                response = handler(request)
+                # Can return AIMessage directly for simple cases
+                return AIMessage(content="Simplified response")
+            ```
         """
-        return None
+        raise NotImplementedError
 
-    async def aretry_model_request(
+    async def awrap_model_call(
         self,
-        error: Exception,
         request: ModelRequest,
-        state: StateT,
-        runtime: Runtime[ContextT],
-        attempt: int,
-    ) -> ModelRequest | None:
-        """Async logic to handle model invocation errors and optionally retry.
+        handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+    ) -> ModelCallResult:
+        """Async version of wrap_model_call.
 
         Args:
-            error: The exception that occurred during model invocation.
-            request: The original model request that failed.
-            state: The current agent state.
-            runtime: The langgraph runtime.
-            attempt: The current attempt number (1-indexed).
+            request: Model request to execute (includes state and runtime).
+            handler: Async callback that executes the model request.
 
         Returns:
-            ModelRequest: Modified request to retry with.
-            None: Propagate the error (re-raise).
+            ModelCallResult
+
+        Examples:
+            Retry on error:
+            ```python
+            async def awrap_model_call(self, request, handler):
+                for attempt in range(3):
+                    try:
+                        return await handler(request)
+                    except Exception:
+                        if attempt == 2:
+                            raise
+            ```
         """
-        return await run_in_executor(
-            None, self.retry_model_request, error, request, state, runtime, attempt
-        )
+        raise NotImplementedError
 
     def after_agent(self, state: StateT, runtime: Runtime[ContextT]) -> dict[str, Any] | None:
         """Logic to run after the agent execution completes."""
@@ -236,6 +301,60 @@ class AgentMiddleware(Generic[StateT, ContextT]):
     ) -> dict[str, Any] | None:
         """Async logic to run after the agent execution completes."""
 
+    def wrap_tool_call(
+        self,
+        request: ToolCallRequest,
+        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, 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).
+
+        The handler callable can be invoked multiple times for retry logic.
+        Each call to handler is independent and stateless.
+
+        Examples:
+            Modify request before execution:
+
+            def wrap_tool_call(self, request, handler):
+                request.tool_call["args"]["value"] *= 2
+                return handler(request)
+
+            Retry on error (call handler multiple times):
+
+            def wrap_tool_call(self, request, handler):
+                for attempt in range(3):
+                    try:
+                        result = handler(request)
+                        if is_valid(result):
+                            return result
+                    except Exception:
+                        if attempt == 2:
+                            raise
+                return result
+
+            Conditional retry based on response:
+
+            def wrap_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
+        """
+        raise NotImplementedError
+
 
 class _CallableWithStateAndRuntime(Protocol[StateT_contra, ContextT]):
     """Callable with AgentState and Runtime as arguments."""
@@ -247,23 +366,41 @@ class _CallableWithStateAndRuntime(Protocol[StateT_contra, ContextT]):
         ...
 
 
-class _CallableWithModelRequestAndStateAndRuntime(Protocol[StateT_contra, ContextT]):
-    """Callable with ModelRequest, AgentState, and Runtime as arguments."""
+class _CallableReturningPromptString(Protocol[StateT_contra, ContextT]):  # type: ignore[misc]
+    """Callable that returns a prompt string given ModelRequest (contains state and runtime)."""
+
+    def __call__(self, request: ModelRequest) -> str | Awaitable[str]:
+        """Generate a system prompt string based on the request."""
+        ...
+
+
+class _CallableReturningModelResponse(Protocol[StateT_contra, ContextT]):  # type: ignore[misc]
+    """Callable for model call interception with handler callback.
+
+    Receives handler callback to execute model and returns ModelResponse or AIMessage.
+    """
 
     def __call__(
-        self, request: ModelRequest, state: StateT_contra, runtime: Runtime[ContextT]
-    ) -> ModelRequest | Awaitable[ModelRequest]:
-        """Perform some logic with the model request, state, and runtime."""
+        self,
+        request: ModelRequest,
+        handler: Callable[[ModelRequest], ModelResponse],
+    ) -> ModelCallResult:
+        """Intercept model execution via handler callback."""
         ...
 
 
-class _CallableReturningPromptString(Protocol[StateT_contra, ContextT]):
-    """Callable that returns a prompt string given ModelRequest, AgentState, and Runtime."""
+class _CallableReturningToolResponse(Protocol):
+    """Callable for tool call interception with handler callback.
+
+    Receives handler callback to execute tool and returns final ToolMessage or Command.
+    """
 
     def __call__(
-        self, request: ModelRequest, state: StateT_contra, runtime: Runtime[ContextT]
-    ) -> str | Awaitable[str]:
-        """Generate a system prompt string based on the request, state, and runtime."""
+        self,
+        request: ToolCallRequest,
+        handler: Callable[[ToolCallRequest], ToolMessage | Command],
+    ) -> ToolMessage | Command:
+        """Intercept tool execution via handler callback."""
         ...
 
 
@@ -363,7 +500,7 @@ def before_model(
 
     Returns:
         Either an AgentMiddleware instance (if func is provided directly) or a decorator function
-        that can be applied to a function its wrapping.
+        that can be applied to a function it is wrapping.
 
     The decorated function should return:
         - `dict[str, Any]` - State updates to merge into the agent state
@@ -460,143 +597,6 @@ def before_model(
     return decorator
 
 
-@overload
-def modify_model_request(
-    func: _CallableWithModelRequestAndStateAndRuntime[StateT, ContextT],
-) -> AgentMiddleware[StateT, ContextT]: ...
-
-
-@overload
-def modify_model_request(
-    func: None = None,
-    *,
-    state_schema: type[StateT] | None = None,
-    tools: list[BaseTool] | None = None,
-    name: str | None = None,
-) -> Callable[
-    [_CallableWithModelRequestAndStateAndRuntime[StateT, ContextT]],
-    AgentMiddleware[StateT, ContextT],
-]: ...
-
-
-def modify_model_request(
-    func: _CallableWithModelRequestAndStateAndRuntime[StateT, ContextT] | None = None,
-    *,
-    state_schema: type[StateT] | None = None,
-    tools: list[BaseTool] | None = None,
-    name: str | None = None,
-) -> (
-    Callable[
-        [_CallableWithModelRequestAndStateAndRuntime[StateT, ContextT]],
-        AgentMiddleware[StateT, ContextT],
-    ]
-    | AgentMiddleware[StateT, ContextT]
-):
-    r"""Decorator used to dynamically create a middleware with the modify_model_request hook.
-
-    Args:
-        func: The function to be decorated. Must accept:
-            `request: ModelRequest, state: StateT, runtime: Runtime[ContextT]` -
-            Model request, state, and runtime context
-        state_schema: Optional custom state schema type. If not provided, uses the default
-            AgentState schema.
-        tools: Optional list of additional tools to register with this middleware.
-        name: Optional name for the generated middleware class. If not provided,
-            uses the decorated function's name.
-
-    Returns:
-        Either an AgentMiddleware instance (if func is provided) or a decorator function
-        that can be applied to a function.
-
-    The decorated function should return:
-        - `ModelRequest` - The modified model request to be sent to the language model
-
-    Examples:
-        Basic usage to modify system prompt:
-        ```python
-        @modify_model_request
-        def add_context_to_prompt(
-            request: ModelRequest, state: AgentState, runtime: Runtime
-        ) -> ModelRequest:
-            if request.system_prompt:
-                request.system_prompt += "\n\nAdditional context: ..."
-            else:
-                request.system_prompt = "Additional context: ..."
-            return request
-        ```
-
-        Usage with runtime and custom model settings:
-        ```python
-        @modify_model_request
-        def dynamic_model_settings(
-            request: ModelRequest, state: AgentState, runtime: Runtime
-        ) -> ModelRequest:
-            # Use a different model based on user subscription tier
-            if runtime.context.get("subscription_tier") == "premium":
-                request.model = "gpt-4o"
-            else:
-                request.model = "gpt-4o-mini"
-
-            return request
-        ```
-    """
-
-    def decorator(
-        func: _CallableWithModelRequestAndStateAndRuntime[StateT, ContextT],
-    ) -> AgentMiddleware[StateT, ContextT]:
-        is_async = iscoroutinefunction(func)
-
-        if is_async:
-
-            async def async_wrapped(
-                self: AgentMiddleware[StateT, ContextT],  # noqa: ARG001
-                request: ModelRequest,
-                state: StateT,
-                runtime: Runtime[ContextT],
-            ) -> ModelRequest:
-                return await func(request, state, runtime)  # type: ignore[misc]
-
-            middleware_name = name or cast(
-                "str", getattr(func, "__name__", "ModifyModelRequestMiddleware")
-            )
-
-            return type(
-                middleware_name,
-                (AgentMiddleware,),
-                {
-                    "state_schema": state_schema or AgentState,
-                    "tools": tools or [],
-                    "amodify_model_request": async_wrapped,
-                },
-            )()
-
-        def wrapped(
-            self: AgentMiddleware[StateT, ContextT],  # noqa: ARG001
-            request: ModelRequest,
-            state: StateT,
-            runtime: Runtime[ContextT],
-        ) -> ModelRequest:
-            return func(request, state, runtime)  # type: ignore[return-value]
-
-        middleware_name = name or cast(
-            "str", getattr(func, "__name__", "ModifyModelRequestMiddleware")
-        )
-
-        return type(
-            middleware_name,
-            (AgentMiddleware,),
-            {
-                "state_schema": state_schema or AgentState,
-                "tools": tools or [],
-                "modify_model_request": wrapped,
-            },
-        )()
-
-    if func is not None:
-        return decorator(func)
-    return decorator
-
-
 @overload
 def after_model(
     func: _CallableWithStateAndRuntime[StateT, ContextT],
@@ -773,7 +773,7 @@ def before_agent(
 
     Returns:
         Either an AgentMiddleware instance (if func is provided directly) or a decorator function
-        that can be applied to a function its wrapping.
+        that can be applied to a function it is wrapping.
 
     The decorated function should return:
         - `dict[str, Any]` - State updates to merge into the agent state
@@ -1027,14 +1027,13 @@ def dynamic_prompt(
 ):
     """Decorator used to dynamically generate system prompts for the model.
 
-    This is a convenience decorator that creates middleware using `modify_model_request`
+    This is a convenience decorator that creates middleware using `wrap_model_call`
     specifically for dynamic prompt generation. The decorated function should return
     a string that will be set as the system prompt for the model request.
 
     Args:
         func: The function to be decorated. Must accept:
-            `request: ModelRequest, state: StateT, runtime: Runtime[ContextT]` -
-            Model request, state, and runtime context
+            `request: ModelRequest` - Model request (contains state and runtime)
 
     Returns:
         Either an AgentMiddleware instance (if func is provided) or a decorator function
@@ -1047,16 +1046,16 @@ def dynamic_prompt(
         Basic usage with dynamic content:
         ```python
         @dynamic_prompt
-        def my_prompt(request: ModelRequest, state: AgentState, runtime: Runtime) -> str:
-            user_name = runtime.context.get("user_name", "User")
+        def my_prompt(request: ModelRequest) -> str:
+            user_name = request.runtime.context.get("user_name", "User")
             return f"You are a helpful assistant helping {user_name}."
         ```
 
         Using state to customize the prompt:
         ```python
         @dynamic_prompt
-        def context_aware_prompt(request: ModelRequest, state: AgentState, runtime: Runtime) -> str:
-            msg_count = len(state["messages"])
+        def context_aware_prompt(request: ModelRequest) -> str:
+            msg_count = len(request.state["messages"])
             if msg_count > 10:
                 return "You are in a long conversation. Be concise."
             return "You are a helpful assistant."
@@ -1078,12 +1077,11 @@ def dynamic_prompt(
             async def async_wrapped(
                 self: AgentMiddleware[StateT, ContextT],  # noqa: ARG001
                 request: ModelRequest,
-                state: StateT,
-                runtime: Runtime[ContextT],
-            ) -> ModelRequest:
-                prompt = await func(request, state, runtime)  # type: ignore[misc]
+                handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+            ) -> ModelCallResult:
+                prompt = await func(request)  # type: ignore[misc]
                 request.system_prompt = prompt
-                return request
+                return await handler(request)
 
             middleware_name = cast("str", getattr(func, "__name__", "DynamicPromptMiddleware"))
 
@@ -1093,19 +1091,18 @@ def dynamic_prompt(
                 {
                     "state_schema": AgentState,
                     "tools": [],
-                    "amodify_model_request": async_wrapped,
+                    "awrap_model_call": async_wrapped,
                 },
             )()
 
         def wrapped(
             self: AgentMiddleware[StateT, ContextT],  # noqa: ARG001
             request: ModelRequest,
-            state: StateT,
-            runtime: Runtime[ContextT],
-        ) -> ModelRequest:
-            prompt = cast("str", func(request, state, runtime))
+            handler: Callable[[ModelRequest], ModelResponse],
+        ) -> ModelCallResult:
+            prompt = cast("str", func(request))
             request.system_prompt = prompt
-            return request
+            return handler(request)
 
         middleware_name = cast("str", getattr(func, "__name__", "DynamicPromptMiddleware"))
 
@@ -1115,7 +1112,269 @@ def dynamic_prompt(
             {
                 "state_schema": AgentState,
                 "tools": [],
-                "modify_model_request": wrapped,
+                "wrap_model_call": wrapped,
+            },
+        )()
+
+    if func is not None:
+        return decorator(func)
+    return decorator
+
+
+@overload
+def wrap_model_call(
+    func: _CallableReturningModelResponse[StateT, ContextT],
+) -> AgentMiddleware[StateT, ContextT]: ...
+
+
+@overload
+def wrap_model_call(
+    func: None = None,
+    *,
+    state_schema: type[StateT] | None = None,
+    tools: list[BaseTool] | None = None,
+    name: str | None = None,
+) -> Callable[
+    [_CallableReturningModelResponse[StateT, ContextT]],
+    AgentMiddleware[StateT, ContextT],
+]: ...
+
+
+def wrap_model_call(
+    func: _CallableReturningModelResponse[StateT, ContextT] | None = None,
+    *,
+    state_schema: type[StateT] | None = None,
+    tools: list[BaseTool] | None = None,
+    name: str | None = None,
+) -> (
+    Callable[
+        [_CallableReturningModelResponse[StateT, ContextT]],
+        AgentMiddleware[StateT, ContextT],
+    ]
+    | AgentMiddleware[StateT, ContextT]
+):
+    """Create middleware with wrap_model_call hook from a function.
+
+    Converts a function with handler callback into middleware that can intercept
+    model calls, implement retry logic, handle errors, and rewrite responses.
+
+    Args:
+        func: Function accepting (request, handler) that calls handler(request)
+            to execute the model and returns ModelResponse or AIMessage.
+            Request contains state and runtime.
+        state_schema: Custom state schema. Defaults to AgentState.
+        tools: Additional tools to register with this middleware.
+        name: Middleware class name. Defaults to function name.
+
+    Returns:
+        AgentMiddleware instance if func provided, otherwise a decorator.
+
+    Examples:
+        Basic retry logic:
+        ```python
+        @wrap_model_call
+        def retry_on_error(request, handler):
+            max_retries = 3
+            for attempt in range(max_retries):
+                try:
+                    return handler(request)
+                except Exception:
+                    if attempt == max_retries - 1:
+                        raise
+        ```
+
+        Model fallback:
+        ```python
+        @wrap_model_call
+        def fallback_model(request, handler):
+            # Try primary model
+            try:
+                return handler(request)
+            except Exception:
+                pass
+
+            # Try fallback model
+            request.model = fallback_model_instance
+            return handler(request)
+        ```
+
+        Rewrite response content (full ModelResponse):
+        ```python
+        @wrap_model_call
+        def uppercase_responses(request, handler):
+            response = handler(request)
+            ai_msg = response.result[0]
+            return ModelResponse(
+                result=[AIMessage(content=ai_msg.content.upper())],
+                structured_response=response.structured_response,
+            )
+        ```
+
+        Simple AIMessage return (converted automatically):
+        ```python
+        @wrap_model_call
+        def simple_response(request, handler):
+            # AIMessage is automatically converted to ModelResponse
+            return AIMessage(content="Simple response")
+        ```
+    """
+
+    def decorator(
+        func: _CallableReturningModelResponse[StateT, ContextT],
+    ) -> AgentMiddleware[StateT, ContextT]:
+        is_async = iscoroutinefunction(func)
+
+        if is_async:
+
+            async def async_wrapped(
+                self: AgentMiddleware[StateT, ContextT],  # noqa: ARG001
+                request: ModelRequest,
+                handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+            ) -> ModelCallResult:
+                return await func(request, handler)  # type: ignore[misc, arg-type]
+
+            middleware_name = name or cast(
+                "str", getattr(func, "__name__", "WrapModelCallMiddleware")
+            )
+
+            return type(
+                middleware_name,
+                (AgentMiddleware,),
+                {
+                    "state_schema": state_schema or AgentState,
+                    "tools": tools or [],
+                    "awrap_model_call": async_wrapped,
+                },
+            )()
+
+        def wrapped(
+            self: AgentMiddleware[StateT, ContextT],  # noqa: ARG001
+            request: ModelRequest,
+            handler: Callable[[ModelRequest], ModelResponse],
+        ) -> ModelCallResult:
+            return func(request, handler)
+
+        middleware_name = name or cast("str", getattr(func, "__name__", "WrapModelCallMiddleware"))
+
+        return type(
+            middleware_name,
+            (AgentMiddleware,),
+            {
+                "state_schema": state_schema or AgentState,
+                "tools": tools or [],
+                "wrap_model_call": wrapped,
+            },
+        )()
+
+    if func is not None:
+        return decorator(func)
+    return decorator
+
+
+@overload
+def wrap_tool_call(
+    func: _CallableReturningToolResponse,
+) -> AgentMiddleware: ...
+
+
+@overload
+def wrap_tool_call(
+    func: None = None,
+    *,
+    tools: list[BaseTool] | None = None,
+    name: str | None = None,
+) -> Callable[
+    [_CallableReturningToolResponse],
+    AgentMiddleware,
+]: ...
+
+
+def wrap_tool_call(
+    func: _CallableReturningToolResponse | None = None,
+    *,
+    tools: list[BaseTool] | None = None,
+    name: str | None = None,
+) -> (
+    Callable[
+        [_CallableReturningToolResponse],
+        AgentMiddleware,
+    ]
+    | AgentMiddleware
+):
+    """Create middleware with wrap_tool_call hook from a function.
+
+    Converts a function with handler callback into middleware that can intercept
+    tool calls, implement retry logic, monitor execution, and modify responses.
+
+    Args:
+        func: Function accepting (request, handler) that calls
+            handler(request) to execute the tool and returns final ToolMessage or Command.
+        tools: Additional tools to register with this middleware.
+        name: Middleware class name. Defaults to function name.
+
+    Returns:
+        AgentMiddleware instance if func provided, otherwise a decorator.
+
+    Examples:
+        Basic passthrough:
+        ```python
+        @wrap_tool_call
+        def passthrough(request, handler):
+            return handler(request)
+        ```
+
+        Retry logic:
+        ```python
+        @wrap_tool_call
+        def retry_on_error(request, handler):
+            max_retries = 3
+            for attempt in range(max_retries):
+                try:
+                    return handler(request)
+                except Exception:
+                    if attempt == max_retries - 1:
+                        raise
+        ```
+
+        Modify request:
+        ```python
+        @wrap_tool_call
+        def modify_args(request, handler):
+            request.tool_call["args"]["value"] *= 2
+            return handler(request)
+        ```
+
+        Short-circuit with cached result:
+        ```python
+        @wrap_tool_call
+        def with_cache(request, handler):
+            if cached := get_cache(request):
+                return ToolMessage(content=cached, tool_call_id=request.tool_call["id"])
+            result = handler(request)
+            save_cache(request, result)
+            return result
+        ```
+    """
+
+    def decorator(
+        func: _CallableReturningToolResponse,
+    ) -> AgentMiddleware:
+        def wrapped(
+            self: AgentMiddleware,  # noqa: ARG001
+            request: ToolCallRequest,
+            handler: Callable[[ToolCallRequest], ToolMessage | Command],
+        ) -> ToolMessage | Command:
+            return func(request, handler)
+
+        middleware_name = name or cast("str", getattr(func, "__name__", "WrapToolCallMiddleware"))
+
+        return type(
+            middleware_name,
+            (AgentMiddleware,),
+            {
+                "state_schema": AgentState,
+                "tools": tools or [],
+                "wrap_tool_call": wrapped,
             },
         )()