Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(rag): add `on_compress_context` and `list_tools` methods in the `MiddlewareBase` class to support RAG (#1746)
DavdGao2c9da53c0fff
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.pyindex a6202509f..310db9b58 100644--- a/src/agentscope/agent/_agent.py+++ b/src/agentscope/agent/_agent.py@@ -180,6 +180,9 @@ class Agent:self._system_prompt_middlewares = [_ for _ in middlewares if _.is_implemented("on_system_prompt")]+ self._compress_context_middlewares = [+ _ for _ in middlewares if _.is_implemented("on_compress_context")+ ]# =======================================================================# Agent public methods@@ -260,6 +263,47 @@ class Agent:"""Compress the agent's context if the token count exceeds thethreshold.+ Args:+ context_config (`ContextConfig | None`, optional):+ If provided, compress the context with the given context+ config. Otherwise, use the default context config in the+ agent.+ """+ if not self._compress_context_middlewares:+ await self._compress_context_impl(context_config=context_config)+ else:++ async def execute_chain(+ index: int = 0,+ context_config: ContextConfig | None = context_config,+ ) -> None:+ """Execute the compress_context middleware chain."""+ if index >= len(self._compress_context_middlewares):+ await self._compress_context_impl(+ context_config=context_config,+ )+ else:+ mw = self._compress_context_middlewares[index]+ input_kwargs = {"context_config": context_config}++ async def next_handler(**kwargs: Any) -> None:+ await execute_chain(index + 1, **kwargs)++ await mw.on_compress_context(+ agent=self,+ input_kwargs=input_kwargs,+ next_handler=next_handler,+ )++ await execute_chain()++ async def _compress_context_impl(+ self,+ context_config: ContextConfig | None = None,+ ) -> None:+ """Compress the agent's context if the token count exceeds the+ threshold.+Args:context_config (`ContextConfig | None`, optional):If provided, compress the context with the given contextdiff --git a/src/agentscope/middleware/_base.py b/src/agentscope/middleware/_base.pyindex bec7d510c..5d945b593 100644--- a/src/agentscope/middleware/_base.py+++ b/src/agentscope/middleware/_base.py@@ -1,6 +1,8 @@# -*- coding: utf-8 -*-"""Base middleware class for AgentScope middleware system."""-from typing import AsyncGenerator, Awaitable, Callable, Union, TYPE_CHECKING+from typing import AsyncGenerator, Awaitable, Callable, TYPE_CHECKING++from ..tool import ToolBaseif TYPE_CHECKING:from ..agent import Agent@@ -163,7 +165,7 @@ class MiddlewareBase: # pylint: disable=unused-argument...,Awaitable["ChatResponse" | AsyncGenerator["ChatResponse", None]],],- ) -> Union["ChatResponse", AsyncGenerator["ChatResponse", None]]:+ ) -> "ChatResponse" | AsyncGenerator["ChatResponse", None]:"""Hook for intercepting the model API call.Args:@@ -183,6 +185,28 @@ class MiddlewareBase: # pylint: disable=unused-argumentf"{type(self).__name__} does not implement on_model_call",)+ async def on_compress_context(+ self,+ agent: "Agent",+ input_kwargs: dict,+ next_handler: Callable[..., Awaitable[None]],+ ) -> None:+ """Onion hook for `compress_context` function in `Agent` class++ Args:+ agent (`Agent`):+ The Agent instance executing this middleware+ input_kwargs (`dict`):+ Dictionary containing:+ - context_config: ContextConfig | None+ next_handler (`Callable[..., Awaitable[None]]`):+ Callable that executes the next middleware or+ original method+ """+ raise RuntimeError(+ f"{type(self).__name__} does not implement on_compress_context",+ )+async def on_system_prompt(self,agent: "Agent",@@ -204,3 +228,13 @@ class MiddlewareBase: # pylint: disable=unused-argumentraise RuntimeError(f"{type(self).__name__} does not implement on_system_prompt",)++ async def list_tools(self) -> list[ToolBase]:+ """List available tools provided by this middleware. Optional to+ implement.++ Returns:+ `list[ToolBase]`:+ A list of tools provided by this middleware.+ """+ return []diff --git a/tests/middleware_test.py b/tests/middleware_test.pyindex 0e4ddbcce..a29a00e77 100644--- a/tests/middleware_test.py+++ b/tests/middleware_test.py@@ -2,12 +2,13 @@# pylint: disable=abstract-method"""Unit tests for middleware system."""from unittest.async_case import IsolatedAsyncioTestCase+from unittest.mock import AsyncMock, patchfrom typing import Any, AsyncGenerator, Callable, Unionfrom utils import MockModelfrom pydantic import BaseModelfrom agentscope.event import AgentEvent-from agentscope.agent import Agent+from agentscope.agent import Agent, ContextConfigfrom agentscope.middleware import MiddlewareBasefrom agentscope.model import ChatResponsefrom agentscope.message import (@@ -815,6 +816,172 @@ class TestMiddleware(IsolatedAsyncioTestCase):),)+ async def test_on_compress_context_middleware(self) -> None:+ """Test on_compress_context middleware follows the onion chain pattern.++ Verifies that:+ - Multiple middlewares are chained in onion order (mw1 wraps mw2).+ - ``input_kwargs`` carries the correct ``context_config``.+ - The ``next_handler`` ultimately calls ``_compress_context_impl``.+ - A middleware can short-circuit and skip the actual implementation.+ """++ # ------------------------------------------------------------------ #+ # Middleware that records pre/post and forwards to next_handler. #+ # ------------------------------------------------------------------ #+ class CompressContextMiddleware(MiddlewareBase):+ """Middleware for testing on_compress_context hook."""++ def __init__(self, log: list, name: str) -> None:+ """Initialize the compress context middleware.++ Args:+ log (`list`):+ The execution log list.+ name (`str`):+ The middleware name.+ """+ self.log = log+ self.name = name++ async def on_compress_context(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., Any],+ ) -> None:+ """Forward to next handler, recording pre and post."""+ self.log.append(f"{self.name}_pre")+ await next_handler(**input_kwargs)+ self.log.append(f"{self.name}_post")++ middleware1 = CompressContextMiddleware(self.execution_log, "mw1")+ middleware2 = CompressContextMiddleware(self.execution_log, "mw2")++ self.mock_model.set_responses(+ [+ ChatResponse(+ content=[TextBlock(text="test response")],+ is_last=True,+ ),+ ],+ )++ context_config = ContextConfig(trigger_ratio=0.8, reserve_ratio=0.1)+ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ toolkit=self.toolkit,+ middlewares=[middleware1, middleware2],+ context_config=context_config,+ )++ # Patch _compress_context_impl to avoid real token counting.+ with patch.object(+ agent,+ "_compress_context_impl",+ new_callable=AsyncMock,+ ) as mock_impl:+ await agent.compress_context(context_config=context_config)++ # _compress_context_impl must have been called exactly once.+ mock_impl.assert_awaited_once_with(context_config=context_config)++ # Verify onion 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_compress_context_middleware_short_circuit(+ self,+ ) -> None:+ """Test that a middleware can skip _compress_context_impl entirely."""++ class SkipCompressMiddleware(MiddlewareBase):+ """Middleware that skips the actual compress_context call."""++ def __init__(self, log: list) -> None:+ """Initialize the skip compress middleware.++ Args:+ log (`list`):+ The execution log list.+ """+ self.log = log++ async def on_compress_context(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., Any],+ ) -> None:+ """Record the call and skip forwarding to next_handler."""+ self.log.append("skipped")+ # Intentionally NOT calling next_handler.++ middleware = SkipCompressMiddleware(self.execution_log)++ 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],+ )++ with patch.object(+ agent,+ "_compress_context_impl",+ new_callable=AsyncMock,+ ) as mock_impl:+ await agent.compress_context()++ # _compress_context_impl should NOT have been called.+ mock_impl.assert_not_awaited()++ self.assertListEqual(self.execution_log, ["skipped"])++ async def test_on_compress_context_no_middleware(self) -> None:+ """Test that compress_context calls _compress_context_impl directly+ when no middleware is registered."""++ self.mock_model.set_responses(+ [+ ChatResponse(+ content=[TextBlock(text="test response")],+ is_last=True,+ ),+ ],+ )++ context_config = ContextConfig(trigger_ratio=0.8, reserve_ratio=0.1)+ agent = Agent(+ name="test_agent",+ system_prompt="test prompt",+ model=self.mock_model,+ toolkit=self.toolkit,+ # No middlewares registered.+ context_config=context_config,+ )++ with patch.object(+ agent,+ "_compress_context_impl",+ new_callable=AsyncMock,+ ) as mock_impl:+ await agent.compress_context(context_config=context_config)+ mock_impl.assert_awaited_once_with(context_config=context_config)+async def asyncTearDown(self) -> None:"""Clean up test fixtures."""self.execution_log.clear()