Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(agent): support user-defined hints/instructions when compressing memory (#1942)
h2h2h05d7934bb40e
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.pyindex 586524fec..034834a53 100644--- a/src/agentscope/agent/_agent.py+++ b/src/agentscope/agent/_agent.py@@ -70,6 +70,7 @@ from ..message import (ToolCallState,ToolResultState,Usage,+ HintBlock,)from ..tool import (Toolkit,@@ -258,6 +259,7 @@ class Agent:async def compress_context(self,context_config: ContextConfig | None = None,+ instructions: HintBlock | None = None,) -> None:"""Compress the agent's context if the token count exceeds thethreshold.@@ -267,23 +269,34 @@ class Agent:If provided, compress the context with the given contextconfig. Otherwise, use the default context config in theagent.+ instructions (`HintBlock | None`, optional):+ Optional hints or instructions injected into the compression+ context to guide the summarization behavior."""if not self._compress_context_middlewares:- await self._compress_context_impl(context_config=context_config)+ await self._compress_context_impl(+ context_config=context_config,+ instructions=instructions,+ )else:async def execute_chain(index: int = 0,context_config: ContextConfig | None = context_config,+ instructions: HintBlock | None = instructions,) -> None:"""Execute the compress_context middleware chain."""if index >= len(self._compress_context_middlewares):await self._compress_context_impl(context_config=context_config,+ instructions=instructions,)else:mw = self._compress_context_middlewares[index]- input_kwargs = {"context_config": context_config}+ input_kwargs = {+ "context_config": context_config,+ "instructions": instructions,+ }async def next_handler(**kwargs: Any) -> None:await execute_chain(index + 1, **kwargs)@@ -299,6 +312,7 @@ class Agent:async def _compress_context_impl(self,context_config: ContextConfig | None = None,+ instructions: HintBlock | None = None,) -> None:"""Compress the agent's context if the token count exceeds thethreshold.@@ -308,6 +322,9 @@ class Agent:If provided, compress the context with the given contextconfig. Otherwise, use the default context config in theagent.+ instructions (`HintBlock | None`, optional):+ Optional hints or instructions injected into the compression+ context to guide the summarization behavior."""cfg: ContextConfig = context_config or self.context_config@@ -382,9 +399,19 @@ class Agent:if self.state.summary:msgs_system.append(UserMsg("user", self.state.summary))+ instruction_msgs: list[Msg] = []+ if instructions is not None:+ instruction_msgs.append(+ AssistantMsg(+ name=self.name,+ content=[instructions],+ ),+ )+messages = (msgs_system+ msgs_to_compress+ + instruction_msgs+ [UserMsg(name="user", content=cfg.compression_prompt),]@@ -436,6 +463,7 @@ class Agent:messages = (msgs_system+ msgs_to_compress[i:]+ + instruction_msgs+ [UserMsg(name="user",diff --git a/src/agentscope/middleware/_base.py b/src/agentscope/middleware/_base.pyindex 1b815dc86..2fc4de95b 100644--- a/src/agentscope/middleware/_base.py+++ b/src/agentscope/middleware/_base.py@@ -199,6 +199,7 @@ class MiddlewareBase: # pylint: disable=unused-argumentinput_kwargs (`dict`):Dictionary containing:- context_config: ContextConfig | None+ - instructions: HintBlock | Nonenext_handler (`Callable[..., Awaitable[None]]`):Callable that executes the next middleware ororiginal methoddiff --git a/tests/compress_context_test.py b/tests/compress_context_test.pyindex 24f0e34b7..e589a2e8a 100644--- a/tests/compress_context_test.py+++ b/tests/compress_context_test.py@@ -4,6 +4,7 @@import jsonimport osimport tempfile+from typing import Anyfrom unittest.async_case import IsolatedAsyncioTestCase@@ -12,10 +13,86 @@ from utils import MockModel, AnyStringfrom agentscope.model import StructuredResponsefrom agentscope.agent import Agent, ContextConfigfrom agentscope.state import AgentState-from agentscope.message import UserMsg, AssistantMsg, TextBlock, ToolCallBlock+from agentscope.message import (+ UserMsg,+ AssistantMsg,+ TextBlock,+ ToolCallBlock,+ HintBlock,+ Msg,+)from agentscope.tool import Toolkit+class RecordingStructuredMockModel(MockModel):+ """A mock model that records structured-output compression calls."""++ def __init__(+ self,+ *args: Any,+ fail_structured_output_times: int = 0,+ force_compression_overflow: bool = False,+ **kwargs: Any,+ ) -> None:+ """Initialize the recording mock model."""+ super().__init__(*args, **kwargs)+ self.recorded_structured_messages: list[list[Msg]] = []+ self._fail_structured_output_times = fail_structured_output_times+ self._force_compression_overflow = force_compression_overflow+ self._compression_count_calls = 0++ async def count_tokens(+ self,+ messages: list[Msg],+ tools: list[dict] | None,+ ) -> int:+ """Force the overflow branch when counting compression messages."""+ is_compression_count = bool(+ tools+ and tools[0].get("function", {}).get("name")+ == "generate_structured_output",+ )+ if self._force_compression_overflow and is_compression_count:+ self._compression_count_calls += 1+ if self._compression_count_calls == 1:+ return self.context_size + 1+ return 1+ return await super().count_tokens(messages, tools)++ async def _call_api_with_structured_output(+ self,+ model_name: str,+ messages: list[Msg],+ structured_model: Any,+ **kwargs: Any,+ ) -> StructuredResponse:+ """Record the structured-output call and optionally fail first."""+ self.recorded_structured_messages.append(list(messages))+ if self._fail_structured_output_times > 0:+ self._fail_structured_output_times -= 1+ raise RuntimeError("simulated compression overflow")+ return await super()._call_api_with_structured_output(+ model_name,+ messages,+ structured_model,+ **kwargs,+ )+++def _has_instruction_hint(+ messages: list[Msg],+ instructions: HintBlock,+) -> bool:+ """Return True if messages contain instructions as an assistant hint."""+ for msg in messages:+ if msg.role != "assistant":+ continue+ for hint_block in msg.get_content_blocks("hint"):+ if hint_block.id == instructions.id:+ return hint_block.hint == instructions.hint+ return False++class ContextCompressionTest(IsolatedAsyncioTestCase):"""The template test case."""@@ -871,5 +948,136 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):await agent.state.tool_context.get_cache(file_path),)+ async def test_context_compression_injects_instructions_as_hint(+ self,+ ) -> None:+ """Instructions are injected as a HintBlock only for compression."""+ model = RecordingStructuredMockModel(context_size=100)+ agent = Agent(+ name="Friday",+ system_prompt="".join(["0" for _ in range(20 * 4)]),+ model=model,+ context_config=ContextConfig(+ trigger_ratio=0.7,+ reserve_ratio=0.4,+ ),+ state=AgentState(+ session_id="123",+ context=[+ UserMsg(+ "User",+ "".join(["1" for _ in range(30 * 4)]),+ id="1",+ ),+ AssistantMsg(+ "Friday",+ "".join(["2" for _ in range(10 * 4)]),+ id="2",+ ),+ UserMsg(+ "User",+ "".join(["3" for _ in range(10 * 4)]),+ id="3",+ ),+ ],+ ),+ toolkit=Toolkit(),+ )++ model.set_structured_response(+ StructuredResponse(+ content={+ "task_overview": "1",+ "current_state": "2",+ "important_discoveries": "3",+ "next_steps": "4",+ "context_to_preserve": "5",+ },+ ),+ )+ instructions = HintBlock(+ hint="Keep user requirements and file paths.",+ source="user",+ )++ await agent.compress_context(instructions=instructions)++ self.assertEqual(len(model.recorded_structured_messages), 1)+ self.assertTrue(+ _has_instruction_hint(+ model.recorded_structured_messages[0],+ instructions,+ ),+ )+ self.assertFalse(+ any(msg.get_content_blocks("hint") for msg in agent.state.context),+ )++ async def test_context_compression_overflow_retry_keeps_instructions(+ self,+ ) -> None:+ """Overflow retry preserves instructions when rebuilding messages."""+ model = RecordingStructuredMockModel(+ context_size=100,+ fail_structured_output_times=1,+ force_compression_overflow=True,+ )+ agent = Agent(+ name="Friday",+ system_prompt="".join(["0" for _ in range(20 * 4)]),+ model=model,+ context_config=ContextConfig(+ trigger_ratio=0.7,+ reserve_ratio=0.4,+ ),+ state=AgentState(+ session_id="123",+ context=[+ UserMsg(+ "User",+ "".join(["1" for _ in range(30 * 4)]),+ id="1",+ ),+ AssistantMsg(+ "Friday",+ "".join(["2" for _ in range(10 * 4)]),+ id="2",+ ),+ UserMsg(+ "User",+ "".join(["3" for _ in range(10 * 4)]),+ id="3",+ ),+ ],+ ),+ toolkit=Toolkit(),+ )++ model.set_structured_response(+ StructuredResponse(+ content={+ "task_overview": "1",+ "current_state": "2",+ "important_discoveries": "3",+ "next_steps": "4",+ "context_to_preserve": "5",+ },+ ),+ )+ instructions = HintBlock(+ hint="Keep the user's original success criteria.",+ source="user",+ )++ await agent.compress_context(instructions=instructions)++ self.assertEqual(len(model.recorded_structured_messages), 2)+ self.assertTrue(+ _has_instruction_hint(+ model.recorded_structured_messages[-1],+ instructions,+ ),+ )+async def asyncTearDown(self) -> None:"""The async teardown method."""diff --git a/tests/middleware_test.py b/tests/middleware_test.pyindex a29a00e77..eda6cc22e 100644--- a/tests/middleware_test.py+++ b/tests/middleware_test.py@@ -13,6 +13,7 @@ from agentscope.middleware import MiddlewareBasefrom agentscope.model import ChatResponsefrom agentscope.message import (TextBlock,+ HintBlock,UserMsg,SystemMsg,Msg,@@ -821,10 +822,12 @@ class TestMiddleware(IsolatedAsyncioTestCase):Verifies that:- Multiple middlewares are chained in onion order (mw1 wraps mw2).- - ``input_kwargs`` carries the correct ``context_config``.+ - ``input_kwargs`` carries the correct ``context_config`` and+ ``instructions``.- The ``next_handler`` ultimately calls ``_compress_context_impl``.- A middleware can short-circuit and skip the actual implementation."""+ seen_instructions = []# ------------------------------------------------------------------ ## Middleware that records pre/post and forwards to next_handler. #@@ -852,6 +855,7 @@ class TestMiddleware(IsolatedAsyncioTestCase):) -> None:"""Forward to next handler, recording pre and post."""self.log.append(f"{self.name}_pre")+ seen_instructions.append(input_kwargs.get("instructions"))await next_handler(**input_kwargs)self.log.append(f"{self.name}_post")@@ -878,20 +882,86 @@ class TestMiddleware(IsolatedAsyncioTestCase):)# Patch _compress_context_impl to avoid real token counting.+ instructions = HintBlock(+ hint="Keep user requirements while compressing.",+ source="user",+ )with patch.object(agent,"_compress_context_impl",new_callable=AsyncMock,) as mock_impl:- await agent.compress_context(context_config=context_config)+ await agent.compress_context(+ context_config=context_config,+ instructions=instructions,+ )# _compress_context_impl must have been called exactly once.- mock_impl.assert_awaited_once_with(context_config=context_config)+ mock_impl.assert_awaited_once_with(+ context_config=context_config,+ instructions=instructions,+ )# Verify onion execution order: mw1_pre -> mw2_pre -> mw2_post -># mw1_postexpected = ["mw1_pre", "mw2_pre", "mw2_post", "mw1_post"]self.assertListEqual(self.execution_log, expected)+ self.assertListEqual(seen_instructions, [instructions, instructions])++ async def test_on_compress_context_middleware_modify_instructions(+ self,+ ) -> None:+ """Test that middleware can replace compress_context instructions."""++ class ReplaceInstructionsMiddleware(MiddlewareBase):+ """Middleware that replaces the compression instructions."""++ def __init__(self, replacement: HintBlock) -> None:+ """Initialize the middleware with replacement instructions."""+ self.replacement = replacement++ async def on_compress_context(+ self,+ agent: Agent,+ input_kwargs: dict,+ next_handler: Callable[..., Any],+ ) -> None:+ """Replace instructions before forwarding."""+ input_kwargs["instructions"] = self.replacement+ await next_handler(**input_kwargs)++ original = HintBlock(+ hint="Keep all requirements.",+ source="user",+ )+ replacement = HintBlock(+ hint="Keep only unresolved requirements.",+ source="middleware",+ )+ 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=[ReplaceInstructionsMiddleware(replacement)],+ 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,+ instructions=original,+ )++ mock_impl.assert_awaited_once_with(+ context_config=context_config,+ instructions=replacement,+ )async def test_on_compress_context_middleware_short_circuit(self,@@ -980,7 +1050,10 @@ class TestMiddleware(IsolatedAsyncioTestCase):new_callable=AsyncMock,) as mock_impl:await agent.compress_context(context_config=context_config)- mock_impl.assert_awaited_once_with(context_config=context_config)+ mock_impl.assert_awaited_once_with(+ context_config=context_config,+ instructions=None,+ )async def asyncTearDown(self) -> None:"""Clean up test fixtures."""