Skip to content

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

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.py
index 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 the
threshold.
@@ -267,23 +269,34 @@ class Agent:
If provided, compress the context with the given context
config. Otherwise, use the default context config in the
agent.
+ 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 the
threshold.
@@ -308,6 +322,9 @@ class Agent:
If provided, compress the context with the given context
config. Otherwise, use the default context config in the
agent.
+ 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.py
index 1b815dc86..2fc4de95b 100644
--- a/src/agentscope/middleware/_base.py
+++ b/src/agentscope/middleware/_base.py
@@ -199,6 +199,7 @@ class MiddlewareBase: # pylint: disable=unused-argument
input_kwargs (`dict`):
Dictionary containing:
- context_config: ContextConfig | None
+ - instructions: HintBlock | None
next_handler (`Callable[..., Awaitable[None]]`):
Callable that executes the next middleware or
original method
diff --git a/tests/compress_context_test.py b/tests/compress_context_test.py
index 24f0e34b7..e589a2e8a 100644
--- a/tests/compress_context_test.py
+++ b/tests/compress_context_test.py
@@ -4,6 +4,7 @@
import json
import os
import tempfile
+from typing import Any
from unittest.async_case import IsolatedAsyncioTestCase
@@ -12,10 +13,86 @@ from utils import MockModel, AnyString
from agentscope.model import StructuredResponse
from agentscope.agent import Agent, ContextConfig
from 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.py
index a29a00e77..eda6cc22e 100644
--- a/tests/middleware_test.py
+++ b/tests/middleware_test.py
@@ -13,6 +13,7 @@ from agentscope.middleware import MiddlewareBase
from agentscope.model import ChatResponse
from 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_post
expected = ["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."""