Skip to content

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

feat(agent): add agent-driven context compression tool (#2143)

jinliylbccb9fa5ed5c
diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.py
index 319b67717..d51767f37 100644
--- a/src/agentscope/agent/_agent.py
+++ b/src/agentscope/agent/_agent.py
@@ -94,6 +94,7 @@ from ..tool import (
ToolChunk,
ToolChoice,
ToolResponse,
+ FunctionTool,
)
from ..permission import (
PermissionBehavior,
@@ -104,6 +105,9 @@ from ..permission import (
from ._structured_output_tool import _GenerateStructuredOutput
from ..workspace import Offloader, WorkspaceBase
+# The name of the tool that the agent uses to compress its own context
+_COMPRESSION_TOOL_NAME = "CompressContext"
+
if TYPE_CHECKING:
from ..middleware import MiddlewareBase
else:
@@ -173,6 +177,16 @@ class Agent:
self.context_config = context_config or ContextConfig()
self.react_config = react_config or ReActConfig()
self.injection_config = injection_config or InjectionConfig()
+ if self.injection_config.context_buffer_ratio is not None:
+ warnings.warn(
+ "The 'context_buffer_ratio' of the injection config is "
+ "deprecated, set it in the context config instead.",
+ DeprecationWarning,
+ stacklevel=2,
+ )
+ self.context_config.context_buffer_ratio = (
+ self.injection_config.context_buffer_ratio
+ )
self._validate_configs()
# The permission engine
@@ -185,6 +199,18 @@ class Agent:
# The Tool-related logics
# ====================================================================
self.toolkit = toolkit or Toolkit()
+ # Built here rather than in ``_prepare_model_input``, so that the
+ # registration can tell this agent's tool from a tool of the same
+ # name, e.g. another agent sharing the toolkit
+ self._compression_tool = FunctionTool(
+ self._compress_context_tool,
+ name=_COMPRESSION_TOOL_NAME,
+ is_concurrency_safe=False,
+ permission=PermissionDecision(
+ behavior=PermissionBehavior.ALLOW,
+ message=f"{_COMPRESSION_TOOL_NAME} is always allowed.",
+ ),
+ )
# ====================================================================
# The Middleware-related attributes
@@ -237,16 +263,21 @@ class Agent:
f"{self.context_config.trigger_ratio}.",
)
+ # The buffer is only consumed by the runtime state injection and
+ # the compression tool, so it's checked only when one of them is on
if (
self.injection_config.inject_runtime_state
- and self.injection_config.context_buffer_ratio
+ or self.context_config.compression_tool_enabled
+ ) and (
+ self.context_config.context_buffer_ratio
>= self.context_config.trigger_ratio
):
raise ValueError(
- "The 'context_buffer_ratio' of the injection config must be "
- "smaller than the 'trigger_ratio' of the context config, so "
- "that the context length is injected before the compression, "
- f"got {self.injection_config.context_buffer_ratio} and "
+ "The 'context_buffer_ratio' of the context config must be "
+ "smaller than its 'trigger_ratio', so that the context "
+ "length is injected and the compression tool takes effect "
+ "before the hard compression, got "
+ f"{self.context_config.context_buffer_ratio} and "
f"{self.context_config.trigger_ratio}.",
)
@@ -408,6 +439,54 @@ class Agent:
await execute_chain()
+ async def _compress_context_tool(self) -> ToolChunk:
+ """Compress the older context into a continuation summary, while
+ preserving the recent context needed for the upcoming work.
+
+ Call it between tasks, where the completed work can be preserved
+ accurately in a summary, rather than in the middle of a task. Keep
+ the current context when the exact earlier details are still needed.
+ The context is replaced only after the summary is generated
+ successfully, and is left as-is when it's not long enough to be
+ worth compressing.
+
+ Returns:
+ `ToolChunk`:
+ Whether the context was compressed.
+ """
+ # The agent decides when to compress, so lower the trigger to the
+ # ratio where the compression is recommended. A context below that
+ # ratio is left untouched.
+ context_config = self.context_config.model_copy(
+ update={
+ "trigger_ratio": self.context_config.trigger_ratio
+ - self.context_config.context_buffer_ratio,
+ },
+ )
+
+ n_msgs = len(self.state.context)
+ try:
+ await self.compress_context(context_config=context_config)
+
+ except Exception as e: # pylint: disable=broad-exception-caught
+ return ToolChunk(
+ content=[TextBlock(text=f"Context compression failed: {e}")],
+ state=ToolResultState.ERROR,
+ )
+
+ if len(self.state.context) == n_msgs:
+ text = (
+ "The context is not long enough to compress, so it remains "
+ "unchanged."
+ )
+ else:
+ text = "Context compressed successfully."
+
+ return ToolChunk(
+ content=[TextBlock(text=text)],
+ state=ToolResultState.SUCCESS,
+ )
+
async def _compress_context_impl(
self,
context_config: ContextConfig | None = None,
@@ -598,6 +677,8 @@ class Agent:
error = retry_error
if res is None:
+ if not cfg.compression_fallback_to_truncation:
+ raise error
logger.warning(
"[AGENT %s]: Summary generation failed: %s. "
"Falling back to context truncation.",
@@ -1286,9 +1367,11 @@ class Agent:
they have been compressed away) nor a previous tasks injection.
- **Context**: injected at the first iteration of a reply when the
current input tokens are within
- ``injection_config.context_buffer_ratio`` of the compression
+ ``context_config.context_buffer_ratio`` of the compression
threshold, letting the agent perceive that a compression is near.
- This dimension is evaluated independently of the two above.
+ With the compression tool enabled and no task in progress, the
+ agent is also told that it can compress right now. This dimension
+ is evaluated independently of the two above.
- **Tool error**: injected when the same tool call, i.e. the same tool
name and arguments, has failed in the last
``injection_config.tool_retries_limit`` consecutive tool results, so
@@ -1446,9 +1529,9 @@ class Agent:
# =====================================================================
# Step 4: Context Length
# =====================================================================
- # The context length is checked independently of the dimensions above,
- # and only at the beginning of a reply, where the context has just
- # grown by the new input
+ # The context length is checked independently of the dimensions
+ # above, and only at the beginning of a reply, where the context has
+ # just grown by the new input
if self.state.cur_iter == 0:
# Count the current tokens
kwargs = await self._prepare_model_input()
@@ -1457,22 +1540,35 @@ class Agent:
trigger_tokens = int(
self.context_config.trigger_ratio * self.model.context_size,
)
-
if input_tokens > (
- max(
- 0.0,
+ (
self.context_config.trigger_ratio
- - self.injection_config.context_buffer_ratio,
+ - self.context_config.context_buffer_ratio
)
* self.model.context_size
):
# To trigger memory compress
- injections["context-length"] = (
+ hint = (
f"Your current context contains {input_tokens} "
f"tokens. When reaching {trigger_tokens} tokens, "
f"your context will be compressed."
)
+ # No task in progress means a boundary where the agent can
+ # compress by itself, preserving the completed work in a
+ # summary it writes
+ if (
+ self.context_config.compression_tool_enabled
+ and task_status["in_progress"] == 0
+ ):
+ hint += (
+ " No task is in progress, so judge by yourself "
+ "whether the context should be compressed now by "
+ f"calling `{_COMPRESSION_TOOL_NAME}`."
+ )
+
+ injections["context-length"] = hint
+
# =====================================================================
# Step 5: Check Repeated Tool Errors
# =====================================================================
@@ -2805,6 +2901,23 @@ class Agent:
if msg_index < 0:
return [], deepcopy(self.state.context)
+ # Compression can also be requested from inside the acting loop. In
+ # that case the current tool call has been written to context but its
+ # result has not. Never move an unfinished call into the summary: the
+ # result will be appended after the tool returns and must remain paired
+ # with its call in the retained context.
+ unfinished_tool_call_ids = {
+ block.id
+ for block in self.state.get_unfinished_tool_calls(self.name)
+ }
+ for index, msg in enumerate(self.state.context[: msg_index + 1]):
+ if any(
+ block.id in unfinished_tool_call_ids
+ for block in msg.get_content_blocks("tool_call")
+ ):
+ msg_index = index
+ break
+
# The msgs that won't exceed the reserved token limit
msgs_to_compress = self.state.context[:msg_index]
msgs_to_reserve = self.state.context[msg_index + 1 :]
@@ -2830,6 +2943,15 @@ class Agent:
break
block_index -= 1
+ unfinished_block_indexes = [
+ index
+ for index, block in enumerate(boundary_msg_content)
+ if isinstance(block, ToolCallBlock)
+ and block.id in unfinished_tool_call_ids
+ ]
+ if unfinished_block_indexes:
+ block_index = min(block_index, min(unfinished_block_indexes) - 1)
+
# Adjust the block_index to avoid splitting tool call and result pairs.
# Moving the boundary can bring another tool call into the compressed
# part while leaving its result reserved, so repeat until it is stable.
@@ -2854,7 +2976,24 @@ class Agent:
# Move unmatched results into the compressed part and recheck,
# because this move can split another tool call/result pair.
- block_index = max(remain_result_ids.values())
+ new_block_index = max(remain_result_ids.values())
+
+ if unfinished_block_indexes and new_block_index >= min(
+ unfinished_block_indexes,
+ ):
+ # The move would compress an unfinished tool call, so reserve
+ # the calls of the unmatched results instead
+ block_index = (
+ min(
+ index
+ for index, block in enumerate(boundary_msg_content)
+ if isinstance(block, ToolCallBlock)
+ and block.id in remain_result_ids
+ )
+ - 1
+ )
+ else:
+ block_index = new_block_index
# Split the boundary msg content
boundary_msg_to_compress.content = boundary_msg_content[
@@ -3094,6 +3233,14 @@ class Agent:
# The conversation context
messages.extend(self.state.context)
+ # Equip the compression tool, whose registration is kept across
+ # replies so that its schema is stable for prompt caching
+ if self.context_config.compression_tool_enabled and (
+ await self.toolkit.get_tool(_COMPRESSION_TOOL_NAME)
+ is not self._compression_tool
+ ):
+ await self.toolkit.add_tool(self._compression_tool)
+
# Get the tools schemas
tools = await self.toolkit.get_tool_schemas(
self.state.tool_context.activated_groups,
diff --git a/src/agentscope/agent/_config.py b/src/agentscope/agent/_config.py
index 384a3f60e..e54f0c422 100644
--- a/src/agentscope/agent/_config.py
+++ b/src/agentscope/agent/_config.py
@@ -63,10 +63,25 @@ class ContextConfig(BaseModel):
"""The ratio of the tokens to reserve in context compression, which should
be smaller than the trigger ratio."""
+ context_buffer_ratio: float = Field(
+ title="Context Buffer",
+ default=0.2,
+ ge=0,
+ le=1,
+ description=(
+ "The buffer ahead of the 'trigger_ratio', within which the agent "
+ "is told that a compression is near, and can compress by itself "
+ "if the compression tool is enabled. It must be smaller than the "
+ "'trigger_ratio'."
+ ),
+ )
+ """The buffer ahead of the compression threshold, e.g. with a trigger ratio
+ of 0.8 and a buffer of 0.2, the context length is injected once the input
+ tokens exceed 60% of the model context size."""
+
compression_prompt: str = Field(
default=(
- "<system-hint>You have been working on the task described above "
- "but have not yet completed it. "
+ "<system-hint>You have been working on the task described above. "
"Now write a continuation summary that will allow you to resume "
"work efficiently in a future context window where the "
"conversation history will be replaced with this summary. "
@@ -138,6 +153,29 @@ class ContextConfig(BaseModel):
)
"""The tool result limit to avoid tool result bursting."""
+ compression_fallback_to_truncation: bool = Field(
+ default=True,
+ description=(
+ "Whether to truncate the oldest context when the compression "
+ "summary cannot be generated. Turning it off raises the error "
+ "instead, keeping the context intact at the cost of exceeding "
+ "the context length."
+ ),
+ )
+ """Whether to fall back to context truncation when the summary generation
+ fails."""
+
+ compression_tool_enabled: bool = Field(
+ default=False,
+ description=(
+ "Whether to expose a context compression tool to the agent. "
+ "When runtime-state injection is enabled, the agent is prompted "
+ "to use the tool between tasks as the context approaches the "
+ "hard compression threshold."
+ ),
+ )
+ """Whether the agent can explicitly request context compression."""
+
max_image_num: int = Field(
title="Max Image Number",
default=5,
@@ -205,20 +243,19 @@ class InjectionConfig(BaseModel):
"""The minimum elapsed time in **hours** from the recorded time to trigger
a new time injection."""
- context_buffer_ratio: float = Field(
+ context_buffer_ratio: float | None = Field(
title="Context Buffer",
- default=0.2,
+ default=None,
ge=0,
le=1,
description=(
- "The buffer that will activate context length injection before "
- "context compression, which should be smaller than the "
- "'trigger_ratio' of the context config."
+ "Deprecated, use the 'context_buffer_ratio' of the context "
+ "config instead. When provided, it overrides the one in the "
+ "context config."
),
)
- """The buffer ahead of the compression threshold, e.g. with a trigger ratio
- of 0.8 and a buffer of 0.2, the context length is injected once the input
- tokens exceed 60% of the model context size."""
+ """Deprecated in favor of ``ContextConfig.context_buffer_ratio``, which
+ is also consumed by the context compression tool."""
tool_retries_limit: int = Field(
title="Tool Retries Limit",
diff --git a/src/agentscope/tool/_adapters.py b/src/agentscope/tool/_adapters.py
index 4c623f79b..e61463912 100644
--- a/src/agentscope/tool/_adapters.py
+++ b/src/agentscope/tool/_adapters.py
@@ -61,6 +61,7 @@ class FunctionTool(ToolBase):
is_read_only: bool = False,
is_state_injected: bool = False,
middlewares: list[ToolMiddlewareBase] | None = None,
+ permission: PermissionDecision | None = None,
) -> None:
"""Initialize the FunctionTool.
@@ -87,6 +88,9 @@ class FunctionTool(ToolBase):
Whether this tool requires agent state injection.
middlewares (`list[ToolMiddlewareBase] | None`, optional):
Tool middlewares wrapping the tool execution.
+ permission (`PermissionDecision | None`, optional):
+ The permission decision of this tool. If not provided, the
+ user will be asked to confirm the tool call.
"""
super().__init__(middlewares=middlewares)
self.name = name or func.__name__
@@ -107,6 +111,7 @@ class FunctionTool(ToolBase):
self.is_external_tool = False
self.is_mcp = False
self._func = func
+ self._permission = permission
async def check_permissions(
self,
@@ -115,12 +120,14 @@ class FunctionTool(ToolBase):
) -> PermissionDecision:
"""Check permissions for the tool usage.
- Default implementation allows all operations.
-
Returns:
`PermissionDecision`:
- Permission decision (default: allowed).
+ The permission decision given in the constructor, or asking
+ the user to confirm the tool call if not provided.
"""
+ if self._permission is not None:
+ return self._permission
+
return PermissionDecision(
behavior=PermissionBehavior.ASK,
message="Custom function tools must be explicitly allowed "
diff --git a/tests/agent_basic_test.py b/tests/agent_basic_test.py
index 61f708e88..31870f724 100644
--- a/tests/agent_basic_test.py
+++ b/tests/agent_basic_test.py
@@ -183,8 +183,8 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
)
async def test_inconsistent_ratios_are_rejected(self) -> None:
- """The ratios across the context and injection configs must leave room
- ahead of the compression threshold."""
+ """The ratios of the context config must leave room ahead of the
+ compression threshold."""
with self.assertRaises(ValueError):
Agent(
name="agent",
@@ -201,10 +201,27 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
name="agent",
system_prompt="You are an agent.",
model=MockModel(),
- context_config=ContextConfig(trigger_ratio=0.5),
- injection_config=InjectionConfig(context_buffer_ratio=0.5),
+ context_config=ContextConfig(
+ trigger_ratio=0.5,
+ context_buffer_ratio=0.5,
+ ),
)
+ async def test_deprecated_context_buffer_ratio_is_migrated(self) -> None:
+ """The buffer ratio of the injection config still takes effect, and
+ overrides the one in the context config."""
+ context_config = ContextConfig(context_buffer_ratio=0.1)
+ with self.assertWarns(DeprecationWarning):
+ agent = Agent(
+ name="agent",
+ system_prompt="You are an agent.",
+ model=MockModel(),
+ context_config=context_config,
+ injection_config=InjectionConfig(context_buffer_ratio=0.3),
+ )
+
+ self.assertEqual(agent.context_config.context_buffer_ratio, 0.3)
+
async def test_streaming_reasoning(self) -> None:
"""Test the streaming model inference without tool calls generated,
only text in model response.
diff --git a/tests/agent_injection_test.py b/tests/agent_injection_test.py
index 3ae462eec..b640138a5 100644
--- a/tests/agent_injection_test.py
+++ b/tests/agent_injection_test.py
@@ -1,6 +1,7 @@
# -*- coding: utf-8 -*-
"""Unit tests for the runtime state injection of the agent, i.e. the
``Agent._inject_runtime_state`` method."""
+# pylint: disable=too-many-public-methods
from datetime import datetime, tzinfo
from unittest.async_case import IsolatedAsyncioTestCase
from unittest.mock import AsyncMock, patch
@@ -9,7 +10,7 @@ from pydantic import ValidationError
from utils import AnyString, MockModel
-from agentscope.agent import Agent, InjectionConfig
+from agentscope.agent import Agent, ContextConfig, InjectionConfig
from agentscope.message import (
HintBlock,
ToolCallBlock,
@@ -361,6 +362,80 @@ class AgentInjectionTest(IsolatedAsyncioTestCase):
[evt.model_dump() for evt in events],
)
+ async def test_compression_tool_is_recommended_between_tasks(self) -> None:
+ """A long context at a task boundary recommends the agent tool."""
+ expected_hint = (
+ "<system-reminder>Treat the following as the ground truth at this "
+ "point of the conversation. Anything stated earlier is outdated, "
+ "and a later reminder, if any, supersedes this one:\n"
+ "<context-length>Your current context contains 700 tokens. "
+ "When reaching 800 tokens, your context will be compressed. "
+ "No task is in progress, so judge by yourself whether the "
+ "context should be compressed now by calling `CompressContext`."
+ "</context-length>\n"
+ "</system-reminder>"
+ )
+ self.agent.context_config = ContextConfig(
+ trigger_ratio=0.8,
+ reserve_ratio=0.1,
+ compression_tool_enabled=True,
+ )
+ self.agent.state.cur_iter = 0
+ self._add_injection("2026-07-01T12:00:00")
+ self.model.count_tokens = AsyncMock(return_value=700)
+
+ events = await self._run_injection()
+
+ self.assertEqual(
+ [self._expected_event(expected_hint)],
+ [evt.model_dump() for evt in events],
+ )
+
+ async def test_compression_tool_is_not_recommended_within_a_task(
+ self,
+ ) -> None:
+ """An in-progress task isn't a boundary to compress at."""
+ self.agent.context_config = ContextConfig(
+ trigger_ratio=0.8,
+ reserve_ratio=0.1,
+ compression_tool_enabled=True,
+ )
+ self.agent.state.cur_iter = 0
+ self._add_injection("2026-07-01T12:00:00")
+ self.agent.state.tasks_context.tasks = [
+ Task(
+ subject="Write the report",
+ description="Draft the quarterly report.",
+ metadata={},
+ state="in_progress",
+ ),
+ ]
+ self.model.count_tokens = AsyncMock(return_value=700)
+
+ events = await self._run_injection()
+
+ self.assertNotIn("CompressContext", events[0].hint)
+ self.assertIn(
+ "<context-length>Your current context contains 700 tokens. "
+ "When reaching 800 tokens, your context will be compressed."
+ "</context-length>",
+ events[0].hint,
+ )
+
+ async def test_disabled_compression_tool_keeps_awareness_boundary(
+ self,
+ ) -> None:
+ """The regular context reminder retains its strict boundary."""
+ self.agent.state.cur_iter = 0
+ self._add_injection("2026-07-01T12:00:00")
+ # Exactly max(0, 0.8 - 0.2) * 1000; the original behavior requires
+ # token usage to be strictly greater than this boundary.
+ self.model.count_tokens = AsyncMock(return_value=600)
+
+ events = await self._run_injection()
+
+ self.assertEqual([], events)
+
async def test_template_without_placeholder_is_rejected(self) -> None:
"""A template that would silently drop the injected fields should be
rejected at the config level."""
diff --git a/tests/compress_context_test.py b/tests/compress_context_test.py
index 314f0ba29..a4a79acae 100644
--- a/tests/compress_context_test.py
+++ b/tests/compress_context_test.py
@@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
"""A template test case."""
-# pylint: disable=protected-access
+# pylint: disable=protected-access, too-many-public-methods
import hashlib
import json
import os
@@ -11,8 +11,8 @@ from unittest.async_case import IsolatedAsyncioTestCase
from utils import MockModel, AnyString
-from agentscope.model import StructuredResponse
-from agentscope.agent import Agent, ContextConfig
+from agentscope.model import ChatResponse, StructuredResponse
+from agentscope.agent import Agent, ContextConfig, InjectionConfig
from agentscope.state import AgentState
from agentscope.message import (
UserMsg,
@@ -1520,6 +1520,281 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
),
)
+ async def test_compression_tool_compresses_below_hard_threshold(
+ self,
+ ) -> None:
+ """The tool compresses at the ratio where it is recommended, which is
+ below the hard compression threshold."""
+ model = RecordingStructuredMockModel(context_size=500)
+ model.set_structured_response(
+ StructuredResponse(
+ content={
+ "task_overview": "task",
+ "current_state": "complete",
+ "important_discoveries": "none",
+ "next_steps": "None",
+ "context_to_preserve": "none",
+ },
+ ),
+ )
+ agent = Agent(
+ name="Friday",
+ system_prompt="You are helpful.",
+ model=model,
+ # The context is 316 tokens, above the 250 tokens the tool
+ # compresses from, and below the 450 tokens hard threshold
+ context_config=ContextConfig(
+ trigger_ratio=0.9,
+ reserve_ratio=0.3,
+ context_buffer_ratio=0.4,
+ compression_tool_enabled=True,
+ ),
+ state=AgentState(
+ session_id="123",
+ context=[
+ UserMsg("User", str(index) * 80, id=str(index))
+ for index in range(8)
+ ],
+ ),
+ toolkit=Toolkit(),
+ )
+
+ self.assertDictEqual(
+ (await agent._compress_context_tool()).model_dump(),
+ {
+ "content": [
+ {
+ "type": "text",
+ "text": "Context compressed successfully.",
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "finished_at": None,
+ },
+ ],
+ "state": ToolResultState.SUCCESS,
+ "is_last": True,
+ "metadata": {},
+ "id": AnyString(),
+ },
+ )
+ self.assertIn("# Current State\ncomplete", agent.state.summary)
+
+ async def test_compression_tool_skips_small_context(self) -> None:
+ """The tool leaves a context below the recommended ratio untouched,
+ so that a spontaneous call doesn't lose details for nothing."""
+ model = RecordingStructuredMockModel(context_size=500)
+ agent = Agent(
+ name="Friday",
+ system_prompt="You are helpful.",
+ model=model,
+ # The context is 176 tokens, below the 250 tokens the tool
+ # compresses from
+ context_config=ContextConfig(
+ trigger_ratio=0.9,
+ reserve_ratio=0.3,
+ context_buffer_ratio=0.4,
+ compression_tool_enabled=True,
+ ),
+ state=AgentState(
+ session_id="123",
+ context=[UserMsg("User", "1" * 80, id="1")],
+ ),
+ toolkit=Toolkit(),
+ )
+
+ self.assertDictEqual(
+ (await agent._compress_context_tool()).model_dump(),
+ {
+ "content": [
+ {
+ "type": "text",
+ "text": "The context is not long enough to compress, "
+ "so it remains unchanged.",
+ "id": AnyString(),
+ "created_at": AnyString(),
+ "finished_at": None,
+ },
+ ],
+ "state": ToolResultState.SUCCESS,
+ "is_last": True,
+ "metadata": {},
+ "id": AnyString(),
+ },
+ )
+ self.assertEqual(agent.state.summary, "")
+ self.assertListEqual(
+ [msg.id for msg in agent.state.context],
+ ["1"],
+ )
+ self.assertListEqual(model.recorded_structured_messages, [])
+
+ async def test_compression_tool_keeps_its_call_result_pair(self) -> None:
+ """Compression invoked during acting preserves its own tool call."""
+ model = RecordingStructuredMockModel(context_size=500, stream=False)
+ model.set_structured_response(
+ StructuredResponse(
+ content={
+ "task_overview": "task",
+ "current_state": "phase complete",
+ "important_discoveries": "none",
+ "next_steps": "continue",
+ "context_to_preserve": "none",
+ },
+ ),
+ )
+ model.set_responses(
+ [
+ ChatResponse(
+ content=[
+ ToolCallBlock(
+ id="compress-1",
+ name="CompressContext",
+ input="{}",
+ ),
+ ],
+ is_last=True,
+ ),
+ ChatResponse(
+ content=[TextBlock(text="done")],
+ is_last=True,
+ ),
+ ],
+ )
+ agent = Agent(
+ name="Friday",
+ system_prompt="You are helpful.",
+ model=model,
+ toolkit=Toolkit(),
+ # The context is 316 tokens, above the 250 tokens the tool
+ # compresses from, and below the 450 tokens hard threshold
+ context_config=ContextConfig(
+ trigger_ratio=0.9,
+ reserve_ratio=0.3,
+ context_buffer_ratio=0.4,
+ compression_tool_enabled=True,
+ ),
+ state=AgentState(
+ session_id="123",
+ context=[
+ UserMsg("User", str(index) * 80, id=str(index))
+ for index in range(8)
+ ],
+ ),
+ injection_config=InjectionConfig(inject_runtime_state=False),
+ )
+
+ result = await agent.reply(UserMsg("User", "continue"))
+
+ self.assertEqual(result.get_text_content(), "done")
+ self.assertIn("# Current State\nphase complete", agent.state.summary)
+ self.assertListEqual(
+ [
+ type(block)
+ for msg in agent.state.context
+ for block in msg.content
+ if isinstance(block, (ToolCallBlock, ToolResultBlock))
+ and block.id == "compress-1"
+ ],
+ [ToolCallBlock, ToolResultBlock],
+ )
+
+ async def test_split_keeps_unfinished_call_before_its_earlier_pair(
+ self,
+ ) -> None:
+ """A finished pair after an unfinished call must not drag the
+ unfinished call into the compressed part."""
+ agent = Agent(
+ name="Friday",
+ system_prompt="You are helpful.",
+ model=MockModel(context_size=100),
+ toolkit=Toolkit(),
+ state=AgentState(
+ session_id="123",
+ context=[
+ AssistantMsg(
+ "Friday",
+ [
+ ToolCallBlock(id="a", name="Read", input="{}"),
+ ToolCallBlock(
+ id="compress-1",
+ name="CompressContext",
+ input="{}",
+ ),
+ ToolResultBlock(
+ id="a",
+ name="Read",
+ output=[TextBlock(text="content")],
+ ),
+ ],
+ id="reply-1",
+ ),
+ ],
+ ),
+ )
+ agent.state.reply_id = "reply-1"
+
+ (
+ msgs_to_compress,
+ msgs_to_reserve,
+ ) = await agent._split_context_for_compression(1, [])
+
+ self.assertListEqual(msgs_to_compress, [])
+ self.assertListEqual(
+ [
+ (type(block).__name__, block.id)
+ for msg in msgs_to_reserve
+ for block in msg.content
+ ],
+ [
+ ("ToolCallBlock", "a"),
+ ("ToolCallBlock", "compress-1"),
+ ("ToolResultBlock", "a"),
+ ],
+ )
+
+ async def test_compression_tool_registration_tracks_config(self) -> None:
+ """The compression tool is exposed only when it's enabled, and the
+ same instance is kept across replies for a stable schema."""
+ for enabled in (False, True):
+ with self.subTest(enabled=enabled):
+ model = MockModel(stream=False)
+ model.set_responses(
+ [
+ ChatResponse(
+ content=[TextBlock(text="done")],
+ is_last=True,
+ ),
+ ChatResponse(
+ content=[TextBlock(text="done again")],
+ is_last=True,
+ ),
+ ],
+ )
+ toolkit = Toolkit()
+ agent = Agent(
+ name="Friday",
+ system_prompt="You are helpful.",
+ model=model,
+ toolkit=toolkit,
+ context_config=ContextConfig(
+ compression_tool_enabled=enabled,
+ ),
+ injection_config=InjectionConfig(
+ inject_runtime_state=False,
+ ),
+ )
+
+ await agent.reply(UserMsg("User", "hello"))
+ tool = await toolkit.get_tool("CompressContext")
+ self.assertEqual(tool is not None, enabled)
+
+ if enabled:
+ await agent.reply(UserMsg("User", "hello again"))
+ self.assertIs(
+ await toolkit.get_tool("CompressContext"),
+ tool,
+ )
+
async def test_max_image_num_without_offloader(self) -> None:
"""The oldest images exceeding the limit are dropped and replaced by
hints without path information when no offloader is provided."""
@@ -2151,6 +2426,23 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
self.assertEqual(agent.state, expected_state)
+ async def test_summary_failure_raises_without_truncation_fallback(
+ self,
+ ) -> None:
+ """Without the truncation fallback, a failed summary raises and
+ leaves the context untouched."""
+ agent, _ = _make_failing_compression_agent()
+ agent.context_config.compression_fallback_to_truncation = False
+ expected_state = agent.state.model_copy(deep=True)
+
+ with self.assertRaisesRegex(
+ RuntimeError,
+ "simulated compression overflow",
+ ):
+ await agent.compress_context()
+
+ self.assertEqual(agent.state, expected_state)
+
async def test_offload_reminder_is_not_duplicated(self) -> None:
"""Repeated fallback preserves one reminder for a stable path."""
reminder = (
diff --git a/tests/toolkit_test.py b/tests/toolkit_test.py
index 5fb1b9ed1..bb9d6acc2 100644
--- a/tests/toolkit_test.py
+++ b/tests/toolkit_test.py
@@ -28,6 +28,7 @@ from agentscope.tool import (
FunctionTool,
)
from agentscope.permission import (
+ PermissionContext,
PermissionDecision,
PermissionBehavior,
)
@@ -1254,6 +1255,46 @@ class RegisterFunctionTest(IsolatedAsyncioTestCase):
],
)
+ async def test_permission(self) -> None:
+ """Test the permission decision of the function tool."""
+
+ def set_mode(mode: str) -> str:
+ """Set the working mode.
+
+ Args:
+ mode: The mode to use
+ """
+ return f"Mode set to {mode}"
+
+ # Ask the user by default
+ self.assertEqual(
+ await FunctionTool(set_mode).check_permissions(
+ {"mode": "fast"},
+ PermissionContext(),
+ ),
+ PermissionDecision(
+ behavior=PermissionBehavior.ASK,
+ message="Custom function tools must be explicitly allowed "
+ "by the user.",
+ ),
+ )
+
+ # The given decision takes effect
+ decision = PermissionDecision(
+ behavior=PermissionBehavior.ALLOW,
+ message="set_mode is always allowed.",
+ )
+ self.assertEqual(
+ await FunctionTool(
+ set_mode,
+ permission=decision,
+ ).check_permissions(
+ {"mode": "fast"},
+ PermissionContext(),
+ ),
+ decision,
+ )
+
class ToolGroupTest(IsolatedAsyncioTestCase):
"""The tool group test case."""