Skip to content

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

feat(tool): integrate the tool and workspace modules with the Agent class (#1642)

DavdGaocc1087dcade6
diff --git a/docs/FAQ.md b/docs/FAQ.md
new file mode 100644
index 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.md
new file mode 100644
index 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.py
index 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 AnthropicChatModel
from 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.py
index 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 DashScopeChatModel
from 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.py
index 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 DeepSeekChatModel
from 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, since
deepseek-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.py
index 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 GeminiChatModel
from 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.py
index 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 MoonshotChatModel
from 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.py
index 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 OllamaChatModel
from 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.py
index 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 OpenAIChatModel
from 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.py
index 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 OpenAIResponseModel
from 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.py
index 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 XAIChatModel
from 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.py
index 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 Offloader
if 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 configurations
model_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 = name
self._system_prompt = system_prompt
self.model = model
- self.toolkit = toolkit
self.state = state or AgentState()
self.model_config = model_config
self.context_config = context_config
self.react_config = react_config
+ # The permission engine
self._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 summary
self.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 context
self.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 not
batches: 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 output
if 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.py
index 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 CronTrigger
from ....message import UserMsg
from ....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 = storage
self._session_manager = session_manager
self._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.py
index 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.py
index 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.py
index 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, HttpMCPConfig
from .._logging import logger
if TYPE_CHECKING:
- from ..tool import MCPTool
+ from ..tool import MCPTool, ToolBase
else:
MCPTool = Any
+ ToolBase = Any
class 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 client
self._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 session
async 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.tools
else:
# Stateful: use existing session
self._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.py
index 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__.py
index 9c7355eb3..1782942d6 100644
--- a/src/agentscope/tool/__init__.py
+++ b/src/agentscope/tool/__init__.py
@@ -5,7 +5,7 @@ from ._types import ToolChoice, Function, RegisteredTool
from ._response import ToolResponse, ToolChunk
from ._toolkit import Toolkit
from ._base import ToolBase
-from ._adapters import MCPTool
+from ._adapters import MCPTool, FunctionTool
from ._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.py
index 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 with
diff --git a/src/agentscope/tool/_builtin/_meta.py b/src/agentscope/tool/_builtin/_meta.py
index 29a3855fc..b3fccff41 100644
--- a/src/agentscope/tool/_builtin/_meta.py
+++ b/src/agentscope/tool/_builtin/_meta.py
@@ -5,6 +5,7 @@ from typing import Any
from pydantic import Field, create_model
from jinja2 import Template
+from .._tool_group import ToolGroup
from ...permission import (
PermissionContext,
PermissionDecision,
@@ -12,7 +13,6 @@ from ...permission import (
)
from .._response import ToolChunk
from .._base import ToolBase
-from .._types import ToolGroup
from ...exception import DeveloperOrientedException
from ...message import TextBlock
from ...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 current
available 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.py
index 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 DeveloperOrientedException
from ...permission import (
PermissionContext,
PermissionDecision,
@@ -11,6 +12,7 @@ from .._response import ToolChunk
from .._base import ToolBase
from ...skill import Skill
from ...message import TextBlock, ToolResultState
+from ...state import AgentState
class 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.py
new file mode 100644
index 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 skills
diff --git a/src/agentscope/tool/_toolkit.py b/src/agentscope/tool/_toolkit.py
index 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 asyncio
import inspect
-import warnings
from collections import OrderedDict
-from copy import deepcopy
from typing import (
AsyncGenerator,
- Any,
Type,
Generator,
- Callable,
- Coroutine,
)
import mcp
@@ -24,10 +19,9 @@ from pydantic import (
from ._builtin import ResetTools, SkillViewer
from ._base import ToolBase
-from ._adapters import _FunctionTool
from ._response import ToolResponse, ToolChunk
-from ..skill import SkillLoaderBase, LocalSkillLoader, Skill
-from ._types import ToolGroup, RegisteredTool
+from ..skill import SkillLoaderBase, Skill
+from ._types import RegisteredTool
from .._utils._common import _json_loads_with_repair
from ..exception import (
DeveloperOrientedException,
@@ -40,6 +34,7 @@ from ..message import (
TextBlock,
ToolResultState,
)
+from ._tool_group import ToolGroup
from .._logging import logger
from ..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_enabled
self.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 JSON
schema, 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].group
chunk = ToolChunk(
content=[
TextBlock(
@@ -608,135 +385,41 @@ class Toolkit:
# Finally, yield the complete tool response
yield 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 skills
async def get_skill_instructions(self) -> str | None:
@@ -754,10 +437,7 @@ class Toolkit:
The combined prompt for all registered agent skills, or None
if 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 None
if 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 included
groups_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 the
error 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].group
if 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.py
index 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 function
diff --git a/src/agentscope/workspace/__init__.py b/src/agentscope/workspace/__init__.py
index ccbe4592d..39f0ba19c 100644
--- a/src/agentscope/workspace/__init__.py
+++ b/src/agentscope/workspace/__init__.py
@@ -7,6 +7,7 @@ from pydantic import Field
from ._base import WorkspaceBase
from ._local_workspace import LocalWorkspace
+from ._offload_protocol import Offloader
AnyWorkspace = 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.py
index 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 correct
subclass from ``WorkspaceRecord.data`` without a separate factory.
diff --git a/src/agentscope/workspace/_local_workspace.py b/src/agentscope/workspace/_local_workspace.py
index 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.py
new file mode 100644
index 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.py
index 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 Any
from 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-builtin
async 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-builtin
async def __call__(self, input: str, **kwargs: Any) -> ToolChunk:
"""Execute the tool."""
return ToolChunk(
@@ -536,10 +536,7 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
"""
# Register sequential tools
seq_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 IDs
tool_call_id_1 = "tool_call_1"
@@ -803,9 +800,8 @@ class AgentBasicTest(IsolatedAsyncioTestCase):
# Register concurrent tools
conc_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 IDs
diff --git a/tests/compress_context_test.py b/tests/compress_context_test.py
index 138329877..b1bb16692 100644
--- a/tests/compress_context_test.py
+++ b/tests/compress_context_test.py
@@ -619,6 +619,7 @@ class ContextCompressionTest(IsolatedAsyncioTestCase):
# Context to Preserve
5</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.py
index 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 tool
ext_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 tool
ext_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 tool
ext_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.py
index 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 tool
confirm_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 tool
confirm_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 tool
confirm_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.py
index 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 constructor
toolkit_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 test
self.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 whose
parameter 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 that
Pydantic-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 titles
toolkit = 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.py
index 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 tempfile
from unittest.async_case import IsolatedAsyncioTestCase
from utils import AnyString
-from agentscope.skill import SkillLoaderBase, LocalSkillLoader, Skill
+from agentscope.skill import SkillLoaderBase, Skill
from agentscope.tool import Toolkit, ToolChunk, ToolResponse
from agentscope.message import ToolCallBlock
from 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 multiple
loaders."""
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.py
index 449748411..e5dd36ca7 100644
--- a/tests/toolkit_test.py
+++ b/tests/toolkit_test.py
@@ -5,6 +5,8 @@ import json
from typing import Any, AsyncGenerator, Generator
from unittest import TestCase
from unittest.async_case import IsolatedAsyncioTestCase
+
+
from utils import AnyString
from 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 tools
toolkit = 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 conflict
with 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.py
index 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 json
from typing import Any, AsyncGenerator, Type
from pydantic import BaseModel
@@ -9,7 +10,7 @@ from agentscope.message import Msg
from 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.py
index 5b5107cd8..7becb833c 100644
--- a/tests/workspace_local_test.py
+++ b/tests/workspace_local_test.py
@@ -4,14 +4,22 @@
import os
import json
import base64
+import hashlib
import tempfile
+from pathlib import Path
+from typing import Any
from unittest.async_case import IsolatedAsyncioTestCase
from dataclasses import asdict
from urllib.parse import urlparse
from urllib.request import url2pathname
import 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, PermissionBehavior
from agentscope.workspace import LocalWorkspace
from 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 returned
self.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],
+ )