Skip to content

Build and run agents you can see, understand and trust.

feat(middleware): support 2.0 middlewares in the agent class (#1565)

DavdGaoc7e20ce7e9f5
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 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/pyroma
rev: "5.0"
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.py
index 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 inspect
import uuid
from asyncio import Queue
from 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, ModelConfig
from ..state import AgentState
from ._utils import _ToolCallBatch
from .._logging import logger
@@ -49,6 +49,7 @@ from ..event import (
ExceedMaxItersEvent,
)
from ..exception import AgentOrientedException
+from ..middleware import MiddlewareBase
from ..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 the
agent.
"""
- cfg: CompressionConfig = compression_config or self.compression
+ cfg: CompressionConfig = compression_config or self.compression_config
# Count the current tokens
kwargs = 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 implemented
yield 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 response
if 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 evt
elif 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 instructions
skill_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 result
async 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 = None
for 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 = e
diff --git a/src/agentscope/agent/_config.py b/src/agentscope/agent/_config.py
index 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 the
structured 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__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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.py
new file mode 100644
index 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()