Build and run agents you can see, understand and trust.
Python agentchatbotlarge-language-modelsllmllm-agentmcpmulti-agentmulti-modalreact-agentrealtime-agentvoice-agentvoice-assistant
feat(tool): integrate the tool and workspace modules with the Agent class (#1642)
DavdGaocc1087dcade6
diff --git a/docs/FAQ.md b/docs/FAQ.mdnew file mode 100644index 000000000..fdd5bc52b--- /dev/null+++ b/docs/FAQ.md@@ -0,0 +1,55 @@+# AgentScope FAQ++---++## AgentScope Core Framework++### Q1: Does AgentScope's Workstation still exist?++**A**: No. Since **AgentScope 1.0**, the project has fully transitioned to a **code-first development approach** and no longer maintains the earlier drag-and-drop Workstation interface. **It is not recommended to use Workstation in new projects**.++---++### Q2: Why do different LLMs require different Formatters?++**A**: Different LLM providers (e.g., OpenAI, Anthropic, DashScope) have different requirements for input message formats (such as role fields and tool call structures). AgentScope uses **Formatters to decouple model differences**, ensuring generated messages conform to each API's specifications. Even models that claim OpenAI compatibility may require separate adaptation due to version lag.++---++### Q3: Does AgentScope support the MCP (Model Control Protocol)?++**A**: Yes. AgentScope is compatible with the standard MCP protocol for integrating external tools and services. Tutorial reference: [MCP User Guide](https://docs.agentscope.io).++---++### Q4: Are there community-developed AgentScope applications beyond the official examples?++**A**: Yes! Check out the [agentscope-samples](https://github.com/agentscope-ai/agentscope-samples) repository, which contains community-contributed examples including Werewolf, debates, intelligent customer service, and more.++---++### Q5: What is the difference between model fine-tuning and memory retrieval?++**A**:++* **Model fine-tuning**: Modifies model parameters through training to improve performance on specific tasks.++* **Memory retrieval**: Injects relevant context during inference via vector databases or similar methods. The two are **not mutually exclusive and can even be combined** — for example, fine-tuning a model to better leverage retrieved memory information.+++---++### Q6: What is the relationship between AgentScope-Java and Spring AI Alibaba?++**A**:++* **AgentScope-Java** is the Java implementation of AgentScope, currently under development, aiming to maintain consistency with the Python version in philosophy, design, and functionality.++* **Spring AI Alibaba** has **switched its underlying layer to AgentScope-Java**, focusing on Spring ecosystem integration. If you use Spring AI Alibaba's Agentic API, future upgrades will automatically provide AgentScope capabilities — **no need to separately introduce AgentScope-Java**.+++---++### Q7: Can AgentScope be used with AI coding assistants like Cursor or Claude Code?++**A**: Absolutely! AgentScope has a clean code structure and comprehensive documentation, making it well-suited for use with AI coding assistants. It is recommended to provide AgentScope source code or tutorials as context to the AI for better results.diff --git a/docs/FAQ_zh.md b/docs/FAQ_zh.mdnew file mode 100644index 000000000..cead4cd71--- /dev/null+++ b/docs/FAQ_zh.md@@ -0,0 +1,56 @@+# AgentScope 常见问题 (FAQ)++---++## AgentScope 核心框架++### Q1:AgentScope 的 Workstation(工作站)还存在吗?++**A**:不存在了。从 **AgentScope 1.0 起**,项目已全面转向 **代码优先(code-first)的开发模式**,不再维护早期的拖拽式 Workstation 界面。**不建议在新项目中使用 Workstation**。++---++### Q2:为什么不同大模型需要不同的 Formatter?++**A**:不同大模型厂商(如 OpenAI、Anthropic、通义千问等)对输入消息格式(如 role 字段、工具调用结构)有不同要求。AgentScope 通过 **Formatter 解耦模型差异**,确保生成的消息符合各 API 规范。即使某些模型声称兼容 OpenAI,也可能因版本滞后需单独适配。++---++### Q3:AgentScope 是否支持 MCP(Model Control Protocol)协议?++**A**:支持。AgentScope 兼容标准 MCP 协议,可用于对接外部工具或服务。教程参考:[MCP 使用指南](https://docs.agentscope.io)。++---++### Q4:除了官方示例,是否有社区开发的 AgentScope 应用?++**A**:有!可查看 [agentscope-samples](https://github.com/agentscope-ai/agentscope-samples) 仓库,其中包含社区贡献的狼人杀、辩论、智能客服等多种场景示例。++---++### Q5:模型微调和记忆召回有什么区别?++**A**:++* **模型微调**:通过训练修改模型参数,提升特定任务能力。++* **记忆召回**:在推理时通过向量数据库等方式注入相关上下文。 两者**不冲突,甚至可结合使用**——例如微调一个模型使其更擅长利用召回的记忆信息。+++---++### Q6:AgentScope-Java 和 Spring AI Alibaba 是什么关系?++**A**:++* **AgentScope-Java** 是 AgentScope 的 Java 实现,目前仍在建设中,目标是与 Python 版在理念、设计和功能上保持一致。++* **Spring AI Alibaba** 将**底层切换为 AgentScope-Java**,专注 Spring 生态集成。如果你使用 Spring AI Alibaba 的 Agentic API,后续升级即可自动获得 AgentScope 能力,**无需单独引入 AgentScope-Java**。+++---++### Q7:能否配合 Cursor、Claude Code 等 AI 编程助手使用 AgentScope?++**A**:完全可以!AgentScope 代码结构清晰、文档完善,非常适合与 AI 编程助手配合。建议将 AgentScope 源码或教程作为上下文提供给 AI,效果更佳。+diff --git a/scripts/model_examples/anthropic_call.py b/scripts/model_examples/anthropic_call.pyindex 1e4da66fc..20da699d1 100644--- a/scripts/model_examples/anthropic_call.py+++ b/scripts/model_examples/anthropic_call.py@@ -14,7 +14,8 @@ from agentscope.message import ()from agentscope.model import AnthropicChatModelfrom agentscope.credential import AnthropicCredential-from agentscope.tool import Toolkit, ToolChoice+from agentscope.tool import Toolkit, ToolChoice, FunctionTool+# ---------------------------------------------------------------------------# Example 1: Simple user message (streaming)@@ -67,9 +68,8 @@ def get_weather(city: str) -> str:async def example_tool_call() -> None:"""Call the Anthropic model with tool calling enabled."""- toolkit = Toolkit()- toolkit.register_function(get_weather)- tools = toolkit.get_function_schemas()+ toolkit = Toolkit(tools=[FunctionTool(get_weather)])+ tools = await toolkit.get_tool_schemas()model = AnthropicChatModel(credential=AnthropicCredential(diff --git a/scripts/model_examples/dashscope_call.py b/scripts/model_examples/dashscope_call.pyindex 7791e8dac..9c496a915 100644--- a/scripts/model_examples/dashscope_call.py+++ b/scripts/model_examples/dashscope_call.py@@ -14,7 +14,8 @@ from agentscope.message import ()from agentscope.model import DashScopeChatModelfrom agentscope.credential import DashScopeCredential-from agentscope.tool import Toolkit, ToolChoice+from agentscope.tool import Toolkit, ToolChoice, FunctionTool+# ---------------------------------------------------------------------------# Example 1: Simple user message (streaming)@@ -67,9 +68,8 @@ async def example_tool_call() -> None:Uses qwen3-max which supports both thinking mode and tool calling."""- toolkit = Toolkit()- toolkit.register_function(get_weather)- tools = toolkit.get_function_schemas()+ toolkit = Toolkit(tools=[FunctionTool(get_weather)])+ tools = await toolkit.get_tool_schemas()model = DashScopeChatModel(credential=DashScopeCredential(diff --git a/scripts/model_examples/deepseek_call.py b/scripts/model_examples/deepseek_call.pyindex a96545d9c..0d5910f3c 100644--- a/scripts/model_examples/deepseek_call.py+++ b/scripts/model_examples/deepseek_call.py@@ -19,7 +19,8 @@ from agentscope.message import ()from agentscope.model import DeepSeekChatModelfrom agentscope.credential import DeepSeekCredential-from agentscope.tool import Toolkit, ToolChoice+from agentscope.tool import Toolkit, ToolChoice, FunctionTool+# ---------------------------------------------------------------------------# Example 1: Simple user message (streaming, with chain-of-thought)@@ -72,9 +73,8 @@ async def example_tool_call() -> None:Uses deepseek-v4-flash (non-reasoning) for tool calling, sincedeepseek-reasoner has limited tool call support."""- toolkit = Toolkit()- toolkit.register_function(get_weather)- tools = toolkit.get_function_schemas()+ toolkit = Toolkit(tools=[FunctionTool(get_weather)])+ tools = await toolkit.get_tool_schemas()model = DeepSeekChatModel(credential=DeepSeekCredential(diff --git a/scripts/model_examples/gemini_call.py b/scripts/model_examples/gemini_call.pyindex 9ac5f95ef..c08a2ad8e 100644--- a/scripts/model_examples/gemini_call.py+++ b/scripts/model_examples/gemini_call.py@@ -14,7 +14,8 @@ from agentscope.message import ()from agentscope.model import GeminiChatModelfrom agentscope.credential import GeminiCredential-from agentscope.tool import Toolkit, ToolChoice+from agentscope.tool import Toolkit, ToolChoice, FunctionTool+# ---------------------------------------------------------------------------# Example 1: Simple user message (streaming)@@ -67,9 +68,8 @@ def get_weather(city: str) -> str:async def example_tool_call() -> None:"""Call the Gemini model with tool calling enabled."""- toolkit = Toolkit()- toolkit.register_function(get_weather)- tools = toolkit.get_function_schemas()+ toolkit = Toolkit(tools=[FunctionTool(get_weather)])+ tools = await toolkit.get_tool_schemas()model = GeminiChatModel(credential=GeminiCredential(diff --git a/scripts/model_examples/moonshot_call.py b/scripts/model_examples/moonshot_call.pyindex a77e91267..625bd59f7 100644--- a/scripts/model_examples/moonshot_call.py+++ b/scripts/model_examples/moonshot_call.py@@ -14,7 +14,8 @@ from agentscope.message import ()from agentscope.model import MoonshotChatModelfrom agentscope.credential import MoonshotCredential-from agentscope.tool import Toolkit, ToolChoice+from agentscope.tool import Toolkit, ToolChoice, FunctionTool+# ---------------------------------------------------------------------------# Example 1: Simple user message (streaming)@@ -63,9 +64,8 @@ def get_weather(city: str) -> str:async def example_tool_call() -> None:"""Call the Moonshot model with tool calling enabled."""- toolkit = Toolkit()- toolkit.register_function(get_weather)- tools = toolkit.get_function_schemas()+ toolkit = Toolkit(tools=[FunctionTool(get_weather)])+ tools = await toolkit.get_tool_schemas()model = MoonshotChatModel(credential=MoonshotCredential(diff --git a/scripts/model_examples/ollama_call.py b/scripts/model_examples/ollama_call.pyindex 6a0519e85..50b795cc4 100644--- a/scripts/model_examples/ollama_call.py+++ b/scripts/model_examples/ollama_call.py@@ -20,7 +20,8 @@ from agentscope.message import ()from agentscope.model import OllamaChatModelfrom agentscope.credential import OllamaCredential-from agentscope.tool import Toolkit, ToolChoice+from agentscope.tool import Toolkit, ToolChoice, FunctionTool+# ---------------------------------------------------------------------------# Example 1: Simple user message (streaming)@@ -70,9 +71,8 @@ def get_weather(city: str) -> str:async def example_tool_call() -> None:"""Call the Ollama model with tool calling enabled."""- toolkit = Toolkit()- toolkit.register_function(get_weather)- tools = toolkit.get_function_schemas()+ toolkit = Toolkit(tools=[FunctionTool(get_weather)])+ tools = await toolkit.get_tool_schemas()model = OllamaChatModel(credential=OllamaCredential(diff --git a/scripts/model_examples/openai_chat_call.py b/scripts/model_examples/openai_chat_call.pyindex 6d2c9a0d4..4bf9a3cdb 100644--- a/scripts/model_examples/openai_chat_call.py+++ b/scripts/model_examples/openai_chat_call.py@@ -14,7 +14,8 @@ from agentscope.message import ()from agentscope.model import OpenAIChatModelfrom agentscope.credential import OpenAICredential-from agentscope.tool import Toolkit, ToolChoice+from agentscope.tool import Toolkit, ToolChoice, FunctionTool+# ---------------------------------------------------------------------------# Example 1: Simple user message (streaming)@@ -66,9 +67,8 @@ def get_weather(city: str) -> str:async def example_tool_call() -> None:"""Call the OpenAI Chat model with tool calling enabled."""- toolkit = Toolkit()- toolkit.register_function(get_weather)- tools = toolkit.get_function_schemas()+ toolkit = Toolkit(tools=[FunctionTool(get_weather)])+ tools = await toolkit.get_tool_schemas()model = OpenAIChatModel(credential=OpenAICredential(diff --git a/scripts/model_examples/openai_response_call.py b/scripts/model_examples/openai_response_call.pyindex 947522e35..6aa7ddf28 100644--- a/scripts/model_examples/openai_response_call.py+++ b/scripts/model_examples/openai_response_call.py@@ -19,7 +19,8 @@ from agentscope.message import ()from agentscope.model import OpenAIResponseModelfrom agentscope.credential import OpenAICredential-from agentscope.tool import Toolkit, ToolChoice+from agentscope.tool import Toolkit, ToolChoice, FunctionTool+# ---------------------------------------------------------------------------# Example 1: Simple user message (streaming)@@ -69,9 +70,8 @@ def get_weather(city: str) -> str:async def example_tool_call() -> None:"""Call the OpenAI Response model with tool calling enabled."""- toolkit = Toolkit()- toolkit.register_function(get_weather)- tools = toolkit.get_function_schemas()+ toolkit = Toolkit(tools=[FunctionTool(get_weather)])+ tools = await toolkit.get_tool_schemas()model = OpenAIResponseModel(credential=OpenAICredential(diff --git a/scripts/model_examples/xai_call.py b/scripts/model_examples/xai_call.pyindex e99ccdbd3..f6b7b5f4b 100644--- a/scripts/model_examples/xai_call.py+++ b/scripts/model_examples/xai_call.py@@ -19,7 +19,8 @@ from agentscope.message import ()from agentscope.model import XAIChatModelfrom agentscope.credential import XAICredential-from agentscope.tool import Toolkit, ToolChoice+from agentscope.tool import Toolkit, ToolChoice, FunctionTool+# ---------------------------------------------------------------------------# Example 1: Simple user message (streaming, with reasoning)@@ -72,9 +73,8 @@ async def example_tool_call() -> None:Uses grok-4.3, xAI's flagship mainstream model."""- toolkit = Toolkit()- toolkit.register_function(get_weather)- tools = toolkit.get_function_schemas()+ toolkit = Toolkit(tools=[FunctionTool(get_weather)])+ tools = await toolkit.get_tool_schemas()model = XAIChatModel(credential=XAICredential(diff --git a/src/agentscope/agent/_agent.py b/src/agentscope/agent/_agent.pyindex a75331d33..12dfa228e 100644--- a/src/agentscope/agent/_agent.py+++ b/src/agentscope/agent/_agent.py@@ -83,6 +83,7 @@ from ..permission import (PermissionEngine,PermissionDecision,)+from ..workspace import Offloaderif TYPE_CHECKING:from ..middleware import MiddlewareBase@@ -98,25 +99,67 @@ class Agent:name: str,system_prompt: str,model: ChatModelBase,- toolkit: Toolkit,+ toolkit: Toolkit | None = None,middlewares: list[MiddlewareBase] | None = None,state: AgentState | None = None,+ offloader: Offloader | None = None,+ # The agent configurationsmodel_config: ModelConfig = ModelConfig(),context_config: ContextConfig = ContextConfig(),react_config: ReActConfig = ReActConfig(),) -> None:+ """Initialize the agent class in AgentScope.++ Args:+ name (`str`):+ The agent identifier.+ system_prompt (`str`):+ The agent's system prompt. Additional instructions may be+ appended to it dynamically during operation.+ model (`ChatModelBase`):+ The chat model/llm used for this agent.+ toolkit (`Toolkit | None`, optional):+ The toolkit used for registering tools, MCPs and skills as the+ sole source.+ middlewares (`list[MiddlewareBase] | None`):+ Middlewares applied to the agent to modify its behavior+ without altering its source code. Supported hook points+ include: reply, reasoning, acting, model call, and system+ prompt retrieval.+ state (`AgentState`):+ The agent state. A new state will be created if not provided.+ offloader (`Offloader | None`, optional):+ The context offloader. If provided, the compressed context and+ tool result will be offloaded.+ model_config (`ModelConfig`):+ The additional chat model configuration including fallback+ model and retries.+ context_config (`CompressionConfig`):+ The context config for context compression and tool result+ compression.+ react_config (`ReActConfig`):+ The config for the reasoning-acting loop.+ """self.name = nameself._system_prompt = system_promptself.model = model- self.toolkit = toolkitself.state = state or AgentState()self.model_config = model_configself.context_config = context_configself.react_config = react_config+ # The permission engineself._engine = PermissionEngine(self.state.permission_context)+ # The offloader/workspace+ self.offloader = offloader++ # ====================================================================+ # The Tool-related logics+ # ====================================================================+ self.toolkit = toolkit or Toolkit()+# ====================================================================# The Middleware-related attributes# ====================================================================@@ -381,6 +424,18 @@ class Agent:# Update the summaryself.state.summary = cfg.summary_template.format(**res.content)++ if self.offloader:+ path = await self.offloader.offload_context(+ self.state.session_id,+ msgs=msgs_to_compress,+ )++ self.state.summary += (+ f"\n<system-reminder>The compressed context is offloaded to "+ f"'{path}', you can refer to it when needed.</system-reminder>"+ )+# Update the contextself.state.context = msgs_to_reserve@@ -604,7 +659,7 @@ class Agent:| Msg,None,]:- """Reasoning entry point (may be wrapped by middleware)."""+ """Reasoning entry point (maybe wrapped by middleware)."""if not self._reasoning_middlewares:async for item in self._reasoning_impl(tool_choice=tool_choice):yield item@@ -986,14 +1041,11 @@ class Agent:# concurrently or notbatches: list[_ToolCallBatch] = []for tool_call in tool_calls:- registered_tool = self.toolkit.tools.get(tool_call.name)+ tool = await self.toolkit.get_tool(tool_call.name)# Treat unregistered or unavailable tools as concurrent tools since# it will not generate side effects and be blocked with acting- if (- registered_tool is None- or registered_tool.tool.is_concurrency_safe- ):+ if tool is None or tool.is_concurrency_safe:if len(batches) == 0 or batches[-1].type != "concurrent":batches.append(_ToolCallBatch(@@ -1209,7 +1261,7 @@ class Agent:# ===================================================================try:# Check if the tool is available- tool = self.toolkit.check_tool_available(+ tool = await self.toolkit.check_tool_available(tool_call.name,self.state.tool_context.activated_groups,)@@ -1353,8 +1405,27 @@ class Agent:reminder = ("\n<<<TRUNCATED>>>\n<system-reminder>The ""remaining content has been omitted for "- "limited context.</system-reminder>"+ "limited context.{offload_reminder}"+ "</system-reminder>")++ offload_reminder = ""+ if self.offloader:+ path = await self.offloader.offload_tool_result(+ self.state.session_id,+ offload_tool_result_block,+ )++ offload_reminder = (+ f" You can refer to the file in '{path}' "+ f"for the truncated content if needed."+ )++ reminder = reminder.format(+ offload_reminder=offload_reminder,+ )++ # Insert the reminder to the tool result outputif isinstance(reserved_tool_result_block.output, str):reserved_tool_result_block.output += reminder@@ -1373,8 +1444,6 @@ class Agent: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(@@ -1850,7 +1919,7 @@ class Agent:messages.extend(self.state.context)# Get the tools schemas- tools = self.toolkit.get_function_schemas(+ tools = await self.toolkit.get_tool_schemas(self.state.tool_context.activated_groups,)diff --git a/src/agentscope/app/_manager/_scheduler/_scheduler_manager.py b/src/agentscope/app/_manager/_scheduler/_scheduler_manager.pyindex 33ada35c3..4d3a136a5 100644--- a/src/agentscope/app/_manager/_scheduler/_scheduler_manager.py+++ b/src/agentscope/app/_manager/_scheduler/_scheduler_manager.py@@ -2,8 +2,6 @@"""The cron scheduler manager class."""from collections.abc import Callable, Coroutine-from apscheduler.schedulers.asyncio import AsyncIOScheduler-from apscheduler.triggers.cron import CronTriggerfrom ....message import UserMsgfrom ....tool import ToolBase@@ -51,6 +49,8 @@ class SchedulerManager:The workspace manager passed through to :class:`ChatService`so triggered agents get the configured toolkit and MCPs."""+ from apscheduler.schedulers.asyncio import AsyncIOScheduler+self._storage = storageself._session_manager = session_managerself._background_task_manager = background_task_manager@@ -270,6 +270,9 @@ class SchedulerManager:`str`:The APScheduler job ID (equal to ``record.id``)."""++ from apscheduler.triggers.cron import CronTrigger+logger.info("Registering schedule %s(%s) cron=%s tz=%s",record.id,@@ -277,6 +280,7 @@ class SchedulerManager:record.data.cron_expression,record.data.timezone,)+trigger = self._build_trigger(record)job = self._scheduler.add_job(trigger,diff --git a/src/agentscope/app/_middleware/_tool_offload_middleware.py b/src/agentscope/app/_middleware/_tool_offload_middleware.pyindex 955f64ea6..8d968e3e6 100644--- a/src/agentscope/app/_middleware/_tool_offload_middleware.py+++ b/src/agentscope/app/_middleware/_tool_offload_middleware.py@@ -214,10 +214,9 @@ class ToolOffloadMiddleware(MiddlewareBase): # pylint: disable=abstract-method# - is_external_tool: external tools wait for a human/external system# to push a result back; offloading them makes no sense because the# agent would lose track of the pending confirmation.- registered = agent.toolkit.tools.get(tool_call.name)- if registered is not None and (- registered.tool.is_state_injected- or registered.tool.is_external_tool+ tool = await agent.toolkit.get_tool(tool_call.name)+ if tool is not None and (+ tool.is_state_injected or tool.is_external_tool):logger.info("Tool '%s' is state-injected or external, executing "diff --git a/src/agentscope/app/_service/_agent.py b/src/agentscope/app/_service/_agent.pyindex 139590087..1981e61a6 100644--- a/src/agentscope/app/_service/_agent.py+++ b/src/agentscope/app/_service/_agent.py@@ -71,7 +71,7 @@ async def get_agent(toolkit = Toolkit(tools=[Bash(), Read(), Write(), Edit()],- skills=[],+ skills_or_loaders=[],)for mcp_client in await workspace.list_mcps():diff --git a/src/agentscope/mcp/_mcp_client.py b/src/agentscope/mcp/_mcp_client.pyindex d8bb0f963..3fc48f87d 100644--- a/src/agentscope/mcp/_mcp_client.py+++ b/src/agentscope/mcp/_mcp_client.py@@ -14,9 +14,10 @@ from ._config import StdioMCPConfig, HttpMCPConfigfrom .._logging import loggerif TYPE_CHECKING:- from ..tool import MCPTool+ from ..tool import MCPTool, ToolBaseelse:MCPTool = Any+ ToolBase = Anyclass MCPClient(BaseModel):@@ -84,6 +85,18 @@ class MCPClient(BaseModel):description="The MCP server configuration.",)+ enable_tools: list[str] | None = None+ """The tools enabled in this MCP, which will be returned in the+ `list_tools` function. If `None`, all tools from the MCP server will be+ returned."""++ disable_tools: list[str] | None = None+ """The tools disabled in this MCP, which will be filtered out in the+ `list_tools` function."""++ execution_timeout: float | None = None+ """The execution timeout in seconds for calling the tools from this MCP."""+# Private attributes_client: Any = PrivateAttr(default=None)_session: ClientSession | None = PrivateAttr(default=None)@@ -108,6 +121,35 @@ class MCPClient(BaseModel):"STDIO MCP must be stateful (is_stateful=True).",)+ # Check arguments for self.enable_tools and disable_tools+ if self.enable_tools is not None:+ if not isinstance(self.enable_tools, list) or any(+ not isinstance(_, str) for _ in self.enable_tools+ ):+ raise ValueError(+ "Enable tools should be a list of strings, but got "+ f"{self.enable_tools}.",+ )++ if self.disable_tools is not None:+ if not isinstance(self.disable_tools, list) or any(+ not isinstance(_, str) for _ in self.disable_tools+ ):+ raise ValueError(+ "Disable tools should be a list of strings, but got "+ f"{self.disable_tools}.",+ )++ if self.enable_tools is not None and self.disable_tools is not None:+ intersection = set(self.enable_tools).intersection(+ set(self.disable_tools),+ )+ if len(intersection) != 0:+ raise ValueError(+ f"The tools in enable_tools and disable_tools "+ f"should not overlap, but got {intersection}.",+ )+# Initialize the underlying clientself._initialize_client()@@ -240,15 +282,19 @@ class MCPClient(BaseModel):else:return self._create_http_client()- async def list_tools(self) -> list[mcp.types.Tool]:- """List all available tools from the MCP server.+ async def list_tools(self) -> list[ToolBase]:+ """List available tools from the MCP server. If `enable_tools` and+ `disable_tools` are not `None` in the constructor, the returned+ tools will be filtered accordingly.Returns:- List of available MCP tools.+ `list[ToolBase]`:+ List of available MCP tools.Raises:RuntimeError: If not connected (for stateful connections)."""+ available_tools: list[mcp.types.Tool] = []if not self.is_stateful:# Stateless: create temporary sessionasync with self._get_client_gen() as cli:@@ -260,18 +306,31 @@ class MCPClient(BaseModel):await session.initialize()res = await session.list_tools()self._cached_tools = res.tools- return res.tools+ available_tools = res.toolselse:# Stateful: use existing sessionself._validate_connection()res = await self._session.list_tools()self._cached_tools = res.tools- return res.tools+ available_tools = res.tools++ # Filter tools based on enable_tools and disable_tools+ if self.enable_tools is not None:+ available_tools = [+ tool+ for tool in available_tools+ if tool.name in self.enable_tools+ ]+ if self.disable_tools is not None:+ available_tools = [+ _ for _ in available_tools if _.name not in self.disable_tools+ ]++ return [await self.get_tool(_.name) for _ in available_tools]async def get_tool(self,name: str,- execution_timeout: float | None = None,) -> MCPTool:"""Get a tool by name from the MCP server.@@ -281,8 +340,6 @@ class MCPClient(BaseModel):Args:name: The name of the tool function to get.- execution_timeout: The preset timeout in seconds for calling- the tool function.Returns:A tool object that implements ToolProtocol.@@ -317,7 +374,7 @@ class MCPClient(BaseModel):mcp_name=self.name,tool=target_tool,client_gen=self._get_client_gen,- timeout=execution_timeout,+ timeout=self.execution_timeout,)else:# Stateful: pass session@@ -326,7 +383,7 @@ class MCPClient(BaseModel):mcp_name=self.name,tool=target_tool,session=self._session,- timeout=execution_timeout,+ timeout=self.execution_timeout,)def _validate_connection(self) -> None:diff --git a/src/agentscope/model/_model_usage.py b/src/agentscope/model/_model_usage.pyindex 70e17be61..952cc6de4 100644--- a/src/agentscope/model/_model_usage.py+++ b/src/agentscope/model/_model_usage.py@@ -19,14 +19,14 @@ class ChatUsage(DictMixin):time: float"""The time used in seconds."""- type: Literal["chat"] = field(default_factory=lambda: "chat")- """The type of the usage, must be `chat`."""-cache_creation_input_tokens: int = field(default_factory=lambda: 0)"""The number of input tokens used to create the prompt cache."""cache_input_tokens: int = field(default_factory=lambda: 0)"""The number of input tokens read from the prompt cache."""+ type: Literal["chat"] = field(default_factory=lambda: "chat")+ """The type of the usage, must be `chat`."""+metadata: dict[str, Any] | None = field(default_factory=lambda: None)"""Optional metadata associated with the usage."""diff --git a/src/agentscope/tool/__init__.py b/src/agentscope/tool/__init__.pyindex 9c7355eb3..1782942d6 100644--- a/src/agentscope/tool/__init__.py+++ b/src/agentscope/tool/__init__.py@@ -5,7 +5,7 @@ from ._types import ToolChoice, Function, RegisteredToolfrom ._response import ToolResponse, ToolChunkfrom ._toolkit import Toolkitfrom ._base import ToolBase-from ._adapters import MCPTool+from ._adapters import MCPTool, FunctionToolfrom ._builtin import (ResetTools,Bash,@@ -21,6 +21,7 @@ from ._task import (TaskList,TaskCreate,)+from ._tool_group import ToolGroup__all__ = [# Basic tool related types and functions@@ -28,6 +29,8 @@ __all__ = ["Function","ToolBase","MCPTool",+ "FunctionTool",+ "ToolGroup","Toolkit","ToolChunk","ToolResponse",diff --git a/src/agentscope/tool/_adapters.py b/src/agentscope/tool/_adapters.pyindex eeba19efc..1c5664c0f 100644--- a/src/agentscope/tool/_adapters.py+++ b/src/agentscope/tool/_adapters.py@@ -26,7 +26,7 @@ from ..message import ()-class _FunctionTool(ToolBase):+class FunctionTool(ToolBase):"""Adapter to convert a Python function to ToolProtocol.This class wraps a regular Python function and makes it compatible withdiff --git a/src/agentscope/tool/_builtin/_meta.py b/src/agentscope/tool/_builtin/_meta.pyindex 29a3855fc..b3fccff41 100644--- a/src/agentscope/tool/_builtin/_meta.py+++ b/src/agentscope/tool/_builtin/_meta.py@@ -5,6 +5,7 @@ from typing import Anyfrom pydantic import Field, create_modelfrom jinja2 import Template+from .._tool_group import ToolGroupfrom ...permission import (PermissionContext,PermissionDecision,@@ -12,7 +13,6 @@ from ...permission import ()from .._response import ToolChunkfrom .._base import ToolBase-from .._types import ToolGroupfrom ...exception import DeveloperOrientedExceptionfrom ...message import TextBlockfrom ...state import AgentState@@ -47,7 +47,7 @@ class ResetTools(ToolBase):def __init__(self,- groups: dict[str, ToolGroup],+ groups: list[ToolGroup],response_template: str,) -> None:"""Initialize the meta tool with the current tool groups."""@@ -59,10 +59,10 @@ class ResetTools(ToolBase):"""Dynamically generate the input schema based on the currentavailable tool groups."""fields = {}- for group_name, group in self.groups.items():- if group_name == "basic":+ for group in self.groups:+ if group.name == "basic":continue- fields[group_name] = (+ fields[group.name] = (bool,Field(default=False,@@ -118,9 +118,7 @@ class ResetTools(ToolBase):_agent_state.tool_context.activated_groups.extend(to_activate)template = Template(self.response_template)- activated_groups = [- self.groups[_] for _ in to_activate if _ in self.groups- ]+ activated_groups = [_ for _ in self.groups if _.name in to_activate]return ToolChunk(content=[TextBlock(diff --git a/src/agentscope/tool/_builtin/_skill.py b/src/agentscope/tool/_builtin/_skill.pyindex bc3eef881..825a625bb 100644--- a/src/agentscope/tool/_builtin/_skill.py+++ b/src/agentscope/tool/_builtin/_skill.py@@ -2,6 +2,7 @@"""The builtin skill viewer tool."""from typing import Any, Callable, Awaitable+from ...exception import DeveloperOrientedExceptionfrom ...permission import (PermissionContext,PermissionDecision,@@ -11,6 +12,7 @@ from .._response import ToolChunkfrom .._base import ToolBasefrom ...skill import Skillfrom ...message import TextBlock, ToolResultState+from ...state import AgentStateclass SkillViewer(ToolBase):@@ -45,8 +47,9 @@ class SkillViewer(ToolBase):is_external_tool: bool = False"""The skill viewer is not an external tool."""- is_state_injected: bool = False- """The skill viewer doesn't require state injection."""+ is_state_injected: bool = True+ """The skill viewer require state injection to access the activated tool+ group."""is_read_only: bool = True"""The skill viewer is read-only."""@@ -80,7 +83,11 @@ class SkillViewer(ToolBase):message="The skill viewer is always allowed to be called.",)- async def __call__(self, skill: str) -> ToolChunk:+ async def __call__(+ self,+ skill: str,+ _agent_state: AgentState,+ ) -> ToolChunk:"""View the details of the skill with the given name.Args:@@ -91,8 +98,16 @@ class SkillViewer(ToolBase):`ToolChunk`:The details of the skill."""+ if not isinstance(_agent_state, AgentState):+ raise DeveloperOrientedException(+ f"Expected AgentState but got {type(_agent_state)} "+ "instead for the Skill viewer tool.",+ )- skills = await self._get_skills_method()+ # View the activated skills+ skills = await self._get_skills_method(+ _agent_state.tool_context.activated_groups,+ )target_skill = skills.get(skill)if not target_skill:return ToolChunk(diff --git a/src/agentscope/tool/_tool_group.py b/src/agentscope/tool/_tool_group.pynew file mode 100644index 000000000..e0c5e6dce--- /dev/null+++ b/src/agentscope/tool/_tool_group.py@@ -0,0 +1,107 @@+# -*- coding: utf-8 -*-+"""The tool group class."""+from typing import Literal++from ..mcp import MCPClient+from ._base import ToolBase+from ..skill import SkillLoaderBase, Skill, LocalSkillLoader+++class ToolGroup:+ """A group of related tools, mcps, and skills that an agent can activate,+ deactivate and use together. The tool group is activated by the meta tool+ `ResetTools`.++ In high-code scenarios, the tools argument accepts any child classes for+ ToolBase class, and the tool groups supports serialization.+ """++ name: Literal["basic"] | str+ """Note the "basic" group is special and represents the default tool group+ that will be always be activated for the agent."""++ description: str+ """A description of the tool group from an agent-oriented perspective,+ outlining its capabilities and the conditions under which it should be+ activated."""++ instructions: str | None+ """Instructions included in the meta tool's result upon activation of+ this tool group, guiding the agent on how to properly use the meta tool."""++ tools: list[ToolBase]+ """The tools in this group."""++ skills_or_loaders: list[Skill | SkillLoaderBase]+ """The skills in this group."""++ mcps: list[MCPClient]+ """The mcps in this group."""++ def __init__(+ self,+ name: Literal["basic"] | str,+ description: str | None = None,+ instructions: str | None = None,+ tools: list[ToolBase] | None = None,+ skills_or_loaders: list[str | Skill | SkillLoaderBase] | None = None,+ mcps: list[MCPClient] | None = None,+ ) -> None:+ """Initialize the tool group.++ Args:+ name (`Literal["basic"] | str):+ The name of the tool group.+ description (`str | None`):+ The description of the tool group.+ instructions (`str | None`, optional):+ Instructions included in the meta tool's result upon+ activation of this tool group, guiding the agent on how to+ properly use the meta tool.+ tools (`list[ToolBase] | None`, optional):+ The tools in this group.+ skills_or_loaders (`list[str | Skill | SkillLoaderBase] | None`, \+ optional):+ The skill paths, data, and loaders to access skills in this+ group.+ mcps (`list[MCPClient] | None`, optional):+ The mcps in this group.+ """+ if name != "basic" and description is None:+ raise ValueError(+ f"The tool group description is required for tool group "+ f"'{name}' (Only the 'basic' tool group can have an optional "+ f"description).",+ )++ self.name = name+ self.description = description or ""+ self.instructions = instructions+ self.tools = tools or []+ self.mcps = mcps or []++ # Skill+ self.skills_or_loaders = []+ for _ in skills_or_loaders or []:+ if isinstance(_, str):+ self.skills_or_loaders.append(LocalSkillLoader(directory=_))++ elif isinstance(_, (Skill, SkillLoaderBase)):+ self.skills_or_loaders.append(_)++ else:+ raise TypeError(+ f"Invalid skill or loader: {_}. Must be a skill, "+ f"skill loader, or directory path.",+ )++ async def list_skills(self) -> list[Skill]:+ """List all the skills in this tool group."""+ skills = []+ for skill_or_loader in self.skills_or_loaders:+ if isinstance(skill_or_loader, Skill):+ skills.append(skill_or_loader)+ elif isinstance(skill_or_loader, SkillLoaderBase):+ skills.extend(await skill_or_loader.list_skills())++ return skillsdiff --git a/src/agentscope/tool/_toolkit.py b/src/agentscope/tool/_toolkit.pyindex 1a5c1d813..993617442 100644--- a/src/agentscope/tool/_toolkit.py+++ b/src/agentscope/tool/_toolkit.py@@ -2,16 +2,11 @@"""The toolkit class for tool calls in AgentScope."""import asyncioimport inspect-import warningsfrom collections import OrderedDict-from copy import deepcopyfrom typing import (AsyncGenerator,- Any,Type,Generator,- Callable,- Coroutine,)import mcp@@ -24,10 +19,9 @@ from pydantic import (from ._builtin import ResetTools, SkillViewerfrom ._base import ToolBase-from ._adapters import _FunctionToolfrom ._response import ToolResponse, ToolChunk-from ..skill import SkillLoaderBase, LocalSkillLoader, Skill-from ._types import ToolGroup, RegisteredTool+from ..skill import SkillLoaderBase, Skill+from ._types import RegisteredToolfrom .._utils._common import _json_loads_with_repairfrom ..exception import (DeveloperOrientedException,@@ -40,6 +34,7 @@ from ..message import (TextBlock,ToolResultState,)+from ._tool_group import ToolGroupfrom .._logging import loggerfrom ..state import AgentState@@ -57,8 +52,8 @@ Skills are a collection of instructions, scripts, and resources to extend your c**IMPORTANT**: Skills are NOT tools, and you cannot call a skill directly. To use a skill, you MUST use the `{{ skill_viewer }}` tool to read the skill's full instructions, and then follow those instructions to use the tools and resources provided by the skill.-# Available Skills:-{% for skill in skills %}<skill>+# Available Skills:{% for skill in skills %}+<skill><name>{{ skill.name }}</name><description>{{ skill.description }}</description><dir>{{ skill.dir }}</dir>@@ -89,253 +84,94 @@ class Toolkit:- Provide prompt for the registered skills to the agent."""- def _get_meta_tool_schema(self) -> Type[BaseModel]:- """Get the meta tool schema based on the current tool groups."""- fields = {}- for group_name, group in self.groups.items():- if group_name == "basic":- continue- fields[group_name] = (- bool,- Field(- default=False,- description=group.description,- ),- )- return create_model("_DynamicModel", **fields)-def __init__(self,tools: list[ToolBase] | None = None,- skills: list[str | SkillLoaderBase] | None = None,+ skills_or_loaders: list[str | Skill | SkillLoaderBase] | None = None,+ mcps: list[MCPClient] | None = None,+ tool_groups: list[ToolGroup] | None = None,meta_tool_response_template: str = DEFAULT_META_TOOL_RESPONSE_TEMPLATE,- skill_viewer_enabled: bool = True,skill_instruction_template: str = DEFAULT_SKILL_INSTRUCTION,) -> None:"""Initialize the toolkit.Args:- tools (`list[ToolProtocol] | None`, optional):- The tool objects that implement the ToolProtocol interface.- skills (`list[str] | None`, optional):- The agent skill directories to be registered.+ tools (`list[ToolBase] | None`, optional):+ The tool objects that belong to the "basic" tool group.+ skills_or_loaders (`list[str | Skill | SkillLoaderBase] | None`, \+ optional):+ The agent skill directories to be registered in the "basic"+ tool group.+ mcps (`list[MCPClient] | None`, optional):+ The mcp clients to be registered in the "basic" tool group.+ tool_groups (`list[ToolGroup] | None`, optional):+ The tool groups to be registered.meta_tool_response_template (`str`, optional):The template for meta tool responses.- skill_viewer_enabled (`bool`, defaults to `True`):- Whether enable the built-in skill viewer tool function.skill_instruction_template (`str`):A Jinja2 template for generating the agent skill instruction."""- super().__init__()-- self.tools: dict[str, RegisteredTool] = OrderedDict()- self.groups: dict[str, ToolGroup] = {}- self.skills: list[SkillLoaderBase] = []-- self._middlewares: list = [] # Store registered middlewares-- # ================================================- # Handle the initial tools- # ================================================- if tools:- for tool in tools:- # TODO: handle the name conflict here- self.tools[tool.name] = RegisteredTool(tool=tool)-- # ================================================- # Handle the initial skills- # ================================================- if skills:- for skill in skills:- if isinstance(skill, str):- self.skills.append(LocalSkillLoader(skill))- elif isinstance(skill, SkillLoaderBase):- self.skills.append(skill)- else:- raise TypeError(- f"Invalid skill type: {type(skill)}. Skills should "- "be either a directory path string or an instance "- "of SkillLoaderBase.",++ if tool_groups is not None and any(+ _.name == "basic" for _ in tool_groups+ ):+ raise ValueError(+ "The 'basic' tool group is reserved for the default tool "+ "group. Don't include 'basic' in the tool_groups argument "+ "when you also provide tools, skills or mcps in the "+ "constructor.",+ )++ self.tool_groups = [+ ToolGroup(+ name="basic",+ tools=tools or [],+ skills_or_loaders=skills_or_loaders or [],+ mcps=mcps or [],+ ),+ ] + (tool_groups or [])++ # Check name conflict for tool groups+ if len(set(_.name for _ in self.tool_groups)) != len(+ self.tool_groups,+ ):+ raise ValueError(+ "Tool groups must not contain duplicate tool groups.",+ )++ # The stateful MCP clients should be initialized already+ for group in self.tool_groups:+ for client in group.mcps:+ if client.is_stateful and not client.is_connected:+ raise ValueError(+ f"The MCP client '{client.name}' is stateful, but "+ f"not connected.",)self.meta_tool_response_template = meta_tool_response_template-self.skill_instruction_template = skill_instruction_template- self.skill_viewer_enabled = skill_viewer_enabledself.builtin_meta_tool = RegisteredTool(tool=ResetTools(# An inference value for groups so that it can generate the# corresponding input schema.- groups=self.groups,+ groups=self.tool_groups,response_template=meta_tool_response_template,),)self.builtin_skill_viewer = RegisteredTool(tool=SkillViewer(- get_skills_method=self._get_all_skills,+ get_skills_method=self._get_available_skills,),)- def create_tool_group(- self,- group_name: str,- description: str,- instructions: str | None = None,- tools: list[ToolBase] | None = None,- ) -> None:- """Create a tool group to organize tool functions-- Args:- group_name (`str`):- The name of the tool group.- description (`str`):- The description of the tool group.- instructions (`str | None`, optional):- The instructions about how to use the tool functions in this- group.- tools (`list[ToolProtocol] | None`, optional):- The tool objects that implement the ToolProtocol interface to- be added into this group. Note that these tools will also be- added to the toolkit if they are not already in the toolkit.- """- if group_name in self.groups or group_name == "basic":- raise ValueError(- f"Tool group '{group_name}' is already registered in the "- "toolkit.",- )-- self.groups[group_name] = ToolGroup(- name=group_name,- description=description,- instructions=instructions,- )-- if isinstance(tools, list) and all(- isinstance(_, ToolBase) for _ in tools- ):- for tool in tools:- registered = RegisteredTool(- tool=tool,- group=group_name,- )- self.tools[tool.name] = registered-- def remove_tool_groups(self, group_names: str | list[str]) -> None:- """Remove tool functions from the toolkit by their group names.-- Args:- group_names (`str | list[str]`):- The group names to be removed from the toolkit.- """- if isinstance(group_names, str):- group_names = [group_names]-- if not isinstance(group_names, list) or not all(- isinstance(_, str) for _ in group_names- ):- raise TypeError(- f"The group_names must be a list of strings, "- f"but got {type(group_names)}.",- )-- if "basic" in group_names:- raise ValueError(- "Cannot remove the default 'basic' tool group.",- )-- for group_name in group_names:- self.groups.pop(group_name, None)-- # Remove the tool functions in the given groups- tool_names = deepcopy(list(self.tools.keys()))- for tool_name in tool_names:- if self.tools[tool_name].group in group_names:- self.tools.pop(tool_name)-- def register_function(- self,- func: Callable,- group: str = "basic",- name: str | None = None,- description: str | None = None,- is_concurrency_safe: bool = True,- is_read_only: bool = False,- ) -> None:- """Register a Python function as a tool in the toolkit.-- This method wraps a regular Python function into a FunctionTool and- registers it to the toolkit.-- Args:- func (`Callable`):- A Python function to be registered as a tool.- group (`str`, defaults to `"basic"`):- The belonging group of the tool. Tools in "basic" group are- always included in the JSON schema, while others are only- included when their group is active.- name (`str | None`, optional):- Custom tool name. If None, uses the function name.- description (`str | None`, optional):- Custom tool description. If None, extracts from docstring.- is_concurrency_safe (`bool`, defaults to `True`):- Whether this tool is safe to call concurrently.- is_read_only (`bool`, defaults to `False`):- Whether this tool only reads data without side effects.- """- # Wrap the function into a FunctionTool- tool = _FunctionTool(- func,- name=name,- description=description,- is_concurrency_safe=is_concurrency_safe,- is_read_only=is_read_only,- )-- # Check if the group exists- groups = ["basic"] + list(self.groups.keys())- if group not in groups:- raise ValueError(- f"Tool group '{group}' does not exist. Available groups: "- f"{groups}. You can create a new group by calling "- "`toolkit.create_tool_group()` method.",- )-- # Register the tool- registered = RegisteredTool(- tool=tool,- group=group,- )- self.tools[tool.name] = registered-- def unregister_tool(- self,- tool_name: str,- allow_not_exist: bool = True,- ) -> None:- """Remove tool function from the toolkit by its name.-- Args:- tool_name (`str`):- The name of the tool function to be removed.- allow_not_exist (`bool`):- Allow the tool function to not exist when removing.- """-- if tool_name not in self.tools and not allow_not_exist:- raise ValueError(- f"Tool function '{tool_name}' does not exist in the "- "toolkit.",- )-- self.tools.pop(tool_name, None)-- def get_function_schemas(+ async def get_tool_schemas(self,groups: list[str] | None = None,) -> list[dict]:- """Get the function JSON schemas.+ """Get the JSON schemas of the currently available tool functions+ based on the given activated tool groups... note:: The preset keyword arguments is removed from the JSONschema, and the extended model is applied if it is set.@@ -377,75 +213,13 @@ class Toolkit:"""function_schemas = []- for tool in self._get_available_tools(groups).values():- function_schemas.append(tool.get_function_schema())+ # Get all available tools+ tools_dict = await self._get_available_tools(groups)+ for tool in tools_dict.values():+ function_schemas.append(tool.get_tool_schema())return function_schemas- def set_extended_model(- self,- func_name: str,- model: Type[BaseModel] | None,- ) -> None:- """Set the extended model for a tool function, so that the original- JSON schema will be extended.-- Args:- func_name (`str`):- The name of the tool function.- model (`Union[Type[BaseModel], None]`):- The extended model to be set.- """- if model is not None and not issubclass(model, BaseModel):- raise TypeError(- "The extended model must be a child class of pydantic "- f"BaseModel, but got {type(model)}.",- )-- if func_name in self.tools:- self.tools[func_name].extended_model = model-- else:- raise ValueError(- f"Tool function '{func_name}' not found in the toolkit.",- )-- async def remove_mcp_clients(- self,- client_names: list[str],- ) -> None:- """Remove tool functions from the MCP clients by their names.-- Args:- client_names (`list[str]`):- The names of the MCP client, which used to initialize the- client instance.- """- if isinstance(client_names, str):- client_names = [client_names]-- if isinstance(client_names, list) and not all(- isinstance(_, str) for _ in client_names- ):- raise TypeError(- f"The client_names must be a list of strings, "- f"but got {type(client_names)}.",- )-- to_removed = []- func_names = deepcopy(list(self.tools.keys()))- for func_name in func_names:- if self.tools[func_name].tool.mcp_name in client_names:- self.tools.pop(func_name)- to_removed.append(func_name)-- logger.info(- "Removed %d tool functions from %d MCP: %s",- len(to_removed),- len(client_names),- ", ".join(to_removed),- )-async def call_tool(self,tool_call: ToolCallBlock,@@ -471,14 +245,17 @@ class Toolkit:tool_response = ToolResponse(id=tool_call.id)# Check- available_tools = self._get_available_tools(+ available_tools = await self._get_available_tools(state.tool_context.activated_groups,)if tool_call.name not in available_tools:+ all_tools = await self._get_available_tools(+ groups=[_.name for _ in self.tool_groups],+ )# Not activate- if tool_call.name in self.tools:- group_name = self.tools[tool_call.name].group+ if tool_call.name in all_tools:+ group_name = all_tools[tool_call.name].groupchunk = ToolChunk(content=[TextBlock(@@ -608,135 +385,41 @@ class Toolkit:# Finally, yield the complete tool responseyield tool_response- async def register_mcp(+ async def _get_available_skills(self,- mcp_client: MCPClient,- group_name: str = "basic",- enable_funcs: list[str] | None = None,- disable_funcs: list[str] | None = None,- ) -> None:- """Register tools from an MCP client.-- .. note:: When registering tools from an MCP client, the tool will- be renamed by template `mcp__{mcp_name}__{tool_name}` to avoid- name conflicts.+ groups: list[str] | None = None,+ ) -> dict[str, Skill]:+ """A unified method to collect all skills from the registered skill+ loaders.Args:- mcp_client (`MCPClient`):- The MCP client instance to connect to the MCP server.- group_name (`str`, defaults to `"basic"`):- The group name that the tool functions will be added to.- enable_funcs (`list[str] | None`, optional):- The functions to be added into the toolkit. If `None`, all- tool functions within the MCP servers will be added.- disable_funcs (`list[str] | None`, optional):- The functions that will be filtered out. If `None`, no- tool functions will be filtered out.- """- if not isinstance(mcp_client, MCPClient):- raise ValueError(- f"The 'mcp_client' should be an instance of "- f"'MCPClient' but got {type(mcp_client)}.",- )-- if mcp_client.is_stateful and not mcp_client.is_connected:- raise RuntimeError(- "The MCP client is not connected to the server. Use the "- "`connect()` method first.",- )-- # Check arguments for enable_funcs and disable_funcs- if enable_funcs is not None:- assert isinstance(enable_funcs, list) and all(- isinstance(_, str) for _ in enable_funcs- ), (- "Enable functions should be a list of strings, but got "- f"{enable_funcs}."- )-- if disable_funcs is not None:- assert isinstance(disable_funcs, list) and all(- isinstance(_, str) for _ in disable_funcs- ), (- "Disable functions should be a list of strings, but got "- f"{disable_funcs}."- )-- if enable_funcs is not None and disable_funcs is not None:- intersection = set(enable_funcs).intersection(- set(disable_funcs),- )- assert len(intersection) == 0, (- f"The functions in enable_funcs and disable_funcs "- f"should not overlap, but got {intersection}."- )+ groups (`list[str] | None`, optional):+ A list of group names to filter the skill loaders. The "basic"+ group will always be included regardless of the filter. If not+ provided, only the "basic" group will be included.- tool_names = []- for mcp_tool in await mcp_client.list_tools():- # Skip the functions that are not in the enable_funcs if- # enable_funcs is not None- if enable_funcs is not None and mcp_tool.name not in enable_funcs:- continue+ Returns:+ `dict[str, Skill]`+ A dictionary of skill name and their corresponding Skill+ objects.+ """+ groups_filter = ["basic"] + (groups or [])- # Skip the disabled functions- if disable_funcs is not None and mcp_tool.name in disable_funcs:+ skills = OrderedDict()+ for group in self.tool_groups:+ if group.name not in groups_filter:continue- tool_names.append(mcp_tool.name)-- # Obtain callable function object- tool_obj = await mcp_client.get_tool(- name=mcp_tool.name,- )-- # Register the tool function to the toolkit- registered = RegisteredTool(- tool=tool_obj,- group=group_name,- original_name=mcp_tool.name,- )-- self.tools[tool_obj.name] = registered-- logger.info(- "Registered %d tool functions from MCP: %s.",- len(tool_names),- ", ".join(tool_names),- )-- def clear(self) -> None:- """Clear the toolkit, removing all tool functions and groups."""- self.skills.clear()- self.tools.clear()- self.groups.clear()-- async def _get_all_skills(self) -> dict[str, Skill]:- """A unified method to collect all skills from the registered skill- loaders. Including the name conflict handling for skills with the- same name.- """- skills = OrderedDict()- for loader in self.skills:- new_skills = await loader.list_skills()- # Handle duplicated skill names- for skill in new_skills:- if skill.name not in skills:- skills[skill.name] = skill- else:- # Rename the skill with a suffix to avoid duplication- suffix = 1- while f"{skill.name}_{suffix}" in skills:- suffix += 1- new_name = f"{skill.name}_{suffix}"- warnings.warn(- f"Duplicate skill name '{skill.name}' found in "- f"directory '{skill.dir}'. "- f"Renaming it to '{new_name}'.",+ for skill in await group.list_skills():+ if skill.name in skills:+ logger.warning(+ "Duplicate skill name '%s' found in group '%s', "+ "overwriting it.",+ skill.name,+ group.name,)- # Avoid affect the skill loader cache- copied_skill = deepcopy(skill)- copied_skill.name = new_name- skills[new_name] = copied_skill+ skills[skill.name] = skill+return skillsasync def get_skill_instructions(self) -> str | None:@@ -754,10 +437,7 @@ class Toolkit:The combined prompt for all registered agent skills, or Noneif no skill is registered."""- if len(self.skills) == 0:- return None-- skills = await self._get_all_skills()+ skills = await self._get_available_skills()# If no skills were collected, return Noneif len(skills) == 0:@@ -771,105 +451,7 @@ class Toolkit:skill_viewer=self.builtin_skill_viewer.tool.name,)- def register_middleware(- self,- middleware: Callable[- ...,- Coroutine[Any, Any, AsyncGenerator[ToolResponse, None]]- | AsyncGenerator[ToolResponse, None],- ],- ) -> None:- """Register an onion-style middleware for the `call_tool_function`,- which will wrap around the `call_tool_function` method, allowing- pre-processing, post-processing, or even skipping the execution of- the tool function.-- The middleware follows an onion model, where each registered- middleware wraps around the previous one, forming layers. The- middleware can:-- - Perform pre-processing before calling the tool function- - Intercept and modify each ToolResponse chunk- - Perform post-processing after the tool function completes- - Skip the tool function execution entirely-- The middleware function should accept a ``kwargs`` dict as the first- parameter and ``next_handler`` as the second parameter. The ``kwargs``- dict currently contains:-- - ``tool_call`` (`ToolCallBlock`): The tool call request-- When calling ``next_handler``, pass ``**kwargs`` to unpack the dict.-- Example:- .. code-block:: python-- # Simple direct consumption style (recommended)- async def my_middleware(- kwargs: dict,- next_handler: Callable,- ) -> AsyncGenerator[ToolResponse, None]:- # Access the tool call- tool_call = kwargs["tool_call"]-- # Pre-processing- print(f"Calling tool: {tool_call['name']}")-- # Call next handler with **kwargs- async for response in await next_handler(**kwargs):- # Intercept and modify response if needed- yield response-- # Post-processing after tool completes- print(f"Tool {tool_call['name']} completed")-- toolkit.register_middleware(my_middleware)-- .. code-block:: python-- # Alternative: Skip execution based on conditions- async def my_middleware(- kwargs: dict,- next_handler: Callable,- ) -> AsyncGenerator[ToolResponse, None]:- tool_call = kwargs["tool_call"]-- # Pre-processing- if not is_authorized(tool_call):- # Skip execution and return error directly- yield ToolResponse(- content=[- TextBlock(- type="text",- text="Unauthorized",- ),- ],- )- return-- # Call next handler with **kwargs- async for response in await next_handler(**kwargs):- yield response-- toolkit.register_middleware(my_middleware)-- Args:- middleware (`Callable[..., Coroutine[Any, Any, \-AsyncGenerator[ToolResponse, None]] | AsyncGenerator[ToolResponse, None]]`):- The middleware function that accepts ``kwargs`` (dict) and- ``next_handler`` (Callable), and returns a coroutine that- yields AsyncGenerator of ToolResponse objects. The ``kwargs``- dict currently includes ``tool_call`` (ToolCallBlock), and may- include additional context in future versions.-- .. note:: Tracing is now handled by ``TracingMiddleware`` at the- agent level rather than a ``@trace_toolkit`` decorator.- """- # Simply append the middleware to the list- # The @apply_middlewares decorator will handle the execution- self._middlewares.append(middleware)-- def _get_available_tools(+ async def _get_available_tools(self,groups: list[str] | None,) -> dict[str, RegisteredTool]:@@ -889,29 +471,58 @@ AsyncGenerator[ToolResponse, None]] | AsyncGenerator[ToolResponse, None]]`):"""available_tools = {}+ # Built-in skill viewers+ skills = await self._get_available_skills()+ if len(skills):+ available_tools[+ self.builtin_skill_viewer.tool.name+ ] = self.builtin_skill_viewer+# Builtin meta tool is only included when there is at least one tool# group- if len(self.groups) > 0:+ if (+ len(self.tool_groups) == 1+ and self.tool_groups[0].name != "basic"+ or len(self.tool_groups) > 1+ ):available_tools[self.builtin_meta_tool.tool.name] = self.builtin_meta_tool- # Builtin skill viewer is included when enabled and at least on skill- # is registered- if self.skill_viewer_enabled and len(self.skills) > 0:- available_tools[- self.builtin_skill_viewer.tool.name- ] = self.builtin_skill_viewer-# The tools in the activated groups and the "basic" group are includedgroups_filter = ["basic"] + (groups or [])- for tool_name, tool in self.tools.items():- if tool.group in groups_filter:- available_tools[tool_name] = tool+ for group in self.tool_groups:+ if group.name not in groups_filter:+ continue++ cache_tools = []+ # Python tools+ for tool in group.tools:+ cache_tools.append(tool)++ # MCP tools+ for client in group.mcps:+ tools = await client.list_tools()+ cache_tools.extend(tools)++ # Append cached tools into the available tools and solve the name+ # conflict+ for tool in cache_tools:+ if tool.name in available_tools:+ logger.warning(+ "Duplicate tool name '%s' found in group '%s', "+ "overwriting it.",+ tool.name,+ group.name,+ )+ available_tools[tool.name] = RegisteredTool(+ tool=tool,+ group=group.name,+ )return available_tools- def check_tool_available(+ async def check_tool_available(self,tool_name: str,activated_groups: list[str],@@ -931,13 +542,14 @@ AsyncGenerator[ToolResponse, None]] | AsyncGenerator[ToolResponse, None]]`):object. Otherwise, raise the agent-oriented exception with theerror message."""- if tool_name not in self.tools:+ tools = await self._get_available_tools(activated_groups)+ if tool_name not in tools:raise ToolNotFoundError(f"ToolNotFoundError: The tool named '{tool_name}' doesn't "f"exist.",)- group_name = self.tools[tool_name].group+ group_name = tools[tool_name].groupif group_name != "basic" and group_name not in activated_groups:raise ToolGroupInactiveError(f"ToolGroupInactiveError: The tool '{tool_name}' in group "@@ -946,4 +558,42 @@ AsyncGenerator[ToolResponse, None]] | AsyncGenerator[ToolResponse, None]]`):f"'{self.builtin_meta_tool.tool.name}' tool.",)- return self.tools[tool_name].tool+ return tools[tool_name].tool++ async def get_tool(self, name: str) -> ToolBase | None:+ """Get tool instance by its name.++ Args:+ name (`str`):+ The name of the tool to be checked.++ Returns:+ `ToolBase | None`:+ The tool instance, or `None` if no tool is found.+ """+ tools = await self._get_available_tools(+ [_.name for _ in self.tool_groups],+ )+ registered_tool = tools.get(name, None)+ if registered_tool is None:+ return None+ return registered_tool.tool++ def _get_meta_tool_schema(self) -> Type[BaseModel]:+ """Get the meta tool schema based on the current tool groups."""+ fields = {}+ for group in self.tool_groups:+ if group.name == "basic":+ continue+ fields[group.name] = (+ bool,+ Field(+ default=False,+ description=group.description,+ ),+ )+ return create_model("_DynamicModel", **fields)++ def clear(self) -> None:+ """Clear the registered tools, skills and MCPs."""+ self.tool_groups.clear()diff --git a/src/agentscope/tool/_types.py b/src/agentscope/tool/_types.pyindex b969e2973..0823187b8 100644--- a/src/agentscope/tool/_types.py+++ b/src/agentscope/tool/_types.py@@ -53,7 +53,7 @@ class RegisteredTool:f"Invalid input_schema: {self.tool.input_schema}. ",)- def get_function_schema(+ def get_tool_schema(self,extended_model: Type[BaseModel] | None = None,) -> dict:@@ -153,22 +153,6 @@ class RegisteredTool:return function_schema-@dataclass-class ToolGroup:- """The tool group abstraction that provides a higher level of organization- for tools."""-- name: str- """The group name, which will be used in the reset function as the group- identifier."""- description: str- """The description of the tool group to tell the agent what the tool- group is about."""- instructions: str | None = None- """The instructions that will be contained when this tool group is- activated."""--# The function types that can be registered as tools in AgentScope.Function: TypeAlias = (# Sync functiondiff --git a/src/agentscope/workspace/__init__.py b/src/agentscope/workspace/__init__.pyindex ccbe4592d..39f0ba19c 100644--- a/src/agentscope/workspace/__init__.py+++ b/src/agentscope/workspace/__init__.py@@ -7,6 +7,7 @@ from pydantic import Fieldfrom ._base import WorkspaceBasefrom ._local_workspace import LocalWorkspace+from ._offload_protocol import OffloaderAnyWorkspace = Annotated[Union[LocalWorkspace], Field(discriminator="type")]@@ -14,4 +15,5 @@ __all__ = ["AnyWorkspace","WorkspaceBase","LocalWorkspace",+ "Offloader",]diff --git a/src/agentscope/workspace/_base.py b/src/agentscope/workspace/_base.pyindex d1ce4a8a9..dab8de0d2 100644--- a/src/agentscope/workspace/_base.py+++ b/src/agentscope/workspace/_base.py@@ -16,7 +16,7 @@ class WorkspaceBase(BaseModel):"""Abstract base class representing the execution environment of an agent.Inherits from ``BaseModel`` so that each workspace instance is directly- serialisable via ``model_dump()`` / ``model_validate()``. The ``type``+ serializable via ``model_dump()`` / ``model_validate()``. The ``type``discriminator field enables the manager to reconstruct the correctsubclass from ``WorkspaceRecord.data`` without a separate factory.diff --git a/src/agentscope/workspace/_local_workspace.py b/src/agentscope/workspace/_local_workspace.pyindex 88fa36a23..2f9c73d86 100644--- a/src/agentscope/workspace/_local_workspace.py+++ b/src/agentscope/workspace/_local_workspace.py@@ -519,6 +519,17 @@ class LocalWorkspace(WorkspaceBase):f"tool_result-{tool_result.id}.txt",)+ # Avoid filename conflict+ index = 1+ while os.path.exists(path):+ path = os.path.join(+ self.workdir,+ "sessions",+ session_id,+ f"tool_result-{tool_result.id}({index}).txt",+ )+ index += 1+res_strs = []if isinstance(tool_result.output, str):res_strs.append(tool_result.output)diff --git a/src/agentscope/workspace/_offload_protocol.py b/src/agentscope/workspace/_offload_protocol.pynew file mode 100644index 000000000..f178962f8--- /dev/null+++ b/src/agentscope/workspace/_offload_protocol.py@@ -0,0 +1,47 @@+# -*- coding: utf-8 -*-+"""The offload protocol."""+from typing import Protocol, Any++from ..message import Msg, ToolResultBlock+++class Offloader(Protocol):+ """The offloader protocol."""++ async def offload_context(+ self,+ session_id: str,+ msgs: list[Msg],+ **kwargs: Any,+ ) -> str:+ """Offload compressed context to workspace-accessible storage.++ Args:+ session_id (`str`):+ The session id.+ msgs (`list[Msg]`):+ The messages to offload.++ Returns:+ `str`:+ The offloaded context reference.+ """++ async def offload_tool_result(+ self,+ session_id: str,+ tool_result: ToolResultBlock,+ **kwargs: Any,+ ) -> str:+ """Offload a tool result to workspace-accessible storage.++ Args:+ session_id (`str`):+ The session id.+ tool_result (`ToolResultBlock`):+ The tool result.++ Returns:+ `str`:+ The offloaded context reference.+ """diff --git a/tests/agent_basic_test.py b/tests/agent_basic_test.pyindex cd4e94173..59ed5b462 100644--- a/tests/agent_basic_test.py+++ b/tests/agent_basic_test.py@@ -1,5 +1,4 @@# -*- coding: utf-8 -*--# pylint: disable=redefined-builtin"""The basic test of the agent class."""from typing import Anyfrom unittest.async_case import IsolatedAsyncioTestCase@@ -12,7 +11,6 @@ from agentscope.tool import (ToolBase,Toolkit,ToolChunk,- RegisteredTool,)from agentscope.permission import (PermissionDecision,@@ -51,6 +49,7 @@ class MockSequentialTool(ToolBase):message="Mock tool always allows",)+ # pylint: disable=redefined-builtinasync def __call__(self, input: str, **kwargs: Any) -> ToolChunk:"""Execute the tool."""return ToolChunk(@@ -87,6 +86,7 @@ class MockConcurrentTool(ToolBase):message="Mock tool always allows",)+ # pylint: disable=redefined-builtinasync def __call__(self, input: str, **kwargs: Any) -> ToolChunk:"""Execute the tool."""return ToolChunk(@@ -536,10 +536,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):"""# Register sequential toolsseq_tool = MockSequentialTool()- self.agent.toolkit.tools[seq_tool.name] = RegisteredTool(- tool=seq_tool,- group="basic",- )+ self.agent.toolkit = Toolkit(tools=[seq_tool])# Create tool call IDstool_call_id_1 = "tool_call_1"@@ -803,9 +800,8 @@ class AgentBasicTest(IsolatedAsyncioTestCase):# Register concurrent toolsconc_tool = MockConcurrentTool()- self.agent.toolkit.tools[conc_tool.name] = RegisteredTool(- tool=conc_tool,- group="basic",+ self.agent.toolkit = Toolkit(+ tools=[conc_tool],)# Create tool call IDs@@ -1042,14 +1038,8 @@ class AgentBasicTest(IsolatedAsyncioTestCase):seq_tool = MockSequentialTool()conc_tool = MockConcurrentTool()- self.agent.toolkit.tools[seq_tool.name] = RegisteredTool(- tool=seq_tool,- group="basic",- )-- self.agent.toolkit.tools[conc_tool.name] = RegisteredTool(- tool=conc_tool,- group="basic",+ self.agent.toolkit = Toolkit(+ tools=[seq_tool, conc_tool],)# Create tool call IDsdiff --git a/tests/compress_context_test.py b/tests/compress_context_test.pyindex 138329877..b1bb16692 100644--- a/tests/compress_context_test.py+++ b/tests/compress_context_test.py@@ -619,6 +619,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):# Context to Preserve5</system-info>""",)+self.assertListEqual([_.model_dump() for _ in agent.state.context],[diff --git a/tests/hitl_external_execution_test.py b/tests/hitl_external_execution_test.pyindex 80ec0dbfd..e4627bda2 100644--- a/tests/hitl_external_execution_test.py+++ b/tests/hitl_external_execution_test.py@@ -12,7 +12,6 @@ from agentscope.tool import (ToolBase,Toolkit,ToolChunk,- RegisteredTool,)from agentscope.permission import (PermissionDecision,@@ -271,9 +270,8 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):"""# Register external toolext_tool = MockExternalSequentialTool()- self.agent.toolkit.tools[ext_tool.name] = RegisteredTool(- tool=ext_tool,- group="basic",+ self.agent.toolkit = Toolkit(+ tools=[ext_tool],)# Set up mock response with tool call (no final text response)@@ -481,9 +479,8 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):"""# Register external sequential toolext_tool = MockExternalSequentialTool()- self.agent.toolkit.tools[ext_tool.name] = RegisteredTool(- tool=ext_tool,- group="basic",+ self.agent.toolkit = Toolkit(+ tools=[ext_tool],)# Set up mock response with multiple tool calls@@ -780,9 +777,8 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):"""# Register external concurrent toolext_tool = MockExternalConcurrentTool()- self.agent.toolkit.tools[ext_tool.name] = RegisteredTool(- tool=ext_tool,- group="basic",+ self.agent.toolkit = Toolkit(+ tools=[ext_tool],)# Set up mock response with multiple tool calls@@ -1079,9 +1075,8 @@ class AgentExternalExecutionTest(IsolatedAsyncioTestCase):4. Continue reasoning only after both results are applied"""ext_tool = MockExternalConcurrentTool()- self.agent.toolkit.tools[ext_tool.name] = RegisteredTool(- tool=ext_tool,- group="basic",+ self.agent.toolkit = Toolkit(+ tools=[ext_tool],)self.model.set_responses(diff --git a/tests/hitl_user_confirmation_test.py b/tests/hitl_user_confirmation_test.pyindex 94ed0f192..ce0027369 100644--- a/tests/hitl_user_confirmation_test.py+++ b/tests/hitl_user_confirmation_test.py@@ -11,7 +11,6 @@ from agentscope.tool import (ToolBase,Toolkit,ToolChunk,- RegisteredTool,)from agentscope.permission import (PermissionDecision,@@ -246,9 +245,8 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):"""# Register user confirm toolconfirm_tool = MockUserConfirmSequentialTool()- self.agent.toolkit.tools[confirm_tool.name] = RegisteredTool(- tool=confirm_tool,- group="basic",+ self.agent.toolkit = Toolkit(+ tools=[confirm_tool],)# Set up mock response with tool call (no final text response)@@ -483,9 +481,8 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):"""# Register user confirm sequential toolconfirm_tool = MockUserConfirmSequentialTool()- self.agent.toolkit.tools[confirm_tool.name] = RegisteredTool(- tool=confirm_tool,- group="basic",+ self.agent.toolkit = Toolkit(+ tools=[confirm_tool],)# Set up mock response with multiple tool calls@@ -830,9 +827,8 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):"""# Register user confirm concurrent toolconfirm_tool = MockUserConfirmConcurrentTool()- self.agent.toolkit.tools[confirm_tool.name] = RegisteredTool(- tool=confirm_tool,- group="basic",+ self.agent.toolkit = Toolkit(+ tools=[confirm_tool],)# Set up mock response with multiple tool calls@@ -1180,9 +1176,8 @@ class AgentUserConfirmationTest(IsolatedAsyncioTestCase):4. Execute both tools and continue reasoning after both complete"""confirm_tool = MockUserConfirmConcurrentTool()- self.agent.toolkit.tools[confirm_tool.name] = RegisteredTool(- tool=confirm_tool,- group="basic",+ self.agent.toolkit = Toolkit(+ tools=[confirm_tool],)self.model.set_responses(diff --git a/tests/mcp_sse_client_test.py b/tests/mcp_sse_client_test.pyindex 9d3970d87..f7df7106a 100644--- a/tests/mcp_sse_client_test.py+++ b/tests/mcp_sse_client_test.py@@ -144,7 +144,8 @@ class SseMCPClientTest(IsolatedAsyncioTestCase):# Register MCPTool via Toolkit constructortoolkit_with_mcp = Toolkit(tools=[mcp_tool_1])- schemas = toolkit_with_mcp.get_function_schemas()+ schemas = await toolkit_with_mcp.get_tool_schemas()+self.assertListEqual(schemas,self.schemas,@@ -180,12 +181,12 @@ class SseMCPClientTest(IsolatedAsyncioTestCase):)self.toolkit.clear()- self.assertDictEqual(self.toolkit.tools, {})+ self.assertListEqual(self.toolkit.tool_groups, [])# Try to add the mcp client- await self.toolkit.register_mcp(stateless_client)+ self.toolkit = Toolkit(mcps=[stateless_client])self.assertListEqual(- self.toolkit.get_function_schemas(),+ await self.toolkit.get_tool_schemas(),self.schemas,)@@ -232,7 +233,7 @@ class SseMCPClientTest(IsolatedAsyncioTestCase):toolkit_with_mcp = Toolkit(tools=[mcp_tool_1])self.assertListEqual(- toolkit_with_mcp.get_function_schemas(),+ await toolkit_with_mcp.get_tool_schemas(),self.schemas,)@@ -267,11 +268,11 @@ class SseMCPClientTest(IsolatedAsyncioTestCase):# mcp client level testself.toolkit.clear()- self.assertDictEqual(self.toolkit.tools, {})+ self.assertListEqual(self.toolkit.tool_groups, [])- await self.toolkit.register_mcp(stateful_client)+ self.toolkit = Toolkit(mcps=[stateful_client])self.assertListEqual(- self.toolkit.get_function_schemas(),+ await self.toolkit.get_tool_schemas(),self.schemas,)@@ -285,7 +286,7 @@ class SseSchemaDefsPreservationTest(IsolatedAsyncioTestCase):These tests start a real FastMCP server that exposes a tool whoseparameter is a Pydantic sub-model. FastMCP generates an inputSchema with``$defs`` for the sub-model. We verify that the schema returned by- ``Toolkit.get_function_schemas()`` preserves those ``$defs`` and that+ ``await toolkit.get_tool_schemas()`` preserves those ``$defs`` and thatPydantic-generated ``title`` fields inside ``$defs`` are stripped."""@@ -348,7 +349,7 @@ class SseSchemaDefsPreservationTest(IsolatedAsyncioTestCase):Expected behaviour (after fix):- ``MCPTool.input_schema`` contains ``$defs._ItemConfig``- - ``Toolkit.get_function_schemas()`` output contains ``$defs``+ - ``await toolkit.get_tool_schemas()`` output contains ``$defs``with the ref resolved and Pydantic titles stripped."""client = MCPClient(@@ -369,7 +370,7 @@ class SseSchemaDefsPreservationTest(IsolatedAsyncioTestCase):"MCPTool.input_schema must preserve $defs from inputSchema",)- # 2. get_function_schemas() must preserve $defs and strip titles+ # 2. get_tool_schemas() must preserve $defs and strip titlestoolkit = Toolkit(tools=[mcp_tool])- schemas = toolkit.get_function_schemas()+ schemas = await toolkit.get_tool_schemas()self.assertListEqual(schemas, self.schemas)diff --git a/tests/toolkit_skill_test.py b/tests/toolkit_skill_test.pyindex 3017d6328..e98d70334 100644--- a/tests/toolkit_skill_test.py+++ b/tests/toolkit_skill_test.py@@ -1,12 +1,13 @@# -*- coding: utf-8 -*-"""Test cases for Toolkit skill-related functionality."""import json-import warnings+import os+import tempfilefrom unittest.async_case import IsolatedAsyncioTestCasefrom utils import AnyString-from agentscope.skill import SkillLoaderBase, LocalSkillLoader, Skill+from agentscope.skill import SkillLoaderBase, Skillfrom agentscope.tool import Toolkit, ToolChunk, ToolResponsefrom agentscope.message import ToolCallBlockfrom agentscope.state import AgentState@@ -41,37 +42,68 @@ class MockSkillLoader(SkillLoaderBase):class ToolkitSkillTest(IsolatedAsyncioTestCase):"""Test cases for Toolkit skill functionality."""- async def test_init_with_skill_loader(self) -> None:- """Test that Toolkit accepts SkillLoaderBase instances in- constructor."""- loader = MockSkillLoader([_make_skill("skill_a")])- toolkit = Toolkit(skills=[loader])-- self.assertEqual(len(toolkit.skills), 1)- self.assertIs(toolkit.skills[0], loader)-- async def test_init_with_string_path(self) -> None:- """Test that Toolkit wraps string paths in LocalSkillLoader."""-- toolkit = Toolkit(skills=["/some/path"])-- self.assertEqual(len(toolkit.skills), 1)- self.assertIsInstance(toolkit.skills[0], LocalSkillLoader)-- async def test_init_with_mixed_skills(self) -> None:- """Test that Toolkit handles mixed string and loader inputs."""-- loader = MockSkillLoader([_make_skill("skill_b")])- toolkit = Toolkit(skills=["/some/path", loader])+ async def test_init_with_various_types(self) -> None:+ """Test Toolkit initialization with str path, SkillLoaderBase, and+ direct Skill objects, then assert get_skill_instructions output."""+ with tempfile.TemporaryDirectory() as skill_dir:+ # Create a minimal SKILL.md so LocalSkillLoader can load it+ skill_md_path = os.path.join(skill_dir, "SKILL.md")+ with open(skill_md_path, "w", encoding="utf-8") as f:+ f.write(+ "---\n"+ "name: path_skill\n"+ "description: A skill loaded from a path\n"+ "---\n\n"+ "# Path Skill\n",+ )++ loader_skill = _make_skill(+ "loader_skill",+ description="A skill from loader",+ dir_="/loader/dir",+ )+ direct_skill = _make_skill(+ "direct_skill",+ description="A directly provided skill",+ dir_="/direct/dir",+ )++ toolkit = Toolkit(+ skills_or_loaders=[+ skill_dir, # str -> LocalSkillLoader+ MockSkillLoader([loader_skill]), # SkillLoaderBase+ direct_skill, # Skill directly+ ],+ )- self.assertEqual(len(toolkit.skills), 2)- self.assertIsInstance(toolkit.skills[0], LocalSkillLoader)- self.assertIs(toolkit.skills[1], loader)+ result = await toolkit.get_skill_instructions()- async def test_init_with_invalid_skill_type(self) -> None:- """Test that Toolkit raises TypeError for invalid skill types."""- with self.assertRaises(TypeError):- Toolkit(skills=[123]) # type: ignore+ self.assertEqual(+ result,+ # pylint: disable=line-too-long+ f"""<agent-skills>+Skills are a collection of instructions, scripts, and resources to extend your capabilities.++**IMPORTANT**: Skills are NOT tools, and you cannot call a skill directly. To use a skill, you MUST use the `Skill` tool to read the skill's full instructions, and then follow those instructions to use the tools and resources provided by the skill.++# Available Skills:+<skill>+<name>path_skill</name>+<description>A skill loaded from a path</description>+<dir>{skill_dir}</dir>+</skill>+<skill>+<name>loader_skill</name>+<description>A skill from loader</description>+<dir>/loader/dir</dir>+</skill>+<skill>+<name>direct_skill</name>+<description>A directly provided skill</description>+<dir>/direct/dir</dir>+</skill>+</agent-skills>""", # noqa: E501+ )async def test_get_skill_instructions_no_skills(self) -> None:"""Test that get_skill_instructions returns None when no skills@@ -80,81 +112,41 @@ class ToolkitSkillTest(IsolatedAsyncioTestCase):result = await toolkit.get_skill_instructions()self.assertIsNone(result)- async def test_get_skill_instructions_with_skills(self) -> None:- """Test that get_skill_instructions returns correct prompt."""- skill = _make_skill(- "my_skill",- description="Does something useful",- dir_="/skills/my_skill",- )- loader = MockSkillLoader([skill])- toolkit = Toolkit(skills=[loader])-- result = await toolkit.get_skill_instructions()-- self.assertIsNotNone(result)- self.assertIn("my_skill", result)- self.assertIn("Does something useful", result)- self.assertIn("/skills/my_skill", result)-async def test_get_skill_instructions_multiple_loaders(self) -> None:"""Test that get_skill_instructions aggregates skills from multipleloaders."""loader1 = MockSkillLoader([_make_skill("skill_x")])loader2 = MockSkillLoader([_make_skill("skill_y")])- toolkit = Toolkit(skills=[loader1, loader2])+ toolkit = Toolkit(skills_or_loaders=[loader1, loader2])result = await toolkit.get_skill_instructions()- self.assertIsNotNone(result)- self.assertIn("skill_x", result)- self.assertIn("skill_y", result)-- async def test_duplicate_skill_name_renamed(self) -> None:- """Test that duplicate skill names are renamed with a numeric- suffix."""- loader1 = MockSkillLoader(- [_make_skill("duplicate_skill", dir_="/dir1")],- )- loader2 = MockSkillLoader(- [_make_skill("duplicate_skill", dir_="/dir2")],+ self.assertEqual(+ result,+ # pylint: disable=line-too-long+ """<agent-skills>+Skills are a collection of instructions, scripts, and resources to extend your capabilities.++**IMPORTANT**: Skills are NOT tools, and you cannot call a skill directly. To use a skill, you MUST use the `Skill` tool to read the skill's full instructions, and then follow those instructions to use the tools and resources provided by the skill.++# Available Skills:+<skill>+<name>skill_x</name>+<description>desc</description>+<dir>/tmp</dir>+</skill>+<skill>+<name>skill_y</name>+<description>desc</description>+<dir>/tmp</dir>+</skill>+</agent-skills>""", # noqa: E501)- toolkit = Toolkit(skills=[loader1, loader2])-- with warnings.catch_warnings(record=True) as caught:- warnings.simplefilter("always")- result = await toolkit.get_skill_instructions()-- self.assertIsNotNone(result)- self.assertIn("duplicate_skill", result)- self.assertIn("duplicate_skill_1", result)-- # A warning should have been issued- self.assertTrue(- any("duplicate_skill" in str(w.message) for w in caught),- "Expected a warning about duplicate skill name",- )-- async def test_duplicate_skill_name_multiple_conflicts(self) -> None:- """Test that multiple duplicates get incrementing suffixes."""- loader1 = MockSkillLoader([_make_skill("dup", dir_="/dir1")])- loader2 = MockSkillLoader([_make_skill("dup", dir_="/dir2")])- loader3 = MockSkillLoader([_make_skill("dup", dir_="/dir3")])- toolkit = Toolkit(skills=[loader1, loader2, loader3])-- with warnings.catch_warnings(record=True):- warnings.simplefilter("always")- result = await toolkit.get_skill_instructions()-- self.assertIsNotNone(result)- self.assertIn("dup", result)- self.assertIn("dup_1", result)- self.assertIn("dup_2", result)async def test_get_skill_instructions_empty_loader(self) -> None:"""Test that an empty loader contributes no skills."""loader = MockSkillLoader([])- toolkit = Toolkit(skills=[loader])+ toolkit = Toolkit(skills_or_loaders=[loader])result = await toolkit.get_skill_instructions()self.assertIsNone(result)@@ -168,9 +160,9 @@ class ToolkitSkillViewerTest(IsolatedAsyncioTestCase):function schemas."""skill = _make_skill("test_skill", description="A test skill")loader = MockSkillLoader([skill])- toolkit = Toolkit(skills=[loader])+ toolkit = Toolkit(skills_or_loaders=[loader])- schemas = toolkit.get_function_schemas()+ schemas = await toolkit.get_tool_schemas()self.assertListEqual(schemas,@@ -211,7 +203,7 @@ class ToolkitSkillViewerTest(IsolatedAsyncioTestCase):)skill.markdown = "# My Skill\nThis is the skill content."loader = MockSkillLoader([skill])- toolkit = Toolkit(skills=[loader])+ toolkit = Toolkit(skills_or_loaders=[loader])tool_call = ToolCallBlock(id="test_call_1",@@ -267,7 +259,7 @@ class ToolkitSkillViewerTest(IsolatedAsyncioTestCase):"""Test calling SkillViewer with a non-existent skill."""skill = _make_skill("existing_skill")loader = MockSkillLoader([skill])- toolkit = Toolkit(skills=[loader])+ toolkit = Toolkit(skills_or_loaders=[loader])tool_call = ToolCallBlock(id="test_call_2",diff --git a/tests/toolkit_test.py b/tests/toolkit_test.pyindex 449748411..e5dd36ca7 100644--- a/tests/toolkit_test.py+++ b/tests/toolkit_test.py@@ -5,6 +5,8 @@ import jsonfrom typing import Any, AsyncGenerator, Generatorfrom unittest import TestCasefrom unittest.async_case import IsolatedAsyncioTestCase++from utils import AnyStringfrom agentscope.state import AgentState@@ -19,6 +21,8 @@ from agentscope.tool import (ToolBase,ToolChunk,ToolResponse,+ ToolGroup,+ FunctionTool,)from agentscope.permission import (PermissionDecision,@@ -140,12 +144,12 @@ class ToolkitTest(IsolatedAsyncioTestCase):toolkit = Toolkit()# No tools- schemas = toolkit.get_function_schemas()+ schemas = await toolkit.get_tool_schemas()self.assertEqual(len(schemas), 0)# Initialize the toolkit with toolstoolkit = Toolkit(tools=[Tool1(), Tool2()])- schemas = toolkit.get_function_schemas()+ schemas = await toolkit.get_tool_schemas()self.assertListEqual(schemas,[@@ -434,11 +438,12 @@ class RegisterFunctionTest(IsolatedAsyncioTestCase):content=[TextBlock(text=f"Result: {result}")],)- toolkit = Toolkit()- toolkit.register_function(add_numbers, group="basic")+ toolkit = Toolkit(+ tools=[FunctionTool(add_numbers)],+ )# Test schema- schemas = toolkit.get_function_schemas()+ schemas = await toolkit.get_tool_schemas()self.assertEqual(len(schemas), 1)self.assertDictEqual(schemas[0],@@ -532,11 +537,16 @@ class RegisterFunctionTest(IsolatedAsyncioTestCase):content=[TextBlock(text=str(i))],)- toolkit = Toolkit()- toolkit.register_function(count_to_n, group="basic")+ toolkit = Toolkit(+ tools=[+ FunctionTool(+ func=count_to_n,+ ),+ ],+ )# Test schema- schemas = toolkit.get_function_schemas()+ schemas = await toolkit.get_tool_schemas()self.assertEqual(len(schemas), 1)self.assertDictEqual(schemas[0],@@ -628,11 +638,12 @@ class RegisterFunctionTest(IsolatedAsyncioTestCase):content=[TextBlock(text=f"Product: {result}")],)- toolkit = Toolkit()- toolkit.register_function(multiply_numbers, group="basic")+ toolkit = Toolkit(+ tools=[FunctionTool(multiply_numbers)],+ )# Test schema- schemas = toolkit.get_function_schemas()+ schemas = await toolkit.get_tool_schemas()self.assertEqual(len(schemas), 1)self.assertDictEqual(schemas[0],@@ -730,11 +741,12 @@ class RegisterFunctionTest(IsolatedAsyncioTestCase):content=[TextBlock(text=f"Number: {i}")],)- toolkit = Toolkit()- toolkit.register_function(generate_sequence, group="basic")+ toolkit = Toolkit(+ tools=[FunctionTool(generate_sequence)],+ )# Test schema- schemas = toolkit.get_function_schemas()+ schemas = await toolkit.get_tool_schemas()self.assertEqual(len(schemas), 1)self.assertDictEqual(schemas[0],@@ -845,19 +857,22 @@ class ToolGroupTest(IsolatedAsyncioTestCase):toolkit = Toolkit()# Test meta tool when no groups exist- schemas = toolkit.get_function_schemas()+ schemas = await toolkit.get_tool_schemas()self.assertEqual(len(schemas), 0)- # Without tools- toolkit.create_tool_group(- group_name="group_1",- description="Group 1",+ toolkit = Toolkit(+ tool_groups=[+ ToolGroup(+ name="group_1",+ description="Group 1",+ ),+ ],)# The group is created successfully- self.assertEqual(len(toolkit.groups), 1)+ self.assertEqual(len(toolkit.tool_groups), 2)# The builtin meta tool is activated- schemas = toolkit.get_function_schemas()+ schemas = await toolkit.get_tool_schemas()self.assertListEqual(schemas,@@ -884,21 +899,37 @@ class ToolGroupTest(IsolatedAsyncioTestCase):# Name conflictwith self.assertRaises(ValueError):- toolkit.create_tool_group(- group_name="group_1",- description="xxx",+ Toolkit(+ tool_groups=[+ ToolGroup(+ name="group_2",+ description="Group 2",+ ),+ ToolGroup(+ name="group_2",+ description="Group 2",+ ),+ ],)# A new group with tools- toolkit.create_tool_group(- group_name="group_2",- description="Group 2",- instructions="This is group 2.",- tools=[Tool1(), Tool2()],+ toolkit = Toolkit(+ tool_groups=[+ ToolGroup(+ name="group_1",+ description="Group 1",+ ),+ ToolGroup(+ name="group_2",+ description="Group 2",+ tools=[Tool1(), Tool2()],+ instructions="This is group 2.",+ ),+ ],)- self.assertEqual(len(toolkit.groups), 2)- schemas = toolkit.get_function_schemas()+ self.assertEqual(len(toolkit.tool_groups), 3)+ schemas = await toolkit.get_tool_schemas()self.assertListEqual(schemas,[@@ -943,7 +974,6 @@ class ToolGroupTest(IsolatedAsyncioTestCase):chunk = await anext(res)self.assertIsInstance(chunk, ToolResponse)-self.assertDictEqual(chunk.model_dump(),{@@ -986,7 +1016,7 @@ The tool instructions are a collection of suggestions, rules and notifications a{"type": "text","id": AnyString(),- "text": """The currently activated tool group(s): group_2, group_1.+ "text": """The currently activated tool group(s): group_1, group_2.<tool-instructions>The tool instructions are a collection of suggestions, rules and notifications about how to use the tools in the activated groups.<group name="group_2">This is group 2.</group>diff --git a/tests/utils.py b/tests/utils.pyindex c0d5c585e..010ca3c08 100644--- a/tests/utils.py+++ b/tests/utils.py@@ -1,5 +1,6 @@# -*- coding: utf-8 -*-"""The utility module for unit tests in agentscope."""+import jsonfrom typing import Any, AsyncGenerator, Typefrom pydantic import BaseModel@@ -9,7 +10,7 @@ from agentscope.message import Msgfrom agentscope.model import ChatModelBase, ChatResponse, StructuredResponse-class AnyString:+class AnyString(str):"""A helper class for asserting any string value in unit tests."""def __eq__(self, other: object) -> bool:@@ -39,6 +40,7 @@ class MockModel(ChatModelBase):def __init__(self,model: str = "mock-model",+ stream: bool = True,context_size: int = 1000,mock_chat_responses: list | None = None,mock_structured_response: Any = None,@@ -47,6 +49,7 @@ class MockModel(ChatModelBase):super().__init__(credential=MockCredential(),model=model,+ stream=stream,parameters=MockModel.Parameters(),context_size=context_size,)@@ -103,3 +106,9 @@ class MockModel(ChatModelBase):) -> StructuredResponse:"""Mock the API call with structured output."""return self.mock_structured_response+++def compare_by_printing(a: Any, b: Any) -> None:+ """Compare the expected output with the actual output by printing them."""+ print(json.dumps(a, indent=4))+ print(json.dumps(b, indent=4))diff --git a/tests/workspace_local_test.py b/tests/workspace_local_test.pyindex 5b5107cd8..7becb833c 100644--- a/tests/workspace_local_test.py+++ b/tests/workspace_local_test.py@@ -4,14 +4,22 @@import osimport jsonimport base64+import hashlibimport tempfile+from pathlib import Path+from typing import Anyfrom unittest.async_case import IsolatedAsyncioTestCasefrom dataclasses import asdictfrom urllib.parse import urlparsefrom urllib.request import url2pathnameimport aiofiles-+from utils import AnyString, MockModel+from agentscope.agent import Agent, ContextConfig+from agentscope.model import ChatResponse, StructuredResponse+from agentscope.state import AgentState+from agentscope.tool import Toolkit, ToolBase, ToolChunk+from agentscope.permission import PermissionDecision, PermissionBehaviorfrom agentscope.workspace import LocalWorkspacefrom agentscope.message import (Msg,@@ -23,9 +31,55 @@ from agentscope.message import (TextBlock,ToolResultBlock,ToolResultState,+ ToolCallBlock,)+class _LongResultTool(ToolBase):+ """A mock tool that returns a long string result for offload testing."""++ name: str = "long_result_tool"+ description: str = "A tool that returns a long string."+ input_schema: dict[str, Any] = {+ "type": "object",+ "properties": {},+ "required": [],+ }+ is_concurrency_safe: bool = True+ is_read_only: bool = True+ is_external_tool: bool = False+ is_mcp: bool = False++ async def check_permissions(+ self,+ *_args: Any,+ **_kwargs: Any,+ ) -> PermissionDecision:+ """Always allow."""+ return PermissionDecision(+ behavior=PermissionBehavior.ALLOW,+ decision_reason="Mock tool always allows",+ message="Mock tool always allows",+ )++ async def __call__(self, **_kwargs: Any) -> ToolChunk:+ """Return a long string result followed by a base64 data block, so we+ can also verify base64 data offloading."""+ return ToolChunk(+ content=[+ TextBlock(text="0" * 30000),+ DataBlock(+ name="fake_image.png",+ source=Base64Source(+ data="AAECAwQF",+ media_type="image/png",+ ),+ ),+ ],+ state=ToolResultState.SUCCESS,+ )++class TestLocalWorkspaceOffload(IsolatedAsyncioTestCase):"""Test cases for LocalWorkspace offload functionality."""@@ -749,3 +803,387 @@ description: {description}# Verify empty list is returnedself.assertListEqual(skills, [])+++class TestLocalWorkspaceWithAgent(IsolatedAsyncioTestCase):+ """Test the local workspace class offloading with the agent."""++ async def test_offload_tool_result(self) -> None:+ """Test integration with the agent when offloading tool result.++ This test verifies that:+ 1. A long tool result is split into a reserved part (kept in context)+ and an offloaded part (written to disk).+ 2. The reserved tool result block in the context is truncated and+ contains a system reminder pointing to the offload file.+ 3. The offloaded file contains the truncated remainder.+ 4. A second reply with a fresh tool call produces a new offload file.+ """+ with tempfile.TemporaryDirectory() as workdir:+ session_id = "test_session"+ model = MockModel(stream=False)+ agent = Agent(+ name="Friday",+ system_prompt="You're a helpful assistant named Friday.",+ model=model,+ toolkit=Toolkit(+ tools=[_LongResultTool()],+ ),+ context_config=ContextConfig(+ tool_result_limit=50,+ ),+ offloader=LocalWorkspace(+ workdir=workdir,+ ),+ state=AgentState(session_id=session_id),+ )++ model.set_responses(+ mock_responses=[+ [+ ChatResponse(+ content=[+ ToolCallBlock(+ id="1",+ name="long_result_tool",+ input="{}",+ ),+ ],+ is_last=True,+ ),+ ],+ [+ ChatResponse(+ content=[+ TextBlock(text="End_1."),+ ],+ is_last=True,+ ),+ ],+ ],+ )++ await agent.reply()++ # === Assert offload file content ===+ offload_path_1 = os.path.join(+ workdir,+ "sessions",+ session_id,+ "tool_result-1.txt",+ )+ self.assertTrue(os.path.exists(offload_path_1))+ async with aiofiles.open(offload_path_1, "r") as f:+ offload_content = await f.read()++ # The base64 payload is hashed with sha256 and persisted under+ # `{workdir}/data/{hash}.{ext}` with the decoded bytes.+ b64_data = "AAECAwQF"+ data_hash = hashlib.sha256(b64_data.encode()).hexdigest()+ data_file_path = os.path.join(+ workdir,+ "data",+ f"{data_hash}.png",+ )+ self.assertTrue(os.path.exists(data_file_path))+ async with aiofiles.open(data_file_path, "rb") as f:+ self.assertEqual(await f.read(), base64.b64decode(b64_data))++ # The full text is "0" * 30000 followed by a base64 DataBlock;+ # tool_result_limit=50 reserves ~200 chars of text in context, the+ # remaining 29800 chars + the DataBlock placeholder are offloaded.+ data_url = Path(data_file_path).as_uri()+ expected_offload_content = (+ "0" * 29800 + f"<data url='{data_url}' name='fake_image.png' "+ f"media_type='image/png'/>"+ )+ self.assertEqual(offload_content, expected_offload_content)++ # === Assert context content ===+ reminder_1 = (+ "\n<<<TRUNCATED>>>\n<system-reminder>The remaining content "+ "has been omitted for limited context. You can refer to the "+ f"file in '{offload_path_1}' for the truncated content if "+ "needed.</system-reminder>"+ )+ expected_first_msg = {+ "id": AnyString(),+ "name": "Friday",+ "role": "assistant",+ "content": [+ {+ "type": "tool_call",+ "id": "1",+ "name": "long_result_tool",+ "input": "{}",+ "state": "finished",+ "suggested_rules": [],+ },+ {+ "type": "tool_result",+ "id": "1",+ "name": "long_result_tool",+ "output": [+ {+ "type": "text",+ "text": "0" * 200 + reminder_1,+ "id": AnyString(),+ },+ ],+ "state": "success",+ },+ {+ "type": "text",+ "text": "End_1.",+ "id": AnyString(),+ },+ ],+ "metadata": {},+ "created_at": AnyString(),+ "finished_at": None,+ "usage": None,+ }+ self.assertListEqual(+ [_.model_dump() for _ in agent.state.context],+ [expected_first_msg],+ )++ async def test_offload_context(self) -> None:+ """Test integration with the agent when offloading context.++ This test triggers context compression twice in the same session and+ verifies that:+ 1. The offload file ``context.jsonl`` is appended to (not+ overwritten) across the two compressions.+ 2. When the compressed context contains a base64-encoded+ ``DataBlock``, the binary payload is persisted to a separate+ data file and the offloaded JSON line references that file via a+ ``URLSource`` instead of embedding the base64 inline.+ 3. ``agent.state.summary`` is rewritten on every compression and+ ends with a system-reminder pointing to the offload file.+ 4. ``agent.state.context`` only retains the latest assistant reply.++ Note: compression triggers based on ``model.context_size`` together+ with the default ``ContextConfig.trigger_ratio`` (0.8) — we set+ ``context_size=100`` here so the threshold is just 80 tokens, and a+ ~500-byte user message (~125 tokens) is enough to trigger+ compression on each reply. The default ``ContextConfig`` is used.+ """+ with tempfile.TemporaryDirectory() as workdir:+ session_id = "test_session_ctx"+ model = MockModel(stream=False, context_size=100)+ agent = Agent(+ name="Friday",+ system_prompt="You're Friday.",+ model=model,+ toolkit=Toolkit(),+ offloader=LocalWorkspace(workdir=workdir),+ state=AgentState(session_id=session_id),+ )++ # The mock structured response is reused across both compression+ # calls (same summary fields each time).+ model.set_structured_response(+ StructuredResponse(+ content={+ "task_overview": "TASK",+ "current_state": "STATE",+ "important_discoveries": "DISCOVERIES",+ "next_steps": "NEXT",+ "context_to_preserve": "PRESERVE",+ },+ ),+ )++ # Each reply yields a single final-text response (no tool calls).+ model.set_responses(+ mock_responses=[+ ChatResponse(+ content=[TextBlock(text="End_1.")],+ is_last=True,+ ),+ ChatResponse(+ content=[TextBlock(text="End_2.")],+ is_last=True,+ ),+ ],+ )++ offload_path = os.path.join(+ workdir,+ "sessions",+ session_id,+ "context.jsonl",+ )++ # ===== First reply =====+ # Build user_msg_a with **fixed** random fields (msg id, the+ # content-block ids, timestamps) so the offloaded JSONL is a+ # fully deterministic string we can assert against literally.+ #+ # Putting the DataBlock FIRST (before the long TextBlock) makes+ # the boundary split include both blocks on the compress side,+ # so the very first compression offloads a multimodal message —+ # the DataBlock is rewritten to a URLSource alongside the+ # original TextBlock, exercising the multimodal offload path.+ b64_data = "AAECAwQF"+ user_msg_a = UserMsg(+ name="user",+ content=[+ DataBlock(+ id="data_block_a",+ name="fake_image_a.png",+ source=Base64Source(+ data=b64_data,+ media_type="image/png",+ ),+ ),+ TextBlock(id="text_block_a", text="A" * 500),+ ],+ id="msg_a",+ created_at="2026-01-01T00:00:00",+ finished_at="2026-01-01T00:00:00",+ )+ await agent.reply(user_msg_a)++ self.assertTrue(os.path.exists(offload_path))+ async with aiofiles.open(offload_path, "r") as f:+ content_after_first = await f.read()++ # The DataBlock is persisted to ``{workdir}/data/`` as soon as+ # it is included in an offloaded line — this happens during the+ # first compression because both blocks land on the compress+ # side of the boundary split.+ data_hash = hashlib.sha256(b64_data.encode()).hexdigest()+ data_file_path = os.path.join(+ workdir,+ "data",+ f"{data_hash}.png",+ )+ self.assertTrue(os.path.exists(data_file_path))+ async with aiofiles.open(data_file_path, "rb") as f:+ self.assertEqual(await f.read(), base64.b64decode(b64_data))++ # The single offloaded line carries user_msg_a with the+ # DataBlock's source rewritten from ``Base64Source`` to+ # ``URLSource`` (pointing at the persisted data file) while the+ # TextBlock is preserved as-is. The expected JSONL is written+ # literally so a developer can read off exactly what gets+ # persisted; only the temp-dir-dependent file URL is+ # interpolated via ``data_url``.+ data_url = Path(data_file_path).as_uri()+ expected_user_msg_a_offloaded_json = (+ '{"name":"user","content":['+ '{"type":"data","id":"data_block_a","source":'+ '{"type":"url","url":"' + data_url + '",'+ '"media_type":"image/png"},"name":"fake_image_a.png"},'+ '{"type":"text","text":"' + "A" * 500 + '",'+ '"id":"text_block_a"}'+ '],"role":"user","id":"msg_a","metadata":{},'+ '"created_at":"2026-01-01T00:00:00",'+ '"finished_at":"2026-01-01T00:00:00","usage":null}'+ )+ self.assertEqual(+ content_after_first,+ expected_user_msg_a_offloaded_json + "\n",+ )++ # ``state.context`` after the first compression is empty+ # (msgs_to_reserve is empty since both content blocks of+ # user_msg_a went to the compress side). After reasoning,+ # ``state.context[0]`` is the assistant's "End_1." reply. The+ # assistant fields (msg id, text-block id, timestamps) are+ # generated by the agent — we capture them here and substitute+ # them into the expected string.+ assistant_1 = agent.state.context[0]++ # ===== Second reply =====+ user_msg_b = UserMsg(+ name="user",+ content=[+ TextBlock(id="text_block_b", text="B" * 500),+ ],+ id="msg_b",+ created_at="2026-01-02T00:00:00",+ finished_at="2026-01-02T00:00:00",+ )+ await agent.reply(user_msg_b)++ async with aiofiles.open(offload_path, "r") as f:+ content_after_second = await f.read()++ # The second compression offloads ``assistant_1`` and+ # ``user_msg_b``. The file is appended to (mode="a"), so it+ # now contains 3 lines: the multimodal user_msg_a from the+ # first compression, plus assistant_1 and user_msg_b from the+ # second.+ expected_assistant_1_json = (+ '{"name":"Friday","content":['+ '{"type":"text","text":"End_1.","id":"'+ + assistant_1.content[0].id+ + '"}'+ '],"role":"assistant","id":"' + assistant_1.id + '",'+ '"metadata":{},"created_at":"' + assistant_1.created_at + '",'+ '"finished_at":null,"usage":null}'+ )+ expected_user_msg_b_json = (+ '{"name":"user","content":['+ '{"type":"text","text":"' + "B" * 500 + '",'+ '"id":"text_block_b"}'+ '],"role":"user","id":"msg_b","metadata":{},'+ '"created_at":"2026-01-02T00:00:00",'+ '"finished_at":"2026-01-02T00:00:00","usage":null}'+ )+ self.assertEqual(+ content_after_second,+ expected_user_msg_a_offloaded_json+ + "\n"+ + expected_assistant_1_json+ + "\n"+ + expected_user_msg_b_json+ + "\n",+ )++ # ``state.summary`` is rewritten on every compression, so the+ # final value is just one rendering of the summary template plus+ # one offload pointer (both compressions wrote to the same file).+ expected_summary = (+ "<system-info>Here is a summary of your previous work\n"+ "# Task Overview\n"+ "TASK\n\n"+ "# Current State\n"+ "STATE\n\n"+ "# Important Discoveries\n"+ "DISCOVERIES\n\n"+ "# Next Steps\n"+ "NEXT\n\n"+ "# Context to Preserve\n"+ "PRESERVE</system-info>\n"+ f"<system-reminder>The compressed context is offloaded "+ f"to '{offload_path}', you can refer to it when needed."+ f"</system-reminder>"+ )+ self.assertEqual(agent.state.summary, expected_summary)++ # ``state.context`` only retains the latest assistant text;+ # everything else has been offloaded.+ expected_second_assistant = {+ "id": AnyString(),+ "name": "Friday",+ "role": "assistant",+ "content": [+ {+ "type": "text",+ "text": "End_2.",+ "id": AnyString(),+ },+ ],+ "metadata": {},+ "created_at": AnyString(),+ "finished_at": None,+ "usage": None,+ }+ self.assertListEqual(+ [_.model_dump() for _ in agent.state.context],+ [expected_second_assistant],+ )