The agent engineering platform.
Python agentsaiai-agentsanthropicchatgptdeepagentsenterpriseframeworkgeminigenerative-ailangchainlanggraphllmmultiagentopen-sourceopenaipydanticpythonragtypescript
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.pyindex 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 annotationsimport itertools-from dataclasses import dataclassfrom 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 resultdef _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 Noneif 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_singledef 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_normalizeddef _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 Noneif 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_singledef 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_normalizeddef _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: PLR0915runtime=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: PLR0915runtime=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 capabilitiesdiff --git a/libs/langchain_v1/langchain/agents/middleware/context_editing.py b/libs/langchain_v1/langchain/agents/middleware/context_editing.pyindex 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_approximatelyfrom 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.pyindex 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_CHECKINGfrom 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 Callablefrom langchain_core.language_models.chat_models import BaseChatModel- from langchain_core.messages import AIMessageclass 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.pyindex 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, Literalif TYPE_CHECKING:from collections.abc import Callable-from langchain_core.messages import AIMessage, ToolMessage+from langchain_core.messages import ToolMessagefrom langchain_core.tools import toolfrom langgraph.types import Commandfrom 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_promptdiff --git a/libs/langchain_v1/langchain/agents/middleware/prompt_caching.py b/libs/langchain_v1/langchain/agents/middleware/prompt_caching.pyindex 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 Callablefrom typing import Literalfrom 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 ChatAnthropicdiff --git a/libs/langchain_v1/langchain/agents/middleware/tool_selection.py b/libs/langchain_v1/langchain/agents/middleware/tool_selection.pyindex 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 BaseToolfrom langchain_core.language_models.chat_models import BaseChatModel-from langchain_core.messages import AIMessage, HumanMessage+from langchain_core.messages import HumanMessagefrom pydantic import Field, TypeAdapterfrom 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_modellogger = 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.pyindex 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: TC002from langgraph.channels.ephemeral_value import EphemeralValuefrom langgraph.channels.untracked_value import UntrackedValuefrom 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+"""++@dataclassclass 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 callingit to short-circuit, or modify the request/response. Multiple middlewarecompose 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 timesfor retry logic. Can skip calling it to short-circuit.Returns:- Final AIMessage to use (from handler or custom).+ ModelCallResultExamples:Retry on error:@@ -200,8 +228,12 @@ class AgentMiddleware(Generic[StateT, ContextT]):Rewrite response:```pythondef 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).+ ModelCallResultExamples:Retry on error:@@ -337,14 +377,14 @@ class _CallableReturningPromptString(Protocol[StateT_contra, ContextT]): # typeclass _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: ARG001request: ModelRequest,- handler: Callable[[ModelRequest], Awaitable[AIMessage]],- ) -> AIMessage:+ handler: Callable[[ModelRequest], Awaitable[ModelResponse]],+ ) -> ModelCallResult:prompt = await func(request) # type: ignore[misc]request.system_prompt = promptreturn await handler(request)@@ -1058,8 +1098,8 @@ def dynamic_prompt(def wrapped(self: AgentMiddleware[StateT, ContextT], # noqa: ARG001request: ModelRequest,- handler: Callable[[ModelRequest], AIMessage],- ) -> AIMessage:+ handler: Callable[[ModelRequest], ModelResponse],+ ) -> ModelCallResult:prompt = cast("str", func(request))request.system_prompt = promptreturn 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_calldef 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: ARG001request: 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: ARG001request: 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.pyindex 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_calldef 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_calldef 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 suffixcontent = 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.pyindex 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 innerdiff --git a/libs/langchain_v1/tests/unit_tests/agents/test_handler_composition.py b/libs/langchain_v1/tests/unit_tests/agents/test_handler_composition.pyindex 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 pytestfrom langchain_core.messages import AIMessagefrom langchain.agents.factory import _chain_model_call_handlers-from langchain.agents.middleware.types import ModelRequest+from langchain.agents.middleware.types import ModelRequest, ModelResponsefrom typing import castfrom 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 Nonedef 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 thirdassert 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"] += 1if 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 ModelResponsereturn 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 Nonedef 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 runtimetest_request = create_test_request()test_request.state = test_statetest_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 runtimeassert 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"] += 1if 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 twiceassert call_count["value"] == 1assert 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.pyindex 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()