Skip to content

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

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.py
index 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 the
threshold.
+ 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 context
diff --git a/src/agentscope/middleware/_base.py b/src/agentscope/middleware/_base.py
index 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 ToolBase
if 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-argument
f"{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-argument
raise 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.py
index 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, patch
from typing import Any, AsyncGenerator, Callable, Union
from utils import MockModel
from pydantic import BaseModel
from agentscope.event import AgentEvent
-from agentscope.agent import Agent
+from agentscope.agent import Agent, ContextConfig
from agentscope.middleware import MiddlewareBase
from agentscope.model import ChatResponse
from 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()