Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(middleware): support 2.0 middlewares in the agent class (#1565)
DavdGaoc7e20ce7e9f5
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yamlindex 84b963f8b..a6dadac4e 100644--- a/.pre-commit-config.yaml+++ b/.pre-commit-config.yaml@@ -103,7 +103,7 @@ repos:--max-nested-blocks=7,--max-statements=100,--max-returns=10,- --max-module-lines=2000,+ --max-module-lines=3000,]- repo: https://github.com/regebro/pyromarev: "5.0"diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.pyindex 99dbd6499..b44a8f284 100644--- a/src/agentscope/agent/_agent.py+++ b/src/agentscope/agent/_agent.py@@ -1,21 +1,21 @@# -*- coding: utf-8 -*-"""The unified agent class in AgentScope library."""import asyncio+import inspectimport uuidfrom asyncio import Queuefrom copy import deepcopy-from typing import Any, AsyncGenerator, Sequence, Literal, List+from typing import (+ Any,+ AsyncGenerator,+ Sequence,+ Literal,+ List,+)import jsonschema-from pydantic import (- BaseModel,- Field,- SerializeAsAny,- PrivateAttr,- ConfigDict,-)-from ._config import CompressionConfig+from ._config import CompressionConfig, ReActConfig, ModelConfigfrom ..state import AgentStatefrom ._utils import _ToolCallBatchfrom .._logging import logger@@ -49,6 +49,7 @@ from ..event import (ExceedMaxItersEvent,)from ..exception import AgentOrientedException+from ..middleware import MiddlewareBasefrom ..model import (ChatResponse,ChatUsage,@@ -82,104 +83,54 @@ from ..permission import ()-class ReasoningConfig(BaseModel):- """The reasoning related configuration"""-- max_iters: int = 20- """The maximum number of iterations for the reasoning-acting loop."""---class ActingConfig(BaseModel):- """The acting related configuration in AgentScope"""-- parallel: bool = True- """Whether to execute tool calls in parallel when there are multiple tool- calls awaiting execution."""+class Agent:+ """The agent class."""+ def __init__(+ self,+ name: str,+ system_prompt: str,+ model: ChatModelBase,+ toolkit: Toolkit,+ middlewares: list[MiddlewareBase] | None = None,+ state: AgentState | None = None,+ model_config: ModelConfig = ModelConfig(),+ compression_config: CompressionConfig = CompressionConfig(),+ react_config: ReActConfig = ReActConfig(),+ ) -> None:+ self.name = name+ self._system_prompt = system_prompt+ self.model = model+ self.toolkit = toolkit+ self.state = state or AgentState()-class Agent(BaseModel):- """The agent class."""+ self.model_config = model_config+ self.compression_config = compression_config+ self.react_config = react_config- model_config = ConfigDict(arbitrary_types_allowed=True)-- name: str = Field(description="The identifier of the agent.")- """The name of the agent."""-- system_prompt: str = Field(default="You're a helpful assistant.")- """The base system prompt of the agent, extra hints will be attached to- this prompt during agent's reply."""-- model: SerializeAsAny[ChatModelBase] = Field(- description="The language model used by the agent.",- )- """The language model used by the agent."""-- max_retries: int = Field(- default=10,- gt=0,- description="Maximum number of retries when the model call fails.",- )- """The maximum number of retries when the model call fails. Must be- greater than 0."""-- fallback_model: SerializeAsAny[ChatModelBase] | None = Field(- default=None,- description="The fallback model used when the main model fails.",- )- """The fallback model used when the main model fails. Also supports the- max_retries logic."""-- compression: CompressionConfig = Field(- default_factory=CompressionConfig,- description="The compression related configuration for the agent.",- )- """The agent compression related configuration."""-- reasoning: ReasoningConfig = Field(- default_factory=ReasoningConfig,- description="The reasoning related configuration for the agent.",- )- """The reasoning related configuration for the agent."""-- acting: ActingConfig = Field(- default_factory=ActingConfig,- description="The acting related configuration for the agent.",- )- """The acting, i.e. tool execution, related configuration for the agent."""-- state: AgentState = Field(default_factory=AgentState)- """The agent state, including the conversation context, permission context,- tool context, etc."""-- toolkit: Toolkit = Field(exclude=True)- """The toolkit used by the agent."""-- _engine: PermissionEngine = PrivateAttr()- """The permission engine used to manage the tool usage permissions for the- agent."""-- # @field_validator("model", "fallback_model", mode="before")- # @classmethod- # def validate_model(cls, v: Any, info: ValidationInfo) -> Any:- # """Deserialize model from dict using context-injected custom- # classes."""- # if not isinstance(v, dict):- # return v- # custom_classes = (- # info.context.get("custom_model_classes", [])- # if info.context- # else []- # )- # return _deserialize_model(- # v,- # custom_classes=custom_classes,- # context=info.context,- # )-- def model_post_init(self, __context: Any) -> None:- """Initialize the permission engine after the model is initialized."""self._engine = PermissionEngine(self.state.permission_context)+ # ====================================================================+ # The Middleware-related attributes+ # ====================================================================+ # Filter middlewares by implemented hooks (only once)+ middlewares = middlewares or []+ self._reply_middlewares = [+ _ for _ in middlewares if _.is_implemented("on_reply")+ ]+ self._reasoning_middlewares = [+ _ for _ in middlewares if _.is_implemented("on_reasoning")+ ]+ self._acting_middlewares = [+ _ for _ in middlewares if _.is_implemented("on_acting")+ ]+ self._model_call_middlewares = [+ _ for _ in middlewares if _.is_implemented("on_model_call")+ ]+ self._system_prompt_middlewares = [+ _ for _ in middlewares if _.is_implemented("on_system_prompt")+ ]+# =======================================================================# Agent public methods# =======================================================================@@ -262,7 +213,7 @@ class Agent(BaseModel):config. Otherwise, use the default compression config in theagent."""- cfg: CompressionConfig = compression_config or self.compression+ cfg: CompressionConfig = compression_config or self.compression_config# Count the current tokenskwargs = await self._prepare_model_input()@@ -438,6 +389,49 @@ class Agent(BaseModel):event: UserConfirmResultEvent| ExternalExecutionResultEvent| None = None,+ ) -> AsyncGenerator[AgentEvent | Msg, None]:+ """Reply entry point (may be wrapped by middleware)."""+ if not self._reply_middlewares:+ async for item in self._reply_impl(msgs=msgs, event=event):+ yield item+ else:++ async def execute_chain(+ index: int = 0,+ msgs: Msg | list[Msg] | None = msgs,+ event: UserConfirmResultEvent+ | ExternalExecutionResultEvent+ | None = event,+ ) -> AsyncGenerator[AgentEvent | Msg, None]:+ if index >= len(self._reply_middlewares):+ async for item in self._reply_impl(msgs=msgs, event=event):+ yield item+ else:+ mw = self._reply_middlewares[index]+ input_kwargs = {"msgs": msgs, "event": event}++ async def next_handler(+ **kwargs: Any,+ ) -> AsyncGenerator[AgentEvent | Msg, None]:+ async for item in execute_chain(index + 1, **kwargs):+ yield item++ async for item in mw.on_reply(+ agent=self,+ input_kwargs=input_kwargs,+ next_handler=next_handler,+ ):+ yield item++ async for item in execute_chain():+ yield item++ async def _reply_impl(+ self,+ msgs: Msg | list[Msg] | None = None,+ event: UserConfirmResultEvent+ | ExternalExecutionResultEvent+ | None = None,) -> AsyncGenerator[AgentEvent | Msg, None]:"""Core reply logic."""# ===================================================================@@ -471,7 +465,7 @@ class Agent(BaseModel):# Step 3: Enter the reasoning-acting loop until reaching max_iters or# no more tool calls to execute# ===================================================================- while self.state.cur_iter < self.reasoning.max_iters:+ while self.state.cur_iter < self.react_config.max_iters:# ===============================================================# Step 3.1:# ===============================================================@@ -583,9 +577,62 @@ class Agent(BaseModel):| ModelCallEndEvent| Msg,None,+ ]:+ """Reasoning entry point (may be wrapped by middleware)."""+ if not self._reasoning_middlewares:+ async for item in self._reasoning_impl(tool_choice=tool_choice):+ yield item+ else:++ async def execute_chain(+ index: int = 0,+ tool_choice: ToolChoice = tool_choice,+ ) -> AsyncGenerator:+ if index >= len(self._reasoning_middlewares):+ async for item in self._reasoning_impl(+ tool_choice=tool_choice,+ ):+ yield item+ else:+ mw = self._reasoning_middlewares[index]+ input_kwargs = {"tool_choice": tool_choice}++ async def next_handler(**kwargs: Any) -> AsyncGenerator:+ async for item in execute_chain(index + 1, **kwargs):+ yield item++ async for item in mw.on_reasoning(+ agent=self,+ input_kwargs=input_kwargs,+ next_handler=next_handler,+ ):+ yield item++ async for item in execute_chain():+ yield item++ async def _reasoning_impl(+ self,+ tool_choice: ToolChoice = "auto",+ ) -> AsyncGenerator[+ ModelCallStartEvent+ | TextBlockStartEvent+ | TextBlockDeltaEvent+ | TextBlockEndEvent+ | ToolCallBlock+ | ToolCallDeltaEvent+ | ToolCallEndEvent+ | ThinkingBlockStartEvent+ | ThinkingBlockDeltaEvent+ | ThinkingBlockEndEvent+ | DataBlockStartEvent+ | DataBlockDeltaEvent+ | DataBlockEndEvent+ | ModelCallEndEvent+ | Msg,+ None,]:"""Core reasoning logic. Yields chunks with is_last flag."""- # TODO: Pass tool schemas from toolkit when toolkit is implementedyield ModelCallStartEvent(reply_id=self.state.reply_id,@@ -605,19 +652,20 @@ class Agent(BaseModel):block_ids: dict = {"text": None, "thinking": None, "tools": []}completed_response: ChatResponse | None = None- if self.model.stream:+ # Check if res is an async generator (streaming response)+ if inspect.isasyncgen(res):async for chunk in res:- # Break if it's the last chunk with completed response+ # Save the last chunk with completed responseif chunk.is_last:completed_response = chunk- break- # Convert the chunk into events- async for evt in self._convert_chat_response_to_event(- block_ids,- chunk,- ):- yield evt+ else:+ # Convert the chunk into events+ async for evt in self._convert_chat_response_to_event(+ block_ids,+ chunk,+ ):+ yield evtelif isinstance(res, ChatResponse):completed_response = res@@ -1095,6 +1143,49 @@ class Agent(BaseModel):| ToolResultDataDeltaEvent| ToolResultEndEvent,None,+ ]:+ """Execute tool call entry point (may be wrapped by middleware)."""+ if not self._acting_middlewares:+ async for item in self._execute_tool_call_impl(tool_call):+ yield item+ else:++ async def execute_chain(+ index: int = 0,+ tool_call: ToolCallBlock = tool_call,+ ) -> AsyncGenerator:+ if index >= len(self._acting_middlewares):+ async for item in self._execute_tool_call_impl(tool_call):+ yield item+ else:+ mw = self._acting_middlewares[index]+ input_kwargs = {"tool_call": tool_call}++ async def next_handler(**kwargs: Any) -> AsyncGenerator:+ async for item in execute_chain(index + 1, **kwargs):+ yield item++ async for item in mw.on_acting(+ agent=self,+ input_kwargs=input_kwargs,+ next_handler=next_handler,+ ):+ yield item++ async for item in execute_chain():+ yield item++ async def _execute_tool_call_impl(+ self,+ tool_call: ToolCallBlock,+ ) -> AsyncGenerator[+ RequireUserConfirmEvent+ | RequireExternalExecutionEvent+ | ToolResultStartEvent+ | ToolResultTextDeltaEvent+ | ToolResultDataDeltaEvent+ | ToolResultEndEvent,+ None,]:"""Execute a single tool call with permission checking.@@ -1452,17 +1543,22 @@ class Agent(BaseModel):# ======================================================================# Agent internal utility methods# ======================================================================-async def _get_system_prompt(self) -> str:"""Get the system prompt of the agent."""- prompt = [self.system_prompt]+ prompt = [self._system_prompt]# Skill related instructionsskill_instructions = await self.toolkit.get_skill_instructions()if skill_instructions:prompt.append(skill_instructions)- return "\n".join(prompt)+ result = "\n".join(prompt)++ # Apply system_prompt middlewares sequentially (transformer pattern)+ for mw in self._system_prompt_middlewares:+ result = await mw.on_system_prompt(self, result)++ return resultasync def _prepare_model_input(self) -> dict[str, Any]:"""A unified method to prepare the chat model input according to@@ -1500,7 +1596,7 @@ class Agent(BaseModel):tools: list[dict],tool_choice: ToolChoice,) -> ChatResponse | AsyncGenerator[ChatResponse, None]:- """Perform model inference and return the response.+ """Perform model inference with retry logic and middleware support.Args:messages (`list[Msg]`):@@ -1520,18 +1616,64 @@ class Agent(BaseModel):# Fallback to the secondary model if the primary model fails after# retries- if self.fallback_model:- models.append(self.fallback_model)+ if self.model_config.fallback_model:+ models.append(self.model_config.fallback_model)last_exception = Nonefor model in models:- for _ in range(self.max_retries):+ for _ in range(self.model_config.max_retries):try:- return await model(- messages=messages,- tools=tools,- tool_choice=tool_choice,- )+ # Apply middleware to wrap the actual model() call+ if not self._model_call_middlewares:+ return await model(+ messages=messages,+ tools=tools,+ tool_choice=tool_choice,+ )+ else:+ # pylint: disable=cell-var-from-loop+ async def execute_chain(+ index: int = 0,+ current_model: ChatModelBase = model,+ messages: list[Msg] = messages,+ tools: list[dict] = tools,+ tool_choice: ToolChoice = tool_choice,+ ) -> ChatResponse | AsyncGenerator[ChatResponse, None]:+ """Execute the model chain."""+ if index >= len(self._model_call_middlewares):+ return await current_model(+ messages=messages,+ tools=tools,+ tool_choice=tool_choice,+ )+ else:+ mw = self._model_call_middlewares[index]+ input_kwargs = {+ "current_model": current_model,+ "messages": messages,+ "tools": tools,+ "tool_choice": tool_choice,+ }++ async def next_handler(+ **kwargs: Any,+ ) -> (+ ChatResponse+ | AsyncGenerator[ChatResponse, None]+ ):+ # pylint: disable=cell-var-from-loop+ return await execute_chain(+ index + 1,+ **kwargs,+ )++ return await mw.on_model_call(+ agent=self,+ input_kwargs=input_kwargs,+ next_handler=next_handler,+ )++ return await execute_chain()except Exception as e:logger.warning("Model %s call failed for agent %s. "@@ -1539,7 +1681,7 @@ class Agent(BaseModel):model.model_name,self.name,_ + 1,- self.max_retries,+ self.model_config.max_retries,)last_exception = ediff --git a/src/agentscope/agent/_config.py b/src/agentscope/agent/_config.pyindex 614b3ea42..d8701eaa8 100644--- a/src/agentscope/agent/_config.py+++ b/src/agentscope/agent/_config.py@@ -3,6 +3,8 @@from pydantic import BaseModel, Field+from ..model import ChatModelBase+class SummarySchema(BaseModel):"""The compressed memory model, used to generate summary of old memories"""@@ -100,3 +102,48 @@ class CompressionConfig(BaseModel):)"""The structured model used to guide the agent to generate thestructured compressed summary."""+++class ReActConfig(BaseModel):+ """The reasoning related configuration"""++ max_iters: int = Field(+ title="Max Iterations",+ default=20,+ description="The maximum number of reasoning-acting iterations in "+ "one reply",+ )+ """The maximum number of iterations for the reasoning-acting loop."""++ stop_on_reject: bool = Field(+ title="Rejection Handling",+ default=False,+ description="Whether to stop replying when being rejected to "+ "execute tools.",+ )+ """If stop reasoning when tool call(s) are rejected. If `True`, the agent+ won't continue reasoning and wait for outside interaction from the user.+ """+++class ModelConfig(BaseModel):+ """The model related configuration."""++ # TODO: remove this line after PR #1564 is merged, where the ChatModel+ # will be child class of BaseModel+ model_config = {"arbitrary_types_allowed": True}++ max_retries: int = Field(+ default=3,+ gt=0,+ description="Maximum number of retries when the model call fails.",+ )+ """The maximum number of retries when the model call fails. Must be+ greater than 0."""++ fallback_model: ChatModelBase | None = Field(+ default=None,+ description="The fallback model used when the main model fails.",+ )+ """The fallback model used when the main model fails. Also supports the+ max_retries logic."""diff --git a/src/agentscope/middleware/__init__.py b/src/agentscope/middleware/__init__.pynew file mode 100644index 000000000..d898ddea4--- /dev/null+++ b/src/agentscope/middleware/__init__.py@@ -0,0 +1,8 @@+# -*- coding: utf-8 -*-+"""Middleware system for AgentScope agents."""++from ._base import MiddlewareBase++__all__ = [+ "MiddlewareBase",+]diff --git a/src/agentscope/middleware/_base.py b/src/agentscope/middleware/_base.pynew file mode 100644index 000000000..88414e90d--- /dev/null+++ b/src/agentscope/middleware/_base.py@@ -0,0 +1,179 @@+# -*- coding: utf-8 -*-+"""Base middleware class for AgentScope middleware system."""+from typing import AsyncGenerator, Awaitable, Callable, Union, TYPE_CHECKING++if TYPE_CHECKING:+ from ..agent import Agent+ from ..model import ChatResponse+++class MiddlewareBase:+ """Base class for all middleware implementations.++ Middleware provides interception mechanisms at 5 key execution points+ in the Agent lifecycle:++ **Onion Pattern Hooks** (with before/after logic):+ - `on_reply`: Intercepts the entire reply process+ - `on_reasoning`: Intercepts the reasoning/model call phase+ - `on_acting`: Intercepts individual tool call execution+ - `on_model_call`: Intercepts the raw model API call++ **Transformer Pattern Hook** (sequential pipeline):+ - `on_system_prompt`: Transforms the system prompt string++ Each hook is optional - only implement the ones you need. The middleware+ system will automatically detect which hooks are implemented at runtime.++ Example:+ ```python+ class LoggingMiddleware(MiddlewareBase):+ async def on_reasoning(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[[], AsyncGenerator],+ ) -> AsyncGenerator:+ print(f"Before reasoning for agent {agent.name}")+ async for event in next_handler():+ yield event+ print(f"After reasoning for agent {agent.name}")++ agent = Agent(+ ...+ middlewares=[LoggingMiddleware()],+ ...+ )+ ```+ """++ def is_implemented(self, hook_name: str) -> bool:+ """Check if a hook method is implemented in the subclass.++ Args:+ hook_name: Name of the hook method to check++ Returns:+ True if the hook is implemented (overridden), False otherwise+ """+ base_method = getattr(MiddlewareBase, hook_name, None)+ sub_method = getattr(type(self), hook_name, None)+ return base_method is not sub_method++ async def on_reply(+ self,+ agent: "Agent",+ input_kwargs: dict,+ next_handler: Callable[..., AsyncGenerator],+ ) -> AsyncGenerator:+ """Hook for intercepting the reply process.++ Args:+ agent: The Agent instance executing this middleware+ input_kwargs: Dictionary containing:+ - msgs: Msg | list[Msg] | None+ - event: UserConfirmResultEvent |+ ExternalExecutionResultEvent | None+ next_handler: Callable that executes the next middleware or+ original method++ Yields:+ AgentEvent | Msg: Events from the reply process+ """+ raise NotImplementedError(+ f"{type(self).__name__} does not implement on_reply",+ )++ async def on_reasoning(+ self,+ agent: "Agent",+ input_kwargs: dict,+ next_handler: Callable[..., AsyncGenerator],+ ) -> AsyncGenerator:+ """Hook for intercepting the reasoning process.++ Args:+ agent: The Agent instance executing this middleware+ input_kwargs: Dictionary containing:+ - tool_choice: ToolChoice (default "auto")+ next_handler: Callable that executes the next middleware or+ original method++ Yields:+ Various events from the reasoning process+ """+ raise NotImplementedError(+ f"{type(self).__name__} does not implement on_reasoning",+ )++ async def on_acting(+ self,+ agent: "Agent",+ input_kwargs: dict,+ next_handler: Callable[..., AsyncGenerator],+ ) -> AsyncGenerator:+ """Hook for intercepting tool call execution.++ Args:+ agent: The Agent instance executing this middleware+ input_kwargs: Dictionary containing:+ - tool_call: ToolCallBlock+ next_handler: Callable that executes the next middleware or+ original method++ Yields:+ Events from the tool execution process+ """+ raise NotImplementedError(+ f"{type(self).__name__} does not implement on_acting",+ )++ async def on_model_call(+ self,+ agent: "Agent",+ input_kwargs: dict,+ next_handler: Callable[+ ...,+ Awaitable["ChatResponse" | AsyncGenerator["ChatResponse", None]],+ ],+ ) -> Union["ChatResponse", AsyncGenerator["ChatResponse", None]]:+ """Hook for intercepting the model API call.++ Args:+ agent: The Agent instance executing this middleware+ input_kwargs: Dictionary containing:+ - messages: list[Msg]+ - tools: list[dict]+ - tool_choice: ToolChoice+ - current_model: The model instance used for this call+ next_handler: Callable that executes the next middleware or+ original method++ Returns:+ ChatResponse or AsyncGenerator[ChatResponse, None]+ """+ raise NotImplementedError(+ f"{type(self).__name__} does not implement on_model_call",+ )++ async def on_system_prompt(+ self,+ agent: "Agent",+ current_prompt: str,+ ) -> str:+ """Transform the system prompt string.++ This uses a transformer/pipeline pattern rather than onion pattern.+ Multiple middlewares are applied sequentially, each receiving the+ output of the previous one.++ Args:+ agent: The Agent instance executing this middleware+ current_prompt: The current system prompt string++ Returns:+ str: The transformed system prompt+ """+ raise NotImplementedError(+ f"{type(self).__name__} does not implement " f"on_system_prompt",+ )diff --git a/tests/context_compression_test.py b/tests/context_compression_test.pyindex ca435f717..82ac3538e 100644--- a/tests/context_compression_test.py+++ b/tests/context_compression_test.py@@ -24,7 +24,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):name="Friday",system_prompt="".join(["0" for _ in range(60 * 4)]),model=MockModel(),- compression=CompressionConfig(+ compression_config=CompressionConfig(trigger_ratio=0.8,reserve_ratio=0.1,),@@ -474,7 +474,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):name="Friday",system_prompt="".join(["0" for _ in range(20 * 4)]),model=model,- compression=CompressionConfig(+ compression_config=CompressionConfig(trigger_ratio=0.7,reserve_ratio=0.4,),diff --git a/tests/middleware_test.py b/tests/middleware_test.pynew file mode 100644index 000000000..0b2b1b989--- /dev/null+++ b/tests/middleware_test.py@@ -0,0 +1,752 @@+# -*- coding: utf-8 -*-+# pylint: disable=abstract-method+"""Unit tests for middleware system."""+from unittest.async_case import IsolatedAsyncioTestCase+from typing import Any, AsyncGenerator, Callable, Union++from utils import MockModel++from agentscope.event import AgentEvent+from agentscope.agent import Agent+from agentscope.middleware import MiddlewareBase+from agentscope.model import ChatResponse+from agentscope.message import TextBlock, UserMsg, Msg+from agentscope.tool import Toolkit+++class TestMiddleware(IsolatedAsyncioTestCase):+ """Test cases for middleware system."""++ async def asyncSetUp(self) -> None:+ """Set up test fixtures."""+ self.mock_model = MockModel()+ self.toolkit = Toolkit()+ self.execution_log = []++ async def test_on_reply_middleware_pre_post_yield(self) -> None:+ """Test on_reply middleware pre, post and yield positions."""++ class ReplyMiddleware(MiddlewareBase):+ """Middleware for testing on_reply hook."""++ def __init__(self, log: list, name: str) -> None:+ """Initialize the reply middleware.++ Args:+ log: The execution log list.+ name: The middleware name.+ """+ self.log = log+ self.name = name++ async def on_reply(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[[], AsyncGenerator],+ ) -> AsyncGenerator:+ """The on_reply middleware logic."""+ self.log.append(f"{self.name}_pre")+ async for item in next_handler():+ if isinstance(item, AgentEvent):+ self.log.append(f"{self.name}_{item.type}")+ elif isinstance(item, Msg):+ self.log.append(f"{self.name}_msg")+ yield item+ self.log.append(f"{self.name}_post")++ middleware1 = ReplyMiddleware(self.execution_log, "mw1")+ middleware2 = ReplyMiddleware(self.execution_log, "mw2")++ self.mock_model.set_responses(+ [+ ChatResponse(+ content=[TextBlock(text="test response")],+ is_last=True,+ ),+ ],+ )++ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ toolkit=self.toolkit,+ middlewares=[middleware1, middleware2],+ )++ await agent.reply(UserMsg("user", "test message"))++ # Verify execution order+ expected = [+ "mw1_pre",+ "mw2_pre",+ "mw2_REPLY_START",+ "mw1_REPLY_START",+ "mw2_MODEL_CALL_START",+ "mw1_MODEL_CALL_START",+ "mw2_TEXT_BLOCK_START",+ "mw1_TEXT_BLOCK_START",+ "mw2_TEXT_BLOCK_DELTA",+ "mw1_TEXT_BLOCK_DELTA",+ "mw2_TEXT_BLOCK_END",+ "mw1_TEXT_BLOCK_END",+ "mw2_MODEL_CALL_END",+ "mw1_MODEL_CALL_END",+ "mw2_REPLY_END",+ "mw1_REPLY_END",+ "mw2_msg",+ "mw1_msg",+ "mw2_post",+ "mw1_post",+ ]+ self.assertListEqual(self.execution_log, expected)++ async def test_on_reasoning_middleware_pre_yield(self) -> None:+ """Test on_reasoning middleware pre and yield positions."""++ class ReasoningMiddleware(MiddlewareBase):+ """Middleware for testing on_reasoning hook."""++ def __init__(self, log: list, name: str) -> None:+ """Initialize the reasoning middleware.++ Args:+ log: The execution log list.+ name: The middleware name.+ """+ self.log = log+ self.name = name++ async def on_reasoning(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[[], AsyncGenerator],+ ) -> AsyncGenerator:+ """The on_reasoning middleware logic."""+ self.log.append(f"{self.name}_pre")+ async for item in next_handler():+ if isinstance(item, AgentEvent):+ self.log.append(f"{self.name}_{item.type}")+ elif isinstance(item, Msg):+ self.log.append(f"{self.name}_msg")+ yield item+ self.log.append(f"{self.name}_post")++ middleware1 = ReasoningMiddleware(self.execution_log, "mw1")+ middleware2 = ReasoningMiddleware(self.execution_log, "mw2")++ self.mock_model.set_responses(+ [+ ChatResponse(+ content=[TextBlock(text="test response")],+ is_last=True,+ ),+ ],+ )++ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ toolkit=self.toolkit,+ middlewares=[middleware1, middleware2],+ )++ await agent.reply(UserMsg("user", "test message"))++ # Verify execution order+ expected = [+ "mw1_pre",+ "mw2_pre",+ "mw2_MODEL_CALL_START",+ "mw1_MODEL_CALL_START",+ "mw2_TEXT_BLOCK_START",+ "mw1_TEXT_BLOCK_START",+ "mw2_TEXT_BLOCK_DELTA",+ "mw1_TEXT_BLOCK_DELTA",+ "mw2_TEXT_BLOCK_END",+ "mw1_TEXT_BLOCK_END",+ "mw2_MODEL_CALL_END",+ "mw1_MODEL_CALL_END",+ "mw2_msg",+ "mw1_msg",+ ]+ self.assertListEqual(self.execution_log, expected)++ async def test_on_model_call_middleware_non_streaming(self) -> None:+ """Test on_model_call middleware for non-streaming model."""++ class ModelCallMiddleware(MiddlewareBase):+ """Middleware for testing on_model_call hook."""++ def __init__(self, log: list, name: str) -> None:+ """Initialize the model call middleware.++ Args:+ log: The execution log list.+ name: The middleware name.+ """+ self.log = log+ self.name = name++ async def on_model_call(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable,+ ) -> Union[ChatResponse, AsyncGenerator[ChatResponse, None]]:+ """The on_model_call middleware logic."""+ self.log.append(f"{self.name}_pre")+ result = await next_handler()+ self.log.append(f"{self.name}_post")+ return result++ middleware1 = ModelCallMiddleware(self.execution_log, "mw1")+ middleware2 = ModelCallMiddleware(self.execution_log, "mw2")++ self.mock_model.set_responses(+ [+ ChatResponse(+ content=[TextBlock(text="test response")],+ is_last=True,+ ),+ ],+ )++ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ toolkit=self.toolkit,+ middlewares=[middleware1, middleware2],+ )++ await agent.reply(UserMsg("user", "test message"))++ # Verify execution order: mw1_pre -> mw2_pre -> mw2_post -> mw1_post+ expected = ["mw1_pre", "mw2_pre", "mw2_post", "mw1_post"]+ self.assertListEqual(self.execution_log, expected)++ async def test_on_model_call_middleware_streaming(self) -> None:+ """Test on_model_call middleware for streaming model."""++ class ModelCallMiddleware(MiddlewareBase):+ """Middleware for testing on_model_call hook with streaming."""++ def __init__(self, log: list, name: str) -> None:+ """Initialize the model call middleware.++ Args:+ log: The execution log list.+ name: The middleware name.+ """+ self.log = log+ self.name = name++ async def on_model_call(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable,+ ) -> Union[ChatResponse, AsyncGenerator[ChatResponse, None]]:+ """The on_model_call middleware logic for streaming."""+ self.log.append(f"{self.name}_pre")+ result = await next_handler()++ async def wrapped_generator() -> AsyncGenerator[+ ChatResponse,+ None,+ ]:+ """Wrap the generator to log yields."""+ async for chunk in result:+ self.log.append(f"{self.name}_chunk")+ yield chunk+ self.log.append(f"{self.name}_post")++ return wrapped_generator()++ middleware1 = ModelCallMiddleware(self.execution_log, "mw1")+ middleware2 = ModelCallMiddleware(self.execution_log, "mw2")++ self.mock_model.set_responses(+ [+ [+ ChatResponse(+ content=[TextBlock(text="chunk1")],+ is_last=False,+ ),+ ChatResponse(+ content=[TextBlock(text="chunk2")],+ is_last=False,+ ),+ ChatResponse(+ content=[TextBlock(text="chunk3")],+ is_last=True,+ ),+ ],+ ],+ )++ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ toolkit=self.toolkit,+ middlewares=[middleware1, middleware2],+ )++ await agent.reply(UserMsg("user", "test message"))++ # Verify execution order+ expected = [+ "mw1_pre",+ "mw2_pre",+ "mw2_chunk",+ "mw1_chunk",+ "mw2_chunk",+ "mw1_chunk",+ "mw2_chunk",+ "mw1_chunk",+ "mw2_post",+ "mw1_post",+ ]+ self.assertListEqual(self.execution_log, expected)++ async def test_on_system_prompt_middleware(self) -> None:+ """Test on_system_prompt middleware (transformer pattern)."""++ class SystemPromptMiddleware(MiddlewareBase):+ """Middleware for testing on_system_prompt hook."""++ def __init__(self, log: list, name: str, suffix: str) -> None:+ """Initialize the system prompt middleware.++ Args:+ log: The execution log list.+ name: The middleware name.+ suffix: The suffix to append to the prompt.+ """+ self.log = log+ self.name = name+ self.suffix = suffix++ async def on_system_prompt(+ self,+ agent: Agent,+ current_prompt: str,+ ) -> str:+ """The on_system_prompt middleware logic."""+ self.log.append(f"{self.name}_executed")+ return f"{current_prompt} {self.suffix}"++ middleware1 = SystemPromptMiddleware(+ self.execution_log,+ "mw1",+ "[MW1]",+ )+ middleware2 = SystemPromptMiddleware(+ self.execution_log,+ "mw2",+ "[MW2]",+ )++ self.mock_model.set_responses(+ [+ ChatResponse(+ content=[TextBlock(text="test response")],+ is_last=True,+ ),+ ],+ )++ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ toolkit=self.toolkit,+ middlewares=[middleware1, middleware2],+ )++ await agent.reply(UserMsg("user", "test message"))++ # Verify execution order: mw1 -> mw2 (sequential transformer pattern)+ # Note: system_prompt is called twice (once for initial setup, once+ # during reasoning)+ expected = [+ "mw1_executed",+ "mw2_executed", # First call+ "mw1_executed",+ "mw2_executed", # Second call during reasoning+ ]+ self.assertListEqual(self.execution_log, expected)++ async def test_multiple_middleware_types(self) -> None:+ """Test multiple middleware types working together."""++ class MultiMiddleware(MiddlewareBase):+ """Middleware implementing multiple hooks."""++ def __init__(self, log: list, name: str) -> None:+ """Initialize the multi middleware.++ Args:+ log: The execution log list.+ name: The middleware name.+ """+ self.log = log+ self.name = name++ async def on_reply(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[[], AsyncGenerator],+ ) -> AsyncGenerator:+ """The on_reply middleware logic."""+ self.log.append(f"{self.name}_reply_pre")+ async for item in next_handler():+ yield item+ self.log.append(f"{self.name}_reply_post")++ async def on_reasoning(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[[], AsyncGenerator],+ ) -> AsyncGenerator:+ """The on_reasoning middleware logic."""+ self.log.append(f"{self.name}_reasoning_pre")+ async for item in next_handler():+ yield item+ self.log.append(f"{self.name}_reasoning_post")++ async def on_model_call(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable,+ ) -> Union[ChatResponse, AsyncGenerator[ChatResponse, None]]:+ """The on_model_call middleware logic."""+ self.log.append(f"{self.name}_model_call_pre")+ result = await next_handler()+ self.log.append(f"{self.name}_model_call_post")+ return result++ async def on_system_prompt(+ self,+ agent: Agent,+ current_prompt: str,+ ) -> str:+ """The on_system_prompt middleware logic."""+ self.log.append(f"{self.name}_system_prompt")+ return current_prompt++ middleware = MultiMiddleware(self.execution_log, "multi")++ self.mock_model.set_responses(+ [+ ChatResponse(+ content=[TextBlock(text="test response")],+ is_last=True,+ ),+ ],+ )++ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ toolkit=self.toolkit,+ middlewares=[middleware],+ )++ await agent.reply(UserMsg("user", "test message"))++ # Verify all middleware hooks were called+ expected = [+ "multi_reply_pre",+ "multi_system_prompt",+ "multi_reasoning_pre",+ "multi_system_prompt",+ "multi_model_call_pre",+ "multi_model_call_post",+ "multi_reply_post",+ ]+ self.assertListEqual(self.execution_log, expected)++ async def test_on_reply_middleware_modify_input(self) -> None:+ """Test that on_reply middleware can modify msgs input."""++ class ModifyMsgsMiddleware(MiddlewareBase):+ """Middleware that modifies the msgs input."""++ async def on_reply(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., AsyncGenerator],+ ) -> AsyncGenerator:+ """Modify msgs before passing to next handler."""+ # Modify the message content+ msgs = input_kwargs["msgs"]+ if isinstance(msgs, Msg):+ modified_msg = UserMsg(+ name=msgs.name,+ content="MODIFIED: " + msgs.content,+ )+ async for item in next_handler(+ msgs=modified_msg,+ event=input_kwargs.get("event"),+ ):+ yield item+ else:+ async for item in next_handler(**input_kwargs):+ yield item++ middleware = ModifyMsgsMiddleware()++ # Track what message the model receives+ received_messages = []++ class TrackingModel(MockModel):+ """Model that tracks received messages."""++ async def _call_api(+ self,+ *args: Any,+ **kwargs: Any,+ ) -> ChatResponse:+ """Track the messages and return mock response."""+ messages = kwargs.get("messages", [])+ received_messages.extend(messages)+ return await super()._call_api(*args, **kwargs)++ tracking_model = TrackingModel()+ tracking_model.set_responses(+ [+ ChatResponse(+ content=[TextBlock(text="response")],+ is_last=True,+ ),+ ],+ )++ agent_instance = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=tracking_model,+ toolkit=self.toolkit,+ middlewares=[middleware],+ )++ await agent_instance.reply(UserMsg("user", "original message"))++ # Verify the model received the modified message+ user_messages = [m for m in received_messages if m.role == "user"]+ self.assertTrue(len(user_messages) > 0)+ self.assertIn("MODIFIED: original message", user_messages[-1].content)++ async def test_on_reasoning_middleware_modify_input(self) -> None:+ """Test that on_reasoning middleware can modify tool_choice input."""++ class ModifyToolChoiceMiddleware(MiddlewareBase):+ """Middleware that modifies the tool_choice input."""++ async def on_reasoning(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., AsyncGenerator],+ ) -> AsyncGenerator:+ """Force tool_choice to 'none' to prevent tool calls."""+ # Override tool_choice to 'none'+ async for item in next_handler(tool_choice="none"):+ yield item++ middleware = ModifyToolChoiceMiddleware()++ # Track what tool_choice the model receives+ received_tool_choices = []++ class TrackingModel(MockModel):+ """Model that tracks received tool_choice."""++ async def _call_api(+ self,+ *args: Any,+ **kwargs: Any,+ ) -> ChatResponse:+ """Track the tool_choice and return mock response."""+ tool_choice = kwargs.get("tool_choice")+ received_tool_choices.append(tool_choice)+ return await super()._call_api(*args, **kwargs)++ tracking_model = TrackingModel()+ tracking_model.set_responses(+ [+ ChatResponse(+ content=[TextBlock(text="response without tools")],+ is_last=True,+ ),+ ],+ )++ agent_instance = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=tracking_model,+ toolkit=self.toolkit,+ middlewares=[middleware],+ )++ await agent_instance.reply(UserMsg("user", "test message"))++ # Verify the model received tool_choice='none'+ self.assertIn("none", received_tool_choices)++ async def test_on_acting_middleware_modify_input(self) -> None:+ """Test that on_acting middleware can modify tool_call input."""+ from agentscope.message import ToolCallBlock++ # Track what tool_call the implementation receives+ received_tool_calls = []++ class ModifyToolCallMiddleware(MiddlewareBase):+ """Middleware that modifies the tool_call input."""++ async def on_acting(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., AsyncGenerator],+ ) -> AsyncGenerator:+ """Modify tool_call.input before execution."""+ tool_call = input_kwargs["tool_call"]+ # Create a modified tool call with different input+ modified_tool_call = ToolCallBlock(+ id=tool_call.id,+ name=tool_call.name,+ input='{"value": "MODIFIED"}',+ state=tool_call.state,+ )+ # Track what we're passing to next handler+ received_tool_calls.append(modified_tool_call.input)+ async for item in next_handler(tool_call=modified_tool_call):+ yield item++ middleware = ModifyToolCallMiddleware()++ # Create a mock agent with the middleware+ agent_instance = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ toolkit=self.toolkit,+ middlewares=[middleware],+ )++ # Directly call _execute_tool_call to test the middleware chain+ original_tool_call = ToolCallBlock(+ id="call_1",+ name="test_tool",+ input='{"value": "ORIGINAL"}',+ )++ # Collect events from the middleware chain+ events = []+ try:+ # pylint: disable=protected-access+ async for evt in agent_instance._execute_tool_call(+ original_tool_call,+ ):+ events.append(evt)+ except Exception:+ # Expected to fail since tool doesn't exist, but we can still+ # verify the middleware modified the input+ pass++ # Verify the middleware modified the tool_call.input+ self.assertEqual(len(received_tool_calls), 1)+ self.assertIn("MODIFIED", received_tool_calls[0])++ async def test_on_model_call_middleware_modify_input(self) -> None:+ """Test that on_model_call middleware can modify messages and model."""++ class ModifyMessagesMiddleware(MiddlewareBase):+ """Middleware that modifies messages input."""++ async def on_model_call(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., Any],+ ) -> Union[ChatResponse, AsyncGenerator[ChatResponse, None]]:+ """Prepend a system message to the messages list."""+ messages = input_kwargs["messages"]+ modified_messages = [+ Msg(+ name="system",+ content="INJECTED SYSTEM MESSAGE",+ role="system",+ ),+ ] + messages++ # Pass modified messages to next handler+ return await next_handler(+ current_model=input_kwargs["current_model"],+ messages=modified_messages,+ tools=input_kwargs["tools"],+ tool_choice=input_kwargs["tool_choice"],+ )++ middleware = ModifyMessagesMiddleware()++ # Track what messages the model receives+ received_messages = []++ class TrackingModel(MockModel):+ """Model that tracks received messages."""++ async def _call_api(+ self,+ *args: Any,+ **kwargs: Any,+ ) -> ChatResponse:+ """Track the messages and return mock response."""+ messages = kwargs.get("messages", [])+ received_messages.extend(messages)+ return await super()._call_api(*args, **kwargs)++ tracking_model = TrackingModel()+ tracking_model.set_responses(+ [+ ChatResponse(+ content=[TextBlock(text="response")],+ is_last=True,+ ),+ ],+ )++ agent_instance = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=tracking_model,+ toolkit=self.toolkit,+ middlewares=[middleware],+ )++ await agent_instance.reply(UserMsg("user", "test message"))++ # Verify the injected system message is present+ system_messages = [m for m in received_messages if m.role == "system"]+ self.assertTrue(+ any(+ "INJECTED SYSTEM MESSAGE" in m.content for m in system_messages+ ),+ )++ async def asyncTearDown(self) -> None:+ """Clean up test fixtures."""+ self.execution_log.clear()