Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(context): support to compact the tool result within the `Agent` class (#1585)
DavdGao54dbead83656
diff --git a/src/agentscope/agent/__init__.py b/src/agentscope/agent/__init__.pyindex b7e02c1ec..f87dd3a99 100644--- a/src/agentscope/agent/__init__.py+++ b/src/agentscope/agent/__init__.py@@ -1,6 +1,6 @@# -*- coding: utf-8 -*-"""Initialize the agent module."""from ._agent import Agent-from ._config import CompressionConfig+from ._config import ContextConfig-__all__ = ["Agent", "CompressionConfig"]+__all__ = ["Agent", "ContextConfig"]diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.pyindex b44a8f284..b582f4d86 100644--- a/src/agentscope/agent/_agent.py+++ b/src/agentscope/agent/_agent.py@@ -15,7 +15,7 @@ from typing import (import jsonschema-from ._config import CompressionConfig, ReActConfig, ModelConfig+from ._config import ContextConfig, ReActConfig, ModelConfigfrom ..state import AgentStatefrom ._utils import _ToolCallBatchfrom .._logging import logger@@ -95,7 +95,7 @@ class Agent:middlewares: list[MiddlewareBase] | None = None,state: AgentState | None = None,model_config: ModelConfig = ModelConfig(),- compression_config: CompressionConfig = CompressionConfig(),+ context_config: ContextConfig = ContextConfig(),react_config: ReActConfig = ReActConfig(),) -> None:self.name = name@@ -105,7 +105,7 @@ class Agent:self.state = state or AgentState()self.model_config = model_config- self.compression_config = compression_config+ self.context_config = context_configself.react_config = react_configself._engine = PermissionEngine(self.state.permission_context)@@ -202,18 +202,18 @@ class Agent:async def compress_context(self,- compression_config: CompressionConfig | None = None,+ context_config: ContextConfig | None = None,) -> None:"""Compress the agent's context if the token count exceeds thethreshold.Args:- compression_config (`CompressionConfig | None`, optional):- If provided, compress the context with the given compression- config. Otherwise, use the default compression config in the+ context_config (`ContextConfig | None`, optional):+ If provided, compress the context with the given context+ config. Otherwise, use the default context config in theagent."""- cfg: CompressionConfig = compression_config or self.compression_config+ cfg: ContextConfig = context_config or self.context_config# Count the current tokenskwargs = await self._prepare_model_input()@@ -1144,7 +1144,7 @@ class Agent:| ToolResultEndEvent,None,]:- """Execute tool call entry point (may be wrapped by middleware)."""+ """Execute tool call entry point (maybe wrapped by middleware)."""if not self._acting_middlewares:async for item in self._execute_tool_call_impl(tool_call):yield item@@ -1326,17 +1326,56 @@ class Agent:res = self.toolkit.call_tool(tool_call, self.state)async for chunk in res:+ # The ToolResponse is the last and completed tool result hereif isinstance(chunk, ToolResponse):- self._save_to_context(- [- ToolResultBlock(- id=tool_call.id,- name=tool_call.name,- output=chunk.content,- state=chunk.state,- ),- ],+ tool_result_block = ToolResultBlock(+ id=tool_call.id,+ name=tool_call.name,+ output=[TextBlock(text=chunk.content)]+ if isinstance(chunk.content, str)+ else chunk.content,+ state=chunk.state,+ )++ # ========================================================+ # Step 4: Truncate the tool result if exceed+ # ========================================================+ (+ reserved_tool_result_block,+ offload_tool_result_block,+ ) = await self._split_tool_result_for_compression(+ tool_result_block,)++ # If offload result is not empty, attach reminder to the+ # reserved context+ if offload_tool_result_block is not None:+ reminder = (+ "\n<<<TRUNCATED>>>\n<system-reminder>The "+ "remaining content has been omitted for "+ "limited context.</system-reminder>"+ )+ if isinstance(reserved_tool_result_block.output, str):+ reserved_tool_result_block.output += reminder++ elif len(+ reserved_tool_result_block.output,+ ) > 0 and isinstance(+ reserved_tool_result_block.output[-1],+ TextBlock,+ ):+ reserved_tool_result_block.output[+ -1+ ].text += reminder++ else:+ reserved_tool_result_block.output += [+ TextBlock(text=reminder),+ ]++ # TODO: offload the tool result++ self._save_to_context([reserved_tool_result_block])# Ends the tool call lifecycle.self._update_tool_call_state(tool_call.id,@@ -1540,6 +1579,154 @@ class Agent:return msgs_to_compress, msgs_to_reserve+ async def _split_tool_result_for_compression(+ self,+ tool_result: ToolResultBlock,+ ) -> tuple[ToolResultBlock, ToolResultBlock | None]:+ """Split the tool result for compression.++ Args:+ tool_result (`ToolResultBlock`):+ The tool result block.++ Returns:+ `tuple[ToolResultBlock, ToolResultBlock | None]`:+ A tuple of the tool result blocks to reserved in context and+ to offload (if any).+ """+ n_tokens = await self.model.count_tokens(+ [AssistantMsg(self.name, content=tool_result.output)],+ None,+ )++ # Return the tool result without truncation+ if n_tokens <= self.context_config.tool_result_limit:+ return tool_result, None++ # Use a copied block for token counting+ copied_tool_result = deepcopy(tool_result)++ # Normalized into content blocks+ if isinstance(copied_tool_result.output, str):+ copied_tool_result.output = [+ TextBlock(text=copied_tool_result.output),+ ]++ # Find the index of the block that will exceed the limit+ boundary_index = 0+ for i in range(len(copied_tool_result.output) - 1, 0, -1):+ copied_tool_result.output = tool_result.output[:i]+ cur_tokens = await self.model.count_tokens(+ [+ AssistantMsg(+ self.name,+ content=copied_tool_result.output,+ ),+ ],+ None,+ )+ if cur_tokens < self.context_config.tool_result_limit:+ boundary_index = i+ break++ # The blocks to reserve and offload (deep copy to avoid+ # modifying original)+ reserved_blocks: list = [+ deepcopy(b) for b in tool_result.output[:boundary_index]+ ]+ offload_blocks: list = [+ deepcopy(b) for b in tool_result.output[boundary_index + 1 :]+ ]++ # Get the boundary block, if text block, we can truncate it+ boundary_block = tool_result.output[boundary_index]+ if isinstance(boundary_block, TextBlock):+ # Truncate it+ truncated_text = boundary_block.text+ cur_tokens = await self.model.count_tokens(+ [AssistantMsg(self.name, content=reserved_blocks)],+ None,+ )+ cur_tokens_plus = await self.model.count_tokens(+ [+ AssistantMsg(+ self.name,+ content=reserved_blocks + [boundary_block],+ ),+ ],+ None,+ )+ # Truncate the text by proportion of tokens+ token_delta = cur_tokens_plus - cur_tokens+ remaining_token_budget = (+ self.context_config.tool_result_limit - cur_tokens+ )+ if token_delta <= 0:+ reserved_tokens = (+ len(truncated_text) if remaining_token_budget > 0 else 0+ )+ else:+ reserved_tokens = int(+ remaining_token_budget / token_delta * len(truncated_text),+ )+ reserved_tokens = max(+ 0,+ min(len(truncated_text), reserved_tokens),+ )++ reserved_text = truncated_text[:reserved_tokens]+ offload_text = truncated_text[reserved_tokens:]++ if reserved_text:+ if (+ len(reserved_blocks) > 0+ and reserved_blocks[-1].type == "text"+ ):+ reserved_blocks[-1].text += reserved_text++ else:+ reserved_blocks.append(+ TextBlock(text=reserved_text, id=boundary_block.id),+ )++ if offload_text:+ if (+ len(offload_blocks) > 0+ and offload_blocks[0].type == "text"+ ):+ offload_blocks[0].text = (+ offload_text + offload_blocks[0].text+ )++ else:+ offload_blocks.insert(+ 0,+ TextBlock(text=offload_text, id=boundary_block.id),+ )++ else:+ # Drop the boundary block if inseparable+ offload_blocks.insert(0, boundary_block)++ if len(offload_blocks) == 0:+ return tool_result, None++ # Create new ToolResultBlock instances for reserved and offload+ reserved_tool_result = ToolResultBlock(+ id=tool_result.id,+ name=tool_result.name,+ output=reserved_blocks,+ state=tool_result.state,+ )+ offload_tool_result = ToolResultBlock(+ id=tool_result.id,+ name=tool_result.name,+ output=offload_blocks,+ state=tool_result.state,+ )++ return reserved_tool_result, offload_tool_result+# ======================================================================# Agent internal utility methods# ======================================================================diff --git a/src/agentscope/agent/_config.py b/src/agentscope/agent/_config.pyindex d8701eaa8..8b5b8b84a 100644--- a/src/agentscope/agent/_config.py+++ b/src/agentscope/agent/_config.py@@ -51,8 +51,8 @@ class SummarySchema(BaseModel):)-class CompressionConfig(BaseModel):- """The compression related configuration in AgentScope"""+class ContextConfig(BaseModel):+ """The context related configuration in AgentScope"""model_config = {"arbitrary_types_allowed": True}"""Allow arbitrary types in the pydantic model."""@@ -103,6 +103,16 @@ class CompressionConfig(BaseModel):"""The structured model used to guide the agent to generate thestructured compressed summary."""+ tool_result_limit: int = Field(+ title="Tool Result Limit",+ default=3000,+ description=(+ "The maximum length of the tool results in tokens. "+ "If exceeded, the tool result will be truncated."+ ),+ )+ """The tool result limit to avoid tool result bursting."""+class ReActConfig(BaseModel):"""The reasoning related configuration"""diff --git a/tests/context_compression_test.py b/tests/compress_context_test.pysimilarity index 99%rename from tests/context_compression_test.pyrename to tests/compress_context_test.pyindex 82ac3538e..2edb990c3 100644--- a/tests/context_compression_test.py+++ b/tests/compress_context_test.py@@ -6,7 +6,7 @@ from unittest.async_case import IsolatedAsyncioTestCasefrom utils import MockModel, AnyStringfrom agentscope.model import StructuredResponse-from agentscope.agent import Agent, CompressionConfig+from agentscope.agent import Agent, ContextConfigfrom agentscope.state import AgentStatefrom agentscope.message import UserMsg, AssistantMsg, TextBlockfrom agentscope.tool import Toolkit@@ -24,7 +24,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):name="Friday",system_prompt="".join(["0" for _ in range(60 * 4)]),model=MockModel(),- compression_config=CompressionConfig(+ context_config=ContextConfig(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_config=CompressionConfig(+ context_config=ContextConfig(trigger_ratio=0.7,reserve_ratio=0.4,),diff --git a/tests/compress_tool_result_test.py b/tests/compress_tool_result_test.pynew file mode 100644index 000000000..33cc166aa--- /dev/null+++ b/tests/compress_tool_result_test.py@@ -0,0 +1,480 @@+# -*- coding: utf-8 -*-+"""The unittests for the tool result compression."""+# pylint: disable=protected-access, unused-argument+from unittest.async_case import IsolatedAsyncioTestCase++from utils import MockModel++from agentscope.agent import Agent, ContextConfig+from agentscope.message import (+ ToolResultBlock,+ TextBlock,+ DataBlock,+ Base64Source,+)+from agentscope.state import AgentState+from agentscope.tool import Toolkit+++class ToolResultCompressionTest(IsolatedAsyncioTestCase):+ """Test cases for tool result compression."""++ async def asyncSetUp(self) -> None:+ """The async setup method."""+ self.mock_model = MockModel()+ self.agent = Agent(+ name="TestAgent",+ system_prompt="Test system prompt",+ model=self.mock_model,+ toolkit=Toolkit(),+ context_config=ContextConfig(+ tool_result_limit=100,+ ),+ state=AgentState(session_id="test_session"),+ )++ async def test_below_limit(self) -> None:+ """Test when tool result is below the token limit."""+ tool_result = ToolResultBlock(+ id="test_1",+ name="test_tool",+ output=[+ TextBlock(text="Short text 1"),+ TextBlock(text="Short text 2"),+ ],+ )++ async def mock_count_tokens(+ messages: list,+ tools: list | None = None,+ ) -> int:+ """Mock token counting function that returns a fixed count."""+ return 50++ self.mock_model.count_tokens = mock_count_tokens+ (+ reserved,+ offload,+ ) = await self.agent._split_tool_result_for_compression(+ tool_result,+ )++ self.assertEqual(reserved, tool_result)+ self.assertIsNone(offload)++ async def test_equal_to_limit(self) -> None:+ """Test when tool result is exactly at the token limit."""+ tool_result = ToolResultBlock(+ id="test_2",+ name="test_tool",+ output=[TextBlock(text="Text at limit")],+ )++ async def mock_count_tokens(+ messages: list,+ tools: list | None = None,+ ) -> int:+ """Mock token counting function that returns a fixed count."""+ return 100++ self.mock_model.count_tokens = mock_count_tokens+ (+ reserved,+ offload,+ ) = await self.agent._split_tool_result_for_compression(+ tool_result,+ )++ self.assertEqual(reserved, tool_result)+ self.assertIsNone(offload)++ async def test_boundary_last_block_text(self) -> None:+ """Test when boundary is the last block and it is a TextBlock."""+ block1 = TextBlock(text="A" * 20, id="block1")+ block2 = TextBlock(text="B" * 20, id="block2")+ block3 = TextBlock(text="C" * 100, id="block3")++ tool_result = ToolResultBlock(+ id="test_3",+ name="test_tool",+ output=[block1, block2, block3],+ )++ async def mock_count_tokens(+ messages: list,+ tools: list | None = None,+ ) -> int:+ """Mock token counting function that counts text length in+ blocks."""+ content = messages[0].content+ if isinstance(content, list):+ total = sum(len(b.text) for b in content if hasattr(b, "text"))+ return total+ return 0++ self.mock_model.count_tokens = mock_count_tokens+ (+ reserved,+ offload,+ ) = await self.agent._split_tool_result_for_compression(+ tool_result,+ )++ # Verify results+ self.assertIsNotNone(reserved)+ self.assertIsNotNone(offload)++ # Verify ToolResultBlock metadata+ self.assertEqual(reserved.id, tool_result.id)+ self.assertEqual(reserved.name, tool_result.name)+ self.assertEqual(reserved.state, tool_result.state)+ self.assertEqual(offload.id, tool_result.id)+ self.assertEqual(offload.name, tool_result.name)+ self.assertEqual(offload.state, tool_result.state)++ # Verify results using assertListEqual+ expected_reserved = [+ {"type": "text", "text": "A" * 20, "id": "block1"},+ {"type": "text", "text": "B" * 20 + "C" * 60, "id": "block2"},+ ]+ expected_offload = [+ {"type": "text", "text": "C" * 40, "id": "block3"},+ ]++ self.assertListEqual(+ [b.model_dump() for b in reserved.output],+ expected_reserved,+ )+ self.assertListEqual(+ [b.model_dump() for b in offload.output],+ expected_offload,+ )++ async def test_boundary_last_block_data(self) -> None:+ """Test when boundary is the last block and it is a DataBlock."""+ block1 = TextBlock(text="A" * 20, id="block1")+ block2 = TextBlock(text="B" * 20, id="block2")+ block3 = DataBlock(+ source=Base64Source(data="base64data", media_type="image/png"),+ id="block3",+ )++ tool_result = ToolResultBlock(+ id="test_4",+ name="test_tool",+ output=[block1, block2, block3],+ )++ async def mock_count_tokens(+ messages: list,+ tools: list | None = None,+ ) -> int:+ """Mock token counting function based on content length."""+ content = messages[0].content+ if isinstance(content, list):+ if len(content) == 3:+ return 150+ elif len(content) == 2:+ return 80+ return 50++ self.mock_model.count_tokens = mock_count_tokens+ (+ reserved,+ offload,+ ) = await self.agent._split_tool_result_for_compression(+ tool_result,+ )++ # Verify results+ self.assertIsNotNone(reserved)+ self.assertIsNotNone(offload)++ # Verify ToolResultBlock metadata+ self.assertEqual(reserved.id, tool_result.id)+ self.assertEqual(offload.id, tool_result.id)++ # Verify results using assertListEqual+ expected_reserved = [+ {"type": "text", "text": "A" * 20, "id": "block1"},+ {"type": "text", "text": "B" * 20, "id": "block2"},+ ]+ expected_offload = [+ {+ "type": "data",+ "id": "block3",+ "source": {+ "type": "base64",+ "data": "base64data",+ "media_type": "image/png",+ },+ "name": None,+ },+ ]++ self.assertListEqual(+ [b.model_dump() for b in reserved.output],+ expected_reserved,+ )+ self.assertListEqual(+ [b.model_dump() for b in offload.output],+ expected_offload,+ )++ async def test_boundary_first_block_text(self) -> None:+ """Test when boundary is the first block and it is a TextBlock."""+ block1 = TextBlock(text="A" * 100, id="block1")+ block2 = TextBlock(text="B" * 20, id="block2")+ block3 = TextBlock(text="C" * 20, id="block3")++ tool_result = ToolResultBlock(+ id="test_5",+ name="test_tool",+ output=[block1, block2, block3],+ )++ async def mock_count_tokens(+ messages: list,+ tools: list | None = None,+ ) -> int:+ """Mock token counting function that counts text length in+ blocks."""+ content = messages[0].content+ if isinstance(content, list):+ total = sum(len(b.text) for b in content if hasattr(b, "text"))+ return total+ return 0++ self.mock_model.count_tokens = mock_count_tokens+ (+ reserved,+ offload,+ ) = await self.agent._split_tool_result_for_compression(+ tool_result,+ )++ # Verify results using assertListEqual+ expected_reserved = [+ {"type": "text", "text": "A" * 100, "id": "block1"},+ ]+ expected_offload = [+ {"type": "text", "text": "B" * 20, "id": "block2"},+ {"type": "text", "text": "C" * 20, "id": "block3"},+ ]++ self.assertListEqual(+ [b.model_dump() for b in reserved.output],+ expected_reserved,+ )+ print(offload.output)+ self.assertListEqual(+ [b.model_dump() for b in offload.output],+ expected_offload,+ )++ async def test_boundary_first_block_data(self) -> None:+ """Test when boundary is the first block and it is a DataBlock."""+ block1 = DataBlock(+ source=Base64Source(data="base64data", media_type="image/png"),+ id="block1",+ )+ block2 = TextBlock(text="B" * 20, id="block2")+ block3 = TextBlock(text="C" * 20, id="block3")++ tool_result = ToolResultBlock(+ id="test_6",+ name="test_tool",+ output=[block1, block2, block3],+ )++ async def mock_count_tokens(+ messages: list,+ tools: list | None = None,+ ) -> int:+ """Mock token counting function based on content length."""+ content = messages[0].content+ if isinstance(content, list):+ if len(content) == 3:+ return 150+ elif len(content) == 2:+ return 80+ elif len(content) == 1:+ return 60+ return 50++ self.mock_model.count_tokens = mock_count_tokens+ (+ reserved,+ offload,+ ) = await self.agent._split_tool_result_for_compression(+ tool_result,+ )++ # Verify results+ self.assertIsNotNone(reserved)+ self.assertIsNotNone(offload)++ # Verify ToolResultBlock metadata+ self.assertEqual(reserved.id, tool_result.id)+ self.assertEqual(offload.id, tool_result.id)++ # Verify results using assertListEqual+ expected_reserved = [+ {+ "type": "data",+ "id": "block1",+ "source": {+ "type": "base64",+ "data": "base64data",+ "media_type": "image/png",+ },+ "name": None,+ },+ {"type": "text", "text": "B" * 20 + "C" * 5, "id": "block2"},+ ]+ expected_offload = [+ {"type": "text", "text": "C" * 15, "id": "block3"},+ ]++ self.assertListEqual(+ [b.model_dump() for b in reserved.output],+ expected_reserved,+ )+ self.assertListEqual(+ [b.model_dump() for b in offload.output],+ expected_offload,+ )++ async def test_boundary_middle_block_text(self) -> None:+ """Test when boundary is a middle block and it is a TextBlock."""+ block1 = TextBlock(text="A" * 20, id="block1")+ block2 = TextBlock(text="B" * 100, id="block2")+ block3 = TextBlock(text="C" * 20, id="block3")++ tool_result = ToolResultBlock(+ id="test_7",+ name="test_tool",+ output=[block1, block2, block3],+ )++ async def mock_count_tokens(+ messages: list,+ tools: list | None = None,+ ) -> int:+ """Mock token counting function that counts text length in+ blocks."""+ content = messages[0].content+ if isinstance(content, list):+ total = sum(len(b.text) for b in content if hasattr(b, "text"))+ return total+ return 0++ self.mock_model.count_tokens = mock_count_tokens+ (+ reserved,+ offload,+ ) = await self.agent._split_tool_result_for_compression(+ tool_result,+ )++ # Verify results+ self.assertIsNotNone(reserved)+ self.assertIsNotNone(offload)++ # Verify ToolResultBlock metadata+ self.assertEqual(reserved.id, tool_result.id)+ self.assertEqual(offload.id, tool_result.id)++ # Verify results using assertListEqual+ expected_reserved = [+ {"type": "text", "text": "A" * 20 + "B" * 80, "id": "block1"},+ ]+ expected_offload = [+ {"type": "text", "text": "B" * 20 + "C" * 20, "id": "block3"},+ ]++ self.assertListEqual(+ [b.model_dump() for b in reserved.output],+ expected_reserved,+ )+ self.assertListEqual(+ [b.model_dump() for b in offload.output],+ expected_offload,+ )++ async def test_boundary_middle_block_data(self) -> None:+ """Test when boundary is a middle block and it is a DataBlock."""+ block1 = TextBlock(text="A" * 20, id="block1")+ block2 = DataBlock(+ source=Base64Source(data="base64data", media_type="image/png"),+ id="block2",+ )+ block3 = TextBlock(text="C" * 20, id="block3")++ tool_result = ToolResultBlock(+ id="test_8",+ name="test_tool",+ output=[block1, block2, block3],+ )++ async def mock_count_tokens(+ messages: list,+ tools: list | None = None,+ ) -> int:+ """Mock token counting function based on content length."""+ content = messages[0].content+ if isinstance(content, list):+ if len(content) == 3:+ return 150+ elif len(content) == 2:+ return 80+ elif len(content) == 1:+ return 40+ return 50++ self.mock_model.count_tokens = mock_count_tokens+ (+ reserved,+ offload,+ ) = await self.agent._split_tool_result_for_compression(+ tool_result,+ )++ # Verify results+ self.assertIsNotNone(reserved)+ self.assertIsNotNone(offload)++ # Verify ToolResultBlock metadata+ self.assertEqual(reserved.id, tool_result.id)+ self.assertEqual(offload.id, tool_result.id)++ # Verify results using assertListEqual+ expected_reserved = [+ {"type": "text", "text": "A" * 20, "id": "block1"},+ {+ "type": "data",+ "id": "block2",+ "source": {+ "type": "base64",+ "data": "base64data",+ "media_type": "image/png",+ },+ "name": None,+ },+ {"type": "text", "text": "C" * 5, "id": "block3"},+ ]+ expected_offload = [+ {"type": "text", "text": "C" * 15, "id": "block3"},+ ]++ self.assertListEqual(+ [b.model_dump() for b in reserved.output],+ expected_reserved,+ )+ self.assertListEqual(+ [b.model_dump() for b in offload.output],+ expected_offload,+ )++ async def asyncTearDown(self) -> None:+ """The async teardown method."""