Skip to content

The agent engineering platform.

chore(langchain_v1): update wrap_on_model return (#33408)

Eugene Yurtsev11c5b8698170
diff --git a/libs/langchain_v1/langchain/agents/factory.py b/libs/langchain_v1/langchain/agents/factory.py
index f61d11d067..84aaa60a8b 100644
--- a/libs/langchain_v1/langchain/agents/factory.py
+++ b/libs/langchain_v1/langchain/agents/factory.py
@@ -3,7 +3,6 @@
from __future__ import annotations
import itertools
-from dataclasses import dataclass
from typing import (
TYPE_CHECKING,
Annotated,
@@ -33,6 +32,7 @@ from langchain.agents.middleware.types import (
AgentState,
JumpTo,
ModelRequest,
+ ModelResponse,
OmitFromSchema,
PublicAgentState,
)
@@ -66,35 +66,24 @@ STRUCTURED_OUTPUT_ERROR_TEMPLATE = "Error: {error}\n Please fix your mistakes."
ResponseT = TypeVar("ResponseT")
-@dataclass
-class _InternalModelResponse:
- """Internal wrapper for model execution results.
-
- Contains either a successful result or an exception, plus cached metadata.
- Middleware receives either AIMessage via .send() or Exception via .throw().
- """
-
- result: AIMessage | None
- """The AI message result on success."""
-
- exception: Exception | None
- """The exception on error."""
-
- effective_response_format: Any = None
- """Cached response format after auto-detection."""
+def _normalize_to_model_response(result: ModelResponse | AIMessage) -> ModelResponse:
+ """Normalize middleware return value to ModelResponse."""
+ if isinstance(result, AIMessage):
+ return ModelResponse(result=[result], structured_response=None)
+ return result
def _chain_model_call_handlers(
handlers: Sequence[
Callable[
- [ModelRequest, Callable[[ModelRequest], AIMessage]],
- AIMessage,
+ [ModelRequest, Callable[[ModelRequest], ModelResponse]],
+ ModelResponse | AIMessage,
]
],
) -> (
Callable[
- [ModelRequest, Callable[[ModelRequest], AIMessage]],
- AIMessage,
+ [ModelRequest, Callable[[ModelRequest], ModelResponse]],
+ ModelResponse,
]
| None
):
@@ -137,33 +126,45 @@ def _chain_model_call_handlers(
return None
if len(handlers) == 1:
- return handlers[0]
+ # Single handler - wrap to normalize output
+ single_handler = handlers[0]
+
+ def normalized_single(
+ request: ModelRequest,
+ handler: Callable[[ModelRequest], ModelResponse],
+ ) -> ModelResponse:
+ result = single_handler(request, handler)
+ return _normalize_to_model_response(result)
+
+ return normalized_single
def compose_two(
outer: Callable[
- [ModelRequest, Callable[[ModelRequest], AIMessage]],
- AIMessage,
+ [ModelRequest, Callable[[ModelRequest], ModelResponse]],
+ ModelResponse | AIMessage,
],
inner: Callable[
- [ModelRequest, Callable[[ModelRequest], AIMessage]],
- AIMessage,
+ [ModelRequest, Callable[[ModelRequest], ModelResponse]],
+ ModelResponse | AIMessage,
],
) -> Callable[
- [ModelRequest, Callable[[ModelRequest], AIMessage]],
- AIMessage,
+ [ModelRequest, Callable[[ModelRequest], ModelResponse]],
+ ModelResponse,
]:
"""Compose two handlers where outer wraps inner."""
def composed(
request: ModelRequest,
- handler: Callable[[ModelRequest], AIMessage],
- ) -> AIMessage:
- # Create a wrapper that calls inner with the base handler
- def inner_handler(req: ModelRequest) -> AIMessage:
- return inner(req, handler)
+ handler: Callable[[ModelRequest], ModelResponse],
+ ) -> ModelResponse:
+ # Create a wrapper that calls inner with the base handler and normalizes
+ def inner_handler(req: ModelRequest) -> ModelResponse:
+ inner_result = inner(req, handler)
+ return _normalize_to_model_response(inner_result)
- # Call outer with the wrapped inner as its handler
- return outer(request, inner_handler)
+ # Call outer with the wrapped inner as its handler and normalize
+ outer_result = outer(request, inner_handler)
+ return _normalize_to_model_response(outer_result)
return composed
@@ -172,20 +173,29 @@ def _chain_model_call_handlers(
for handler in reversed(handlers[:-1]):
result = compose_two(handler, result)
- return result
+ # Wrap to ensure final return type is exactly ModelResponse
+ def final_normalized(
+ request: ModelRequest,
+ handler: Callable[[ModelRequest], ModelResponse],
+ ) -> ModelResponse:
+ # result here is typed as returning ModelResponse | AIMessage but compose_two normalizes
+ final_result = result(request, handler)
+ return _normalize_to_model_response(final_result)
+
+ return final_normalized
def _chain_async_model_call_handlers(
handlers: Sequence[
Callable[
- [ModelRequest, Callable[[ModelRequest], Awaitable[AIMessage]]],
- Awaitable[AIMessage],
+ [ModelRequest, Callable[[ModelRequest], Awaitable[ModelResponse]]],
+ Awaitable[ModelResponse | AIMessage],
]
],
) -> (
Callable[
- [ModelRequest, Callable[[ModelRequest], Awaitable[AIMessage]]],
- Awaitable[AIMessage],
+ [ModelRequest, Callable[[ModelRequest], Awaitable[ModelResponse]]],
+ Awaitable[ModelResponse],
]
| None
):
@@ -201,33 +211,45 @@ def _chain_async_model_call_handlers(
return None
if len(handlers) == 1:
- return handlers[0]
+ # Single handler - wrap to normalize output
+ single_handler = handlers[0]
+
+ async def normalized_single(
+ request: ModelRequest,
+ handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+ ) -> ModelResponse:
+ result = await single_handler(request, handler)
+ return _normalize_to_model_response(result)
+
+ return normalized_single
def compose_two(
outer: Callable[
- [ModelRequest, Callable[[ModelRequest], Awaitable[AIMessage]]],
- Awaitable[AIMessage],
+ [ModelRequest, Callable[[ModelRequest], Awaitable[ModelResponse]]],
+ Awaitable[ModelResponse | AIMessage],
],
inner: Callable[
- [ModelRequest, Callable[[ModelRequest], Awaitable[AIMessage]]],
- Awaitable[AIMessage],
+ [ModelRequest, Callable[[ModelRequest], Awaitable[ModelResponse]]],
+ Awaitable[ModelResponse | AIMessage],
],
) -> Callable[
- [ModelRequest, Callable[[ModelRequest], Awaitable[AIMessage]]],
- Awaitable[AIMessage],
+ [ModelRequest, Callable[[ModelRequest], Awaitable[ModelResponse]]],
+ Awaitable[ModelResponse],
]:
"""Compose two async handlers where outer wraps inner."""
async def composed(
request: ModelRequest,
- handler: Callable[[ModelRequest], Awaitable[AIMessage]],
- ) -> AIMessage:
- # Create a wrapper that calls inner with the base handler
- async def inner_handler(req: ModelRequest) -> AIMessage:
- return await inner(req, handler)
+ handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+ ) -> ModelResponse:
+ # Create a wrapper that calls inner with the base handler and normalizes
+ async def inner_handler(req: ModelRequest) -> ModelResponse:
+ inner_result = await inner(req, handler)
+ return _normalize_to_model_response(inner_result)
- # Call outer with the wrapped inner as its handler
- return await outer(request, inner_handler)
+ # Call outer with the wrapped inner as its handler and normalize
+ outer_result = await outer(request, inner_handler)
+ return _normalize_to_model_response(outer_result)
return composed
@@ -236,7 +258,16 @@ def _chain_async_model_call_handlers(
for handler in reversed(handlers[:-1]):
result = compose_two(handler, result)
- return result
+ # Wrap to ensure final return type is exactly ModelResponse
+ async def final_normalized(
+ request: ModelRequest,
+ handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+ ) -> ModelResponse:
+ # result here is typed as returning ModelResponse | AIMessage but compose_two normalizes
+ final_result = await result(request, handler)
+ return _normalize_to_model_response(final_result)
+
+ return final_normalized
def _resolve_schema(schemas: set[type], schema_name: str, omit_flag: str | None = None) -> type:
@@ -857,31 +888,29 @@ def create_agent( # noqa: PLR0915
)
return request.model.bind(**request.model_settings), None
- def _execute_model_sync(request: ModelRequest) -> _InternalModelResponse:
- """Execute model and return result or exception.
+ def _execute_model_sync(request: ModelRequest) -> ModelResponse:
+ """Execute model and return response.
This is the core model execution logic wrapped by wrap_model_call handlers.
+ Raises any exceptions that occur during model invocation.
"""
- try:
- # Get the bound model (with auto-detection if needed)
- model_, effective_response_format = _get_bound_model(request)
- messages = request.messages
- if request.system_prompt:
- messages = [SystemMessage(request.system_prompt), *messages]
-
- output = model_.invoke(messages)
- return _InternalModelResponse(
- result=output,
- exception=None,
- effective_response_format=effective_response_format,
- )
- except Exception as error: # noqa: BLE001
- # Catch all exceptions from model invocation
- return _InternalModelResponse(
- result=None,
- exception=error,
- effective_response_format=None,
- )
+ # Get the bound model (with auto-detection if needed)
+ model_, effective_response_format = _get_bound_model(request)
+ messages = request.messages
+ if request.system_prompt:
+ messages = [SystemMessage(request.system_prompt), *messages]
+
+ output = model_.invoke(messages)
+
+ # Handle model output to get messages and structured_response
+ handled_output = _handle_model_output(output, effective_response_format)
+ messages_list = handled_output["messages"]
+ structured_response = handled_output.get("structured_response")
+
+ return ModelResponse(
+ result=messages_list,
+ structured_response=structured_response,
+ )
def model_node(state: AgentState, runtime: Runtime[ContextT]) -> dict[str, Any]:
"""Sync model request handler with sequential middleware processing."""
@@ -896,58 +925,47 @@ def create_agent( # noqa: PLR0915
runtime=runtime,
)
- # Execute with or without handler
- effective_response_format: Any = None
-
- # Define base handler that executes the model
- def base_handler(req: ModelRequest) -> AIMessage:
- nonlocal effective_response_format
- internal_response = _execute_model_sync(req)
- if internal_response.exception is not None:
- raise internal_response.exception
- if internal_response.result is None:
- msg = "Model execution succeeded but returned no result"
- raise RuntimeError(msg)
- effective_response_format = internal_response.effective_response_format
- return internal_response.result
-
if wrap_model_call_handler is None:
# No handlers - execute directly
- output = base_handler(request)
+ response = _execute_model_sync(request)
else:
# Call composed handler with base handler
- output = wrap_model_call_handler(request, base_handler)
+ response = wrap_model_call_handler(request, _execute_model_sync)
+
+ # Extract state updates from ModelResponse
+ state_updates = {"messages": response.result}
+ if response.structured_response is not None:
+ state_updates["structured_response"] = response.structured_response
+
return {
"thread_model_call_count": state.get("thread_model_call_count", 0) + 1,
"run_model_call_count": state.get("run_model_call_count", 0) + 1,
- **_handle_model_output(output, effective_response_format),
+ **state_updates,
}
- async def _execute_model_async(request: ModelRequest) -> _InternalModelResponse:
- """Execute model asynchronously and return result or exception.
+ async def _execute_model_async(request: ModelRequest) -> ModelResponse:
+ """Execute model asynchronously and return response.
This is the core async model execution logic wrapped by wrap_model_call handlers.
+ Raises any exceptions that occur during model invocation.
"""
- try:
- # Get the bound model (with auto-detection if needed)
- model_, effective_response_format = _get_bound_model(request)
- messages = request.messages
- if request.system_prompt:
- messages = [SystemMessage(request.system_prompt), *messages]
-
- output = await model_.ainvoke(messages)
- return _InternalModelResponse(
- result=output,
- exception=None,
- effective_response_format=effective_response_format,
- )
- except Exception as error: # noqa: BLE001
- # Catch all exceptions from model invocation
- return _InternalModelResponse(
- result=None,
- exception=error,
- effective_response_format=None,
- )
+ # Get the bound model (with auto-detection if needed)
+ model_, effective_response_format = _get_bound_model(request)
+ messages = request.messages
+ if request.system_prompt:
+ messages = [SystemMessage(request.system_prompt), *messages]
+
+ output = await model_.ainvoke(messages)
+
+ # Handle model output to get messages and structured_response
+ handled_output = _handle_model_output(output, effective_response_format)
+ messages_list = handled_output["messages"]
+ structured_response = handled_output.get("structured_response")
+
+ return ModelResponse(
+ result=messages_list,
+ structured_response=structured_response,
+ )
async def amodel_node(state: AgentState, runtime: Runtime[ContextT]) -> dict[str, Any]:
"""Async model request handler with sequential middleware processing."""
@@ -962,31 +980,22 @@ def create_agent( # noqa: PLR0915
runtime=runtime,
)
- # Execute with or without handler
- effective_response_format: Any = None
-
- # Define base async handler that executes the model
- async def base_handler(req: ModelRequest) -> AIMessage:
- nonlocal effective_response_format
- internal_response = await _execute_model_async(req)
- if internal_response.exception is not None:
- raise internal_response.exception
- if internal_response.result is None:
- msg = "Model execution succeeded but returned no result"
- raise RuntimeError(msg)
- effective_response_format = internal_response.effective_response_format
- return internal_response.result
-
if awrap_model_call_handler is None:
# No async handlers - execute directly
- output = await base_handler(request)
+ response = await _execute_model_async(request)
else:
# Call composed async handler with base handler
- output = await awrap_model_call_handler(request, base_handler)
+ response = await awrap_model_call_handler(request, _execute_model_async)
+
+ # Extract state updates from ModelResponse
+ state_updates = {"messages": response.result}
+ if response.structured_response is not None:
+ state_updates["structured_response"] = response.structured_response
+
return {
"thread_model_call_count": state.get("thread_model_call_count", 0) + 1,
"run_model_call_count": state.get("run_model_call_count", 0) + 1,
- **_handle_model_output(output, effective_response_format),
+ **state_updates,
}
# Use sync or async based on model capabilities
diff --git a/libs/langchain_v1/langchain/agents/middleware/context_editing.py b/libs/langchain_v1/langchain/agents/middleware/context_editing.py
index c26e28dc33..a0d9084572 100644
--- a/libs/langchain_v1/langchain/agents/middleware/context_editing.py
+++ b/libs/langchain_v1/langchain/agents/middleware/context_editing.py
@@ -22,7 +22,12 @@ from langchain_core.messages import (
from langchain_core.messages.utils import count_tokens_approximately
from typing_extensions import Protocol
-from langchain.agents.middleware.types import AgentMiddleware, ModelRequest
+from langchain.agents.middleware.types import (
+ AgentMiddleware,
+ ModelCallResult,
+ ModelRequest,
+ ModelResponse,
+)
DEFAULT_TOOL_PLACEHOLDER = "[cleared]"
@@ -209,8 +214,8 @@ class ContextEditingMiddleware(AgentMiddleware):
def wrap_model_call(
self,
request: ModelRequest,
- handler: Callable[[ModelRequest], AIMessage],
- ) -> AIMessage:
+ handler: Callable[[ModelRequest], ModelResponse],
+ ) -> ModelCallResult:
"""Apply context edits before invoking the model via handler."""
if not request.messages:
return handler(request)
diff --git a/libs/langchain_v1/langchain/agents/middleware/model_fallback.py b/libs/langchain_v1/langchain/agents/middleware/model_fallback.py
index 048eb8edb8..c4d4f6b9cb 100644
--- a/libs/langchain_v1/langchain/agents/middleware/model_fallback.py
+++ b/libs/langchain_v1/langchain/agents/middleware/model_fallback.py
@@ -6,7 +6,9 @@ from typing import TYPE_CHECKING
from langchain.agents.middleware.types import (
AgentMiddleware,
+ ModelCallResult,
ModelRequest,
+ ModelResponse,
)
from langchain.chat_models import init_chat_model
@@ -14,7 +16,6 @@ if TYPE_CHECKING:
from collections.abc import Callable
from langchain_core.language_models.chat_models import BaseChatModel
- from langchain_core.messages import AIMessage
class ModelFallbackMiddleware(AgentMiddleware):
@@ -68,8 +69,8 @@ class ModelFallbackMiddleware(AgentMiddleware):
def wrap_model_call(
self,
request: ModelRequest,
- handler: Callable[[ModelRequest], AIMessage],
- ) -> AIMessage:
+ handler: Callable[[ModelRequest], ModelResponse],
+ ) -> ModelCallResult:
"""Try fallback models in sequence on errors.
Args:
diff --git a/libs/langchain_v1/langchain/agents/middleware/planning.py b/libs/langchain_v1/langchain/agents/middleware/planning.py
index 3278ed8f12..991dffa11a 100644
--- a/libs/langchain_v1/langchain/agents/middleware/planning.py
+++ b/libs/langchain_v1/langchain/agents/middleware/planning.py
@@ -8,12 +8,18 @@ from typing import TYPE_CHECKING, Annotated, Literal
if TYPE_CHECKING:
from collections.abc import Callable
-from langchain_core.messages import AIMessage, ToolMessage
+from langchain_core.messages import ToolMessage
from langchain_core.tools import tool
from langgraph.types import Command
from typing_extensions import NotRequired, TypedDict
-from langchain.agents.middleware.types import AgentMiddleware, AgentState, ModelRequest
+from langchain.agents.middleware.types import (
+ AgentMiddleware,
+ AgentState,
+ ModelCallResult,
+ ModelRequest,
+ ModelResponse,
+)
from langchain.tools import InjectedToolCallId
@@ -189,8 +195,8 @@ class PlanningMiddleware(AgentMiddleware):
def wrap_model_call(
self,
request: ModelRequest,
- handler: Callable[[ModelRequest], AIMessage],
- ) -> AIMessage:
+ handler: Callable[[ModelRequest], ModelResponse],
+ ) -> ModelCallResult:
"""Update the system prompt to include the todo system prompt."""
request.system_prompt = (
request.system_prompt + "\n\n" + self.system_prompt
diff --git a/libs/langchain_v1/langchain/agents/middleware/prompt_caching.py b/libs/langchain_v1/langchain/agents/middleware/prompt_caching.py
index ae640a7459..2c918e97c2 100644
--- a/libs/langchain_v1/langchain/agents/middleware/prompt_caching.py
+++ b/libs/langchain_v1/langchain/agents/middleware/prompt_caching.py
@@ -4,9 +4,12 @@ from collections.abc import Callable
from typing import Literal
from warnings import warn
-from langchain_core.messages import AIMessage
-
-from langchain.agents.middleware.types import AgentMiddleware, ModelRequest
+from langchain.agents.middleware.types import (
+ AgentMiddleware,
+ ModelCallResult,
+ ModelRequest,
+ ModelResponse,
+)
class AnthropicPromptCachingMiddleware(AgentMiddleware):
@@ -45,8 +48,8 @@ class AnthropicPromptCachingMiddleware(AgentMiddleware):
def wrap_model_call(
self,
request: ModelRequest,
- handler: Callable[[ModelRequest], AIMessage],
- ) -> AIMessage:
+ handler: Callable[[ModelRequest], ModelResponse],
+ ) -> ModelCallResult:
"""Modify the model request to add cache control blocks."""
try:
from langchain_anthropic import ChatAnthropic
diff --git a/libs/langchain_v1/langchain/agents/middleware/tool_selection.py b/libs/langchain_v1/langchain/agents/middleware/tool_selection.py
index f63fb68be7..b674673815 100644
--- a/libs/langchain_v1/langchain/agents/middleware/tool_selection.py
+++ b/libs/langchain_v1/langchain/agents/middleware/tool_selection.py
@@ -12,11 +12,16 @@ if TYPE_CHECKING:
from langchain.tools import BaseTool
from langchain_core.language_models.chat_models import BaseChatModel
-from langchain_core.messages import AIMessage, HumanMessage
+from langchain_core.messages import HumanMessage
from pydantic import Field, TypeAdapter
from typing_extensions import TypedDict
-from langchain.agents.middleware.types import AgentMiddleware, ModelRequest
+from langchain.agents.middleware.types import (
+ AgentMiddleware,
+ ModelCallResult,
+ ModelRequest,
+ ModelResponse,
+)
from langchain.chat_models.base import init_chat_model
logger = logging.getLogger(__name__)
@@ -245,8 +250,8 @@ class LLMToolSelectorMiddleware(AgentMiddleware):
def wrap_model_call(
self,
request: ModelRequest,
- handler: Callable[[ModelRequest], AIMessage],
- ) -> AIMessage:
+ handler: Callable[[ModelRequest], ModelResponse],
+ ) -> ModelCallResult:
"""Filter tools based on LLM selection before invoking the model via handler."""
selection_request = self._prepare_selection_request(request)
if selection_request is None:
@@ -276,8 +281,8 @@ class LLMToolSelectorMiddleware(AgentMiddleware):
async def awrap_model_call(
self,
request: ModelRequest,
- handler: Callable[[ModelRequest], Awaitable[AIMessage]],
- ) -> AIMessage:
+ handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+ ) -> ModelCallResult:
"""Filter tools based on LLM selection before invoking the model via handler."""
selection_request = self._prepare_selection_request(request)
if selection_request is None:
diff --git a/libs/langchain_v1/langchain/agents/middleware/types.py b/libs/langchain_v1/langchain/agents/middleware/types.py
index d0cc40b377..39eb5ba4a3 100644
--- a/libs/langchain_v1/langchain/agents/middleware/types.py
+++ b/libs/langchain_v1/langchain/agents/middleware/types.py
@@ -22,7 +22,9 @@ if TYPE_CHECKING:
from langchain.tools.tool_node import ToolCallRequest
# needed as top level import for pydantic schema generation on AgentState
-from langchain_core.messages import AIMessage, AnyMessage, ToolMessage # 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
@@ -42,6 +44,7 @@ __all__ = [
"AgentState",
"ContextT",
"ModelRequest",
+ "ModelResponse",
"OmitFromSchema",
"PublicAgentState",
"after_agent",
@@ -74,6 +77,31 @@ class ModelRequest:
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."""
@@ -167,23 +195,23 @@ class AgentMiddleware(Generic[StateT, ContextT]):
def wrap_model_call(
self,
request: ModelRequest,
- handler: Callable[[ModelRequest], AIMessage],
- ) -> AIMessage:
+ handler: Callable[[ModelRequest], ModelResponse],
+ ) -> ModelCallResult:
"""Intercept and control model execution via handler callback.
- The handler callback executes the model request and returns an AIMessage.
+ 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:
request: Model request to execute (includes state and runtime).
- handler: Callback that executes the model request and returns AIMessage.
+ 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:
- Final AIMessage to use (from handler or custom).
+ ModelCallResult
Examples:
Retry on error:
@@ -200,8 +228,12 @@ class AgentMiddleware(Generic[StateT, ContextT]):
Rewrite response:
```python
def wrap_model_call(self, request, handler):
- result = handler(request)
- return AIMessage(content=f"[{result.content}]")
+ 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:
@@ -210,7 +242,7 @@ class AgentMiddleware(Generic[StateT, ContextT]):
try:
return handler(request)
except Exception:
- return AIMessage(content="Service unavailable")
+ return ModelResponse(result=[AIMessage(content="Service unavailable")])
```
Cache/short-circuit:
@@ -218,9 +250,17 @@ class AgentMiddleware(Generic[StateT, ContextT]):
def wrap_model_call(self, request, handler):
if cached := get_cache(request):
return cached # Short-circuit with cached result
- result = handler(request)
- save_cache(request, result)
- return 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")
```
"""
raise NotImplementedError
@@ -228,8 +268,8 @@ class AgentMiddleware(Generic[StateT, ContextT]):
async def awrap_model_call(
self,
request: ModelRequest,
- handler: Callable[[ModelRequest], Awaitable[AIMessage]],
- ) -> AIMessage:
+ handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+ ) -> ModelCallResult:
"""Async version of wrap_model_call.
Args:
@@ -237,7 +277,7 @@ class AgentMiddleware(Generic[StateT, ContextT]):
handler: Async callback that executes the model request.
Returns:
- Final AIMessage to use (from handler or custom).
+ ModelCallResult
Examples:
Retry on error:
@@ -337,14 +377,14 @@ class _CallableReturningPromptString(Protocol[StateT_contra, ContextT]): # type
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 final AIMessage.
+ Receives handler callback to execute model and returns ModelResponse or AIMessage.
"""
def __call__(
self,
request: ModelRequest,
- handler: Callable[[ModelRequest], AIMessage],
- ) -> AIMessage:
+ handler: Callable[[ModelRequest], ModelResponse],
+ ) -> ModelCallResult:
"""Intercept model execution via handler callback."""
...
@@ -1037,8 +1077,8 @@ def dynamic_prompt(
async def async_wrapped(
self: AgentMiddleware[StateT, ContextT], # noqa: ARG001
request: ModelRequest,
- handler: Callable[[ModelRequest], Awaitable[AIMessage]],
- ) -> AIMessage:
+ handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+ ) -> ModelCallResult:
prompt = await func(request) # type: ignore[misc]
request.system_prompt = prompt
return await handler(request)
@@ -1058,8 +1098,8 @@ def dynamic_prompt(
def wrapped(
self: AgentMiddleware[StateT, ContextT], # noqa: ARG001
request: ModelRequest,
- handler: Callable[[ModelRequest], AIMessage],
- ) -> AIMessage:
+ handler: Callable[[ModelRequest], ModelResponse],
+ ) -> ModelCallResult:
prompt = cast("str", func(request))
request.system_prompt = prompt
return handler(request)
@@ -1120,7 +1160,8 @@ def wrap_model_call(
Args:
func: Function accepting (request, handler) that calls handler(request)
- to execute the model and returns final AIMessage. Request contains state and runtime.
+ 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.
@@ -1157,12 +1198,24 @@ def wrap_model_call(
return handler(request)
```
- Rewrite response content:
+ Rewrite response content (full ModelResponse):
```python
@wrap_model_call
def uppercase_responses(request, handler):
- result = handler(request)
- return AIMessage(content=result.content.upper())
+ 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")
```
"""
@@ -1176,8 +1229,8 @@ def wrap_model_call(
async def async_wrapped(
self: AgentMiddleware[StateT, ContextT], # noqa: ARG001
request: ModelRequest,
- handler: Callable[[ModelRequest], Awaitable[AIMessage]],
- ) -> AIMessage:
+ handler: Callable[[ModelRequest], Awaitable[ModelResponse]],
+ ) -> ModelCallResult:
return await func(request, handler) # type: ignore[misc, arg-type]
middleware_name = name or cast(
@@ -1197,8 +1250,8 @@ def wrap_model_call(
def wrapped(
self: AgentMiddleware[StateT, ContextT], # noqa: ARG001
request: ModelRequest,
- handler: Callable[[ModelRequest], AIMessage],
- ) -> AIMessage:
+ handler: Callable[[ModelRequest], ModelResponse],
+ ) -> ModelCallResult:
return func(request, handler)
middleware_name = name or cast("str", getattr(func, "__name__", "WrapModelCallMiddleware"))
diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/test_wrap_model_call_decorator.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/test_wrap_model_call_decorator.py
index 17b201d313..29194b484d 100644
--- a/libs/langchain_v1/tests/unit_tests/agents/middleware/test_wrap_model_call_decorator.py
+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/test_wrap_model_call_decorator.py
@@ -77,7 +77,9 @@ class TestOnModelCallDecorator:
@wrap_model_call
def uppercase_responses(request, handler):
result = handler(request)
- return AIMessage(content=result.content.upper())
+ # result is ModelResponse, extract AIMessage from it
+ ai_message = result.result[0]
+ return AIMessage(content=ai_message.content.upper())
model = GenericFakeChatModel(messages=iter([AIMessage(content="hello world")]))
agent = create_agent(model=model, middleware=[uppercase_responses])
@@ -336,9 +338,11 @@ class TestOnModelCallDecorator:
@wrap_model_call
def multi_transform(request, handler):
result = handler(request)
+ # result is ModelResponse, extract AIMessage from it
+ ai_message = result.result[0]
# First transformation: uppercase
- content = result.content.upper()
+ content = ai_message.content.upper()
# Second transformation: add prefix and suffix
content = f"[START] {content} [END]"
return AIMessage(content=content)
diff --git a/libs/langchain_v1/tests/unit_tests/agents/middleware/test_wrap_model_call_middleware.py b/libs/langchain_v1/tests/unit_tests/agents/middleware/test_wrap_model_call_middleware.py
index 893432bd51..80674bcd6b 100644
--- a/libs/langchain_v1/tests/unit_tests/agents/middleware/test_wrap_model_call_middleware.py
+++ b/libs/langchain_v1/tests/unit_tests/agents/middleware/test_wrap_model_call_middleware.py
@@ -153,7 +153,9 @@ class TestResponseRewriting:
class UppercaseMiddleware(AgentMiddleware):
def wrap_model_call(self, request, handler):
result = handler(request)
- return AIMessage(content=result.content.upper())
+ # result is ModelResponse, extract AIMessage from it
+ ai_message = result.result[0]
+ return AIMessage(content=ai_message.content.upper())
model = GenericFakeChatModel(messages=iter([AIMessage(content="hello world")]))
agent = create_agent(model=model, middleware=[UppercaseMiddleware()])
@@ -172,7 +174,9 @@ class TestResponseRewriting:
def wrap_model_call(self, request, handler):
result = handler(request)
- return AIMessage(content=f"{self.prefix}{result.content}")
+ # result is ModelResponse, extract AIMessage from it
+ ai_message = result.result[0]
+ return AIMessage(content=f"{self.prefix}{ai_message.content}")
model = GenericFakeChatModel(messages=iter([AIMessage(content="Response")]))
agent = create_agent(model=model, middleware=[PrefixMiddleware(prefix="[BOT]: ")])
@@ -511,12 +515,16 @@ class TestMiddlewareComposition:
class PrefixMiddleware(AgentMiddleware):
def wrap_model_call(self, request, handler):
result = handler(request)
- return AIMessage(content=f"[PREFIX] {result.content}")
+ # result is ModelResponse, extract AIMessage from it
+ ai_message = result.result[0]
+ return AIMessage(content=f"[PREFIX] {ai_message.content}")
class SuffixMiddleware(AgentMiddleware):
def wrap_model_call(self, request, handler):
result = handler(request)
- return AIMessage(content=f"{result.content} [SUFFIX]")
+ # result is ModelResponse, extract AIMessage from it
+ ai_message = result.result[0]
+ return AIMessage(content=f"{ai_message.content} [SUFFIX]")
model = GenericFakeChatModel(messages=iter([AIMessage(content="Middle")]))
# Prefix is outer, Suffix is inner
@@ -551,7 +559,9 @@ class TestMiddlewareComposition:
class UppercaseMiddleware(AgentMiddleware):
def wrap_model_call(self, request, handler):
result = handler(request)
- return AIMessage(content=result.content.upper())
+ # result is ModelResponse, extract AIMessage from it
+ ai_message = result.result[0]
+ return AIMessage(content=ai_message.content.upper())
model = FailOnceThenSucceed(messages=iter([AIMessage(content="success")]))
# Retry outer, Uppercase inner
diff --git a/libs/langchain_v1/tests/unit_tests/agents/test_handler_composition.py b/libs/langchain_v1/tests/unit_tests/agents/test_handler_composition.py
index d8835a90be..65eac87131 100644
--- a/libs/langchain_v1/tests/unit_tests/agents/test_handler_composition.py
+++ b/libs/langchain_v1/tests/unit_tests/agents/test_handler_composition.py
@@ -4,7 +4,7 @@ import pytest
from langchain_core.messages import AIMessage
from langchain.agents.factory import _chain_model_call_handlers
-from langchain.agents.middleware.types import ModelRequest
+from langchain.agents.middleware.types import ModelRequest, ModelResponse
from typing import cast
from langgraph.runtime import Runtime
@@ -27,6 +27,15 @@ def create_test_request(**kwargs):
return ModelRequest(**defaults)
+def create_mock_base_handler(content="test"):
+ """Helper to create a base handler that returns ModelResponse."""
+
+ def mock_base_handler(req):
+ return ModelResponse(result=[AIMessage(content=content)], structured_response=None)
+
+ return mock_base_handler
+
+
class TestChainModelCallHandlers:
"""Test the _chain_model_call_handlers composition function."""
@@ -36,13 +45,15 @@ class TestChainModelCallHandlers:
assert result is None
def test_single_handler_returns_unchanged(self) -> None:
- """Test that single handler is returned without composition."""
+ """Test that single handler is wrapped to normalize output."""
- def handler(request, state, runtime, base_handler):
+ def handler(request, base_handler):
return base_handler(request)
result = _chain_model_call_handlers([handler])
- assert result is handler
+ # Result is wrapped to normalize, so it won't be identical
+ assert result is not None
+ assert callable(result)
def test_two_handlers_basic_composition(self) -> None:
"""Test basic composition of two handlers."""
@@ -63,11 +74,7 @@ class TestChainModelCallHandlers:
composed = _chain_model_call_handlers([outer, inner])
assert composed is not None
- # Execute the composed handler
- def mock_base_handler(req):
- return AIMessage(content="test")
-
- result = composed(create_test_request(), mock_base_handler)
+ result = composed(create_test_request(), create_mock_base_handler())
assert execution_order == [
"outer-before",
@@ -75,7 +82,9 @@ class TestChainModelCallHandlers:
"inner-after",
"outer-after",
]
- assert result.content == "test"
+ # Result is now ModelResponse
+ assert isinstance(result, ModelResponse)
+ assert result.result[0].content == "test"
def test_three_handlers_composition(self) -> None:
"""Test composition of three handlers."""
@@ -102,10 +111,7 @@ class TestChainModelCallHandlers:
composed = _chain_model_call_handlers([first, second, third])
assert composed is not None
- def mock_base_handler(req):
- return AIMessage(content="test")
-
- result = composed(create_test_request(), mock_base_handler)
+ result = composed(create_test_request(), create_mock_base_handler())
# First wraps second wraps third
assert execution_order == [
@@ -116,7 +122,8 @@ class TestChainModelCallHandlers:
"second-after",
"first-after",
]
- assert result.content == "test"
+ assert isinstance(result, ModelResponse)
+ assert result.result[0].content == "test"
def test_inner_handler_retry(self) -> None:
"""Test inner handler retrying before outer sees response."""
@@ -144,12 +151,13 @@ class TestChainModelCallHandlers:
call_count["value"] += 1
if call_count["value"] < 3:
raise ValueError("fail")
- return AIMessage(content="success")
+ return ModelResponse(result=[AIMessage(content="success")], structured_response=None)
result = composed(create_test_request(), mock_base_handler)
assert inner_attempts == [0, 1, 2]
- assert result.content == "success"
+ assert isinstance(result, ModelResponse)
+ assert result.result[0].content == "success"
def test_error_to_success_conversion(self) -> None:
"""Test handler converting error to success response."""
@@ -158,6 +166,7 @@ class TestChainModelCallHandlers:
try:
return handler(request)
except Exception:
+ # Middleware can return AIMessage - it will be normalized to ModelResponse
return AIMessage(content="Fallback response")
def inner_passthrough(request, handler):
@@ -171,7 +180,10 @@ class TestChainModelCallHandlers:
result = composed(create_test_request(), mock_base_handler)
- assert result.content == "Fallback response"
+ # AIMessage was automatically converted to ModelResponse
+ assert isinstance(result, ModelResponse)
+ assert result.result[0].content == "Fallback response"
+ assert result.structured_response is None
def test_request_modification(self) -> None:
"""Test handlers modifying the request."""
@@ -190,13 +202,11 @@ class TestChainModelCallHandlers:
composed = _chain_model_call_handlers([outer_add_context, inner_track_request])
assert composed is not None
- def mock_base_handler(req):
- return AIMessage(content="response")
-
- result = composed(create_test_request(), mock_base_handler)
+ result = composed(create_test_request(), create_mock_base_handler(content="response"))
assert requests_seen == ["Added by outer"]
- assert result.content == "response"
+ assert isinstance(result, ModelResponse)
+ assert result.result[0].content == "response"
def test_composition_preserves_state_and_runtime(self) -> None:
"""Test that state and runtime are passed through composition."""
@@ -219,19 +229,17 @@ class TestChainModelCallHandlers:
test_state = {"test": "state"}
test_runtime = {"test": "runtime"}
- def mock_base_handler(req):
- return AIMessage(content="test")
-
# Create request with state and runtime
test_request = create_test_request()
test_request.state = test_state
test_request.runtime = test_runtime
- result = composed(test_request, mock_base_handler)
+ result = composed(test_request, create_mock_base_handler())
# Both handlers should see same state and runtime
assert state_values == [("outer", test_state), ("inner", test_state)]
assert runtime_values == [("outer", test_runtime), ("inner", test_runtime)]
- assert result.content == "test"
+ assert isinstance(result, ModelResponse)
+ assert result.result[0].content == "test"
def test_multiple_yields_in_retry_loop(self) -> None:
"""Test handler that retries multiple times."""
@@ -257,11 +265,12 @@ class TestChainModelCallHandlers:
attempt["value"] += 1
if attempt["value"] == 1:
raise ValueError("fail")
- return AIMessage(content="ok")
+ return ModelResponse(result=[AIMessage(content="ok")], structured_response=None)
result = composed(create_test_request(), mock_base_handler)
# Outer called once, inner retried so base handler called twice
assert call_count["value"] == 1
assert attempt["value"] == 2
- assert result.content == "ok"
+ assert isinstance(result, ModelResponse)
+ assert result.result[0].content == "ok"
diff --git a/libs/langchain_v1/tests/unit_tests/agents/test_middleware_agent.py b/libs/langchain_v1/tests/unit_tests/agents/test_middleware_agent.py
index 0aeb70828f..a385cc161c 100644
--- a/libs/langchain_v1/tests/unit_tests/agents/test_middleware_agent.py
+++ b/libs/langchain_v1/tests/unit_tests/agents/test_middleware_agent.py
@@ -2568,8 +2568,10 @@ def test_wrap_model_call_rewrite_response() -> None:
def wrap_model_call(self, request, handler):
result = handler(request)
+ # result is ModelResponse, extract AIMessage from it
+ ai_message = result.result[0]
# Rewrite the response
- return AIMessage(content=f"REWRITTEN: {result.content}")
+ return AIMessage(content=f"REWRITTEN: {ai_message.content}")
model = SimpleModel()
middleware = ResponseRewriteMiddleware()