Skip to content

The agent engineering platform.

feat(langchain): add `state_schema` param to `wrap_tool_call` (#39292)

Nishitha M167c537886fa
diff --git a/libs/langchain_v1/langchain/agents/middleware/types.py b/libs/langchain_v1/langchain/agents/middleware/types.py
index c8d7f2b38f..0fa145bfdf 100644
--- a/libs/langchain_v1/langchain/agents/middleware/types.py
+++ b/libs/langchain_v1/langchain/agents/middleware/types.py
@@ -999,6 +999,9 @@ def before_model(
!!! example "With custom state schema"
+ Use a custom state schema when your middleware needs to read or write additional
+ state fields that aren't part of the default agent state.
+
```python
@before_model(state_schema=MyCustomState)
def custom_before_model(state: MyCustomState, runtime: Runtime) -> dict[str, Any]:
@@ -1173,6 +1176,9 @@ def after_model(
!!! example "With custom state schema"
+ Use a custom state schema when your middleware needs to read or write additional
+ state fields that aren't part of the default agent state.
+
```python
@after_model(state_schema=MyCustomState, name="MyAfterModelMiddleware")
def custom_after_model(state: MyCustomState, runtime: Runtime) -> dict[str, Any]:
@@ -1359,6 +1365,9 @@ def before_agent(
!!! example "With custom state schema"
+ Use a custom state schema when your middleware needs to read or write additional
+ state fields that aren't part of the default agent state.
+
```python
@before_agent(state_schema=MyCustomState)
def custom_before_agent(state: MyCustomState, runtime: Runtime) -> dict[str, Any]:
@@ -1558,6 +1567,9 @@ def after_agent(
!!! example "With custom state schema"
+ Use a custom state schema when your middleware needs to read or write additional
+ state fields that aren't part of the default agent state.
+
```python
@after_agent(state_schema=MyCustomState, name="MyAfterAgentMiddleware")
def custom_after_agent(state: MyCustomState, runtime: Runtime) -> dict[str, Any]:
@@ -1994,32 +2006,34 @@ def wrap_model_call(
@overload
def wrap_tool_call(
func: _CallableReturningToolResponse,
-) -> AgentMiddleware: ...
+) -> AgentMiddleware[StateT, ContextT]: ...
@overload
def wrap_tool_call(
func: None = None,
*,
+ state_schema: type[StateT] | None = None,
tools: list[BaseTool] | None = None,
name: str | None = None,
) -> Callable[
[_CallableReturningToolResponse],
- AgentMiddleware,
+ AgentMiddleware[StateT, ContextT],
]: ...
def wrap_tool_call(
func: _CallableReturningToolResponse | None = None,
*,
+ state_schema: type[StateT] | None = None,
tools: list[BaseTool] | None = None,
name: str | None = None,
) -> (
Callable[
[_CallableReturningToolResponse],
- AgentMiddleware,
+ AgentMiddleware[StateT, ContextT],
]
- | AgentMiddleware
+ | AgentMiddleware[StateT, ContextT]
):
"""Create middleware with `wrap_tool_call` hook from a function.
@@ -2034,6 +2048,9 @@ def wrap_tool_call(
`Command`.
Can be sync or async.
+ state_schema: Optional custom state schema type.
+
+ If not provided, uses the default `AgentState` schema.
tools: Additional tools to register with this middleware.
name: Middleware class name.
@@ -2097,17 +2114,28 @@ def wrap_tool_call(
save_cache(request, result)
return result
```
+
+ !!! example "With custom state schema"
+
+ Use a custom state schema when your middleware needs to read or write additional
+ state fields that aren't part of the default agent state.
+
+ ```python
+ @wrap_tool_call(state_schema=MyCustomState)
+ def custom_wrap_tool_call(request, handler):
+ return handler(request)
+ ```
"""
def decorator(
func: _CallableReturningToolResponse,
- ) -> AgentMiddleware:
+ ) -> AgentMiddleware[StateT, ContextT]:
is_async = iscoroutinefunction(func)
if is_async:
async def async_wrapped(
- _self: AgentMiddleware,
+ _self: AgentMiddleware[StateT, ContextT],
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command[Any]]],
) -> ToolMessage | Command[Any]:
@@ -2120,12 +2148,12 @@ def wrap_tool_call(
# `type(...)` builds the correct middleware subclass at runtime, but
# type checkers cannot infer its generic `AgentMiddleware` parameters.
return cast(
- "AgentMiddleware",
+ "AgentMiddleware[StateT, ContextT]",
type(
middleware_name,
(AgentMiddleware,),
{
- "state_schema": AgentState,
+ "state_schema": state_schema or AgentState,
"tools": tools or [],
"awrap_tool_call": async_wrapped,
},
@@ -2133,7 +2161,7 @@ def wrap_tool_call(
)
def wrapped(
- _self: AgentMiddleware,
+ _self: AgentMiddleware[StateT, ContextT],
request: ToolCallRequest,
handler: Callable[[ToolCallRequest], ToolMessage | Command[Any]],
) -> ToolMessage | Command[Any]:
@@ -2144,12 +2172,12 @@ def wrap_tool_call(
# `type(...)` builds the correct middleware subclass at runtime, but
# type checkers cannot infer its generic `AgentMiddleware` parameters.
return cast(
- "AgentMiddleware",
+ "AgentMiddleware[StateT, ContextT]",
type(
middleware_name,
(AgentMiddleware,),
{
- "state_schema": AgentState,
+ "state_schema": state_schema or AgentState,
"tools": tools or [],
"wrap_tool_call": wrapped,
},
diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/core/test_wrap_tool_call.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/core/test_wrap_tool_call.py
index 9620bf400e..e1a5e3dc69 100644
--- a/libs/langchain_v1/tests/unit_tests/agents/middleware/core/test_wrap_tool_call.py
+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/core/test_wrap_tool_call.py
@@ -6,7 +6,7 @@ focusing on the handler pattern (not generators).
import time
from collections.abc import Callable
-from typing import Any
+from typing import Any, TypedDict
from langchain_core.messages import HumanMessage, ToolCall, ToolMessage
from langchain_core.tools import BaseTool, tool
@@ -14,7 +14,7 @@ from langgraph.checkpoint.memory import InMemorySaver
from langgraph.types import Command
from langchain.agents.factory import create_agent
-from langchain.agents.middleware.types import ToolCallRequest, wrap_tool_call
+from langchain.agents.middleware.types import AgentMiddleware, ToolCallRequest, wrap_tool_call
from tests.unit_tests.agents.model import FakeToolCallingModel
@@ -74,6 +74,27 @@ def test_wrap_tool_call_basic_passthrough() -> None:
assert "Results for: test" in tool_messages[0].content
+def test_wrap_tool_call_with_custom_state_schema() -> None:
+ """Test `state_schema` is accepted for consistency with other middleware decorators.
+
+ `before_model`, `after_model`, `wrap_model_call`, `before_agent`, and
+ `after_agent` all support a `state_schema` parameter.
+ """
+
+ class CustomState(TypedDict):
+ messages: list[Any]
+ custom_field: str
+
+ @wrap_tool_call(state_schema=CustomState) # type: ignore[type-var]
+ def middleware_with_schema(
+ request: ToolCallRequest, handler: Callable[[ToolCallRequest], ToolMessage | Command[Any]]
+ ) -> ToolMessage | Command[Any]:
+ return handler(request)
+
+ assert isinstance(middleware_with_schema, AgentMiddleware)
+ assert middleware_with_schema.state_schema == CustomState
+
+
def test_wrap_tool_call_logging() -> None:
"""Test logging tool call execution with wrap_tool_call decorator."""
call_log = []