agentscope-runtime 0.1.0__py3-none-any.whl

agentscope_runtime/sandbox/tools/mcp_tool.py

@@ -0,0 +1,191 @@
+# -*- coding: utf-8 -*-
+from typing import Optional, Any, Dict, Set, List
+
+from ..enums import SandboxType
+from ..box.sandbox import Sandbox
+from .sandbox_tool import SandboxTool
+
+
+class MCPTool(SandboxTool):
+    """MCP tool class."""
+
+    def __init__(
+        self,
+        *,
+        sandbox: Optional[Any] = None,
+        name: Optional[str] = None,
+        sandbox_type: Optional[SandboxType | str] = None,
+        tool_type: Optional[str] = None,
+        schema: Optional[Dict] = None,
+        server_configs: Optional[Dict] = None,
+    ):
+        """
+        Initialize the MCP tool with an additional MCP server configuration.
+        """
+        super().__init__(
+            sandbox=sandbox,
+            name=name,
+            sandbox_type=sandbox_type,
+            tool_type=tool_type,
+            schema=schema,
+        )
+        self._server_configs = server_configs
+
+    @property
+    def server_configs(self) -> Optional[Dict]:
+        return self._server_configs
+
+    @server_configs.setter
+    def server_configs(self, config: Dict):
+        if not isinstance(config, dict) and "mcpServers" not in config:
+            raise ValueError(
+                "MCP server configuration must be a valid dictionary.",
+            )
+        self._server_configs = config
+
+    def bind(self, sandbox: Sandbox):
+        """
+        Return a new instance bound with a specific sandbox (immutable mode).
+        """
+        if not isinstance(sandbox, Sandbox):
+            raise TypeError(
+                "The provided sandbox must be an instance of `Sandbox`.",
+            )
+
+        assert self.sandbox_type == sandbox.sandbox_type, (
+            f"Sandbox type mismatch! The tool requires a sandbox of type "
+            f"`{self.sandbox_type}`, but a sandbox of type"
+            f" `{sandbox.sandbox_type}` was provided."
+        )
+
+        return self.__class__(
+            sandbox=sandbox,
+            name=self._name,
+            sandbox_type=self._sandbox_type,
+            tool_type=self._tool_type,
+            schema=self._schema,
+            server_configs=self._server_configs,
+        )
+
+
+class MCPConfigConverter:
+    """MCP configuration management class."""
+
+    def __init__(
+        self,
+        server_configs: Dict,
+        *,
+        sandbox: Optional[Sandbox] = None,
+        whitelist: Optional[Set[str]] = None,
+        blacklist: Optional[Set[str]] = None,
+    ) -> None:
+        """
+        Initializes MCP configuration.
+
+        Args:
+            server_configs: Dictionary of MCP server configurations.
+            whitelist: Whitelist; if set, only functions in the whitelist
+                are allowed.
+            blacklist: Blacklist; functions in the blacklist will be excluded.
+        """
+        self.server_configs = server_configs
+        self.whitelist = whitelist or set()
+        self.blacklist = blacklist or set()
+        self._sandbox = sandbox
+
+        assert (
+            "mcpServers" in server_configs
+        ), "MCP server config must contain 'mcpServers'"
+
+    def bind(self, sandbox: Sandbox) -> "MCPConfigConverter":
+        """
+        Binds a sandbox and returns a new instance.
+
+        Args:
+            sandbox: The sandbox object to bind.
+
+        Returns:
+            A new configuration instance bound to the sandbox.
+        """
+        new_config = self.__class__(
+            server_configs=self.server_configs.copy(),
+            sandbox=sandbox,
+            whitelist=self.whitelist.copy(),
+            blacklist=self.blacklist.copy(),
+        )
+        return new_config
+
+    def to_builtin_tools(
+        self,
+        *,
+        sandbox: Optional[Sandbox] = None,
+    ) -> List[MCPTool]:
+        """
+        Converts to a list of MCPTool instances.
+
+        Returns:
+            A list of bound MCPTool objects.
+        """
+        box = sandbox or self._sandbox
+        if box is None:
+            from ..registry import SandboxRegistry
+
+            cls_ = SandboxRegistry.get_classes_by_type("base")
+            # Use proper context manager
+            with cls_() as tmp_box:
+                return self._process_tools(tmp_box)
+        else:
+            return self._process_tools(box)
+
+    def _process_tools(self, box: Sandbox) -> List[MCPTool]:
+        """Helper method to process tools with the given sandbox."""
+        tools_to_add = []
+        box.add_mcp_servers(
+            server_configs=self.server_configs,
+            overwrite=False,
+        )
+        for server_name in self.server_configs["mcpServers"]:
+            tools = box.list_tools(tool_type=server_name).get(server_name, [])
+            for tool_name, tool_info in tools.items():
+                if self.whitelist and tool_name not in self.whitelist:
+                    continue
+                if self.blacklist and tool_name in self.blacklist:
+                    continue
+
+                tools_to_add.append(
+                    MCPTool(
+                        sandbox=box,
+                        name=tool_name,
+                        sandbox_type=SandboxType.BASE,
+                        tool_type=server_name,
+                        schema=tool_info["json_schema"]["function"],
+                        server_configs={
+                            "mcpServers": {
+                                server_name: self.server_configs["mcpServers"][
+                                    server_name
+                                ],
+                            },
+                        },
+                    ),
+                )
+
+        return tools_to_add
+
+    @classmethod
+    def from_dict(
+        cls,
+        config_dict: Dict,
+        whitelist: Optional[Set[str]] = None,
+        blacklist: Optional[Set[str]] = None,
+    ) -> "MCPConfigConverter":
+        """Creates a configuration instance from a dictionary.
+
+        Args:
+            config_dict: Configuration dictionary.
+            whitelist: Whitelist.
+            blacklist: Blacklist.
+
+        Returns:
+            An instance of McpConfig.
+        """
+        return cls(config_dict, whitelist=whitelist, blacklist=blacklist)

agentscope_runtime/sandbox/tools/sandbox_tool.py

@@ -0,0 +1,104 @@
+# -*- coding: utf-8 -*-
+from typing import Optional, Any, Dict
+
+from .tool import Tool
+from ..enums import SandboxType
+from ..box.sandbox import Sandbox
+
+
+class SandboxTool(Tool):
+    """Built-in tool class"""
+
+    _name: str = None
+    _sandbox_type: SandboxType | str = None
+    _tool_type: str = None
+    _schema: Dict = None
+
+    def __init__(
+        self,
+        *,
+        sandbox: Optional[Any] = None,
+        name: Optional[str] = None,
+        sandbox_type: Optional[SandboxType | str] = None,
+        tool_type: Optional[str] = None,
+        schema: Optional[Dict] = None,
+    ):
+        """
+        Initialize the tool.
+
+        Note: Once the sandbox is set, it does not change.
+        """
+        self._sandbox = sandbox
+        self._name = name or self.__class__._name
+        self._sandbox_type = sandbox_type or self.__class__._sandbox_type
+        self._tool_type = tool_type or self.__class__._tool_type
+        self._schema = schema or self.__class__._schema
+
+    @property
+    def name(self) -> str:
+        return self._name
+
+    @property
+    def sandbox_type(self) -> SandboxType:
+        return SandboxType(self._sandbox_type)
+
+    @property
+    def tool_type(self) -> str:
+        return self._tool_type
+
+    @property
+    def schema(self) -> Dict:
+        return {
+            "type": "function",
+            "function": self._schema,
+        }
+
+    @property
+    def sandbox(self):
+        return self._sandbox
+
+    def __call__(self, *, sandbox: Optional[Any] = None, **kwargs):
+        """Call the tool, allowing a temporary sandbox to be specified"""
+        return self.call(sandbox=sandbox, **kwargs)
+
+    def call(self, *, sandbox: Optional[Any] = None, **kwargs):
+        """
+        Execute the tool call.
+        Args:
+            sandbox: Temporarily used sandbox, highest priority
+            **kwargs: Tool parameters
+        """
+        # Priority: temporary sandbox > instance sandbox > None (dryrun)
+        box = sandbox or self._sandbox
+        if box is None:
+            return self._dryrun_call(**kwargs)
+        else:
+            return box.call_tool(self.name, arguments=kwargs)
+
+    def bind(self, sandbox: Sandbox):
+        """
+        Return a new instance bound with a specific sandbox (immutable mode).
+        """
+        if not isinstance(sandbox, Sandbox):
+            raise TypeError(
+                "The provided sandbox must be an instance of `Sandbox`.",
+            )
+
+        assert self.sandbox_type == sandbox.sandbox_type, (
+            f"Sandbox type mismatch! The tool requires a sandbox of type "
+            f"`{self.sandbox_type}`, but a sandbox of type"
+            f" `{sandbox.sandbox_type}` was provided."
+        )
+
+        return self.__class__(sandbox=sandbox)
+
+    def _dryrun_call(self, **kwargs):
+        """
+        Dryrun mode: temporarily create a sandbox
+        """
+        from ..registry import SandboxRegistry
+
+        cls_ = SandboxRegistry.get_classes_by_type(self.sandbox_type)
+
+        with cls_() as box:
+            return box.call_tool(self.name, arguments=kwargs)

agentscope_runtime/sandbox/tools/tool.py

@@ -0,0 +1,123 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=unused-argument
+from abc import ABC, abstractmethod
+from typing import Optional, Any, Dict
+from ..enums import SandboxType
+
+
+class Tool(ABC):
+    """Abstract base class for all tools.
+
+    This abstract class defines the common interface that all tool
+    implementations must follow, including both SandboxTool and FunctionTool.
+
+    Key responsibilities:
+    - Define the standard tool interface
+    - Ensure consistent behavior across different tool types
+    - Provide common functionality where applicable
+    """
+
+    def __init__(
+        self,
+        *,
+        name: Optional[str] = None,
+        tool_type: Optional[str] = None,
+        **kwargs,
+    ):
+        """
+        Initialize the tool with basic parameters.
+
+        Args:
+            name: Tool name
+            tool_type: Tool type identifier
+            **kwargs: Additional tool-specific parameters
+        """
+        self._name = name
+        self._tool_type = tool_type
+
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        """Get the tool name."""
+
+    @property
+    @abstractmethod
+    def tool_type(self) -> str:
+        """Get the tool type."""
+
+    @property
+    @abstractmethod
+    def schema(self) -> Dict:
+        """Get the tool schema in OpenAI function calling format."""
+
+    @property
+    @abstractmethod
+    def sandbox_type(self) -> SandboxType:
+        """Get the required sandbox type for this tool."""
+
+    @property
+    @abstractmethod
+    def sandbox(self) -> Optional[Any]:
+        """Get the current sandbox instance (if any)."""
+
+    def __call__(self, *, sandbox: Optional[Any] = None, **kwargs):
+        """Call the tool with optional sandbox override.
+
+        This is a convenience method that delegates to the call() method.
+
+        Args:
+            sandbox: Optional sandbox to use for this call
+            **kwargs: Tool parameters
+
+        Returns:
+            Tool execution result
+        """
+        return self.call(sandbox=sandbox, **kwargs)
+
+    @abstractmethod
+    def call(self, *, sandbox: Optional[Any] = None, **kwargs) -> Dict:
+        """Execute the tool call.
+
+        This is the core method that each tool implementation must provide.
+
+        Args:
+            sandbox: Optional sandbox to use for this call
+            **kwargs: Tool parameters
+
+        Returns:
+            Tool execution result in standardized format:
+            {
+                "meta": Optional[Dict],
+                "content": List[Dict],
+                "isError": bool
+            }
+        """
+
+    @abstractmethod
+    def bind(self, *args, **kwargs) -> "Tool":
+        """Bind parameters or context to create a new tool instance.
+
+        The specific binding behavior depends on the tool type:
+        - SandboxTool: binds to a sandbox
+        - FunctionTool: binds function parameters
+
+        Returns:
+            New tool instance with bound parameters/context
+        """
+
+    def __str__(self) -> str:
+        """String representation of the tool."""
+        return (
+            f"{self.__class__.__name__}(name='{self.name}', type="
+            f"'{self.tool_type}')"
+        )
+
+    def __repr__(self) -> str:
+        """Detailed string representation of the tool."""
+        return (
+            f"{self.__class__.__name__}("
+            f"name='{self.name}', "
+            f"tool_type='{self.tool_type}', "
+            f"sandbox_type='{self.sandbox_type}'"
+            f")"
+        )

agentscope_runtime/sandbox/tools/utils.py

@@ -0,0 +1,68 @@
+# -*- coding: utf-8 -*-
+def setup_tools(
+    tools,
+    environment_manager,
+    session_id,
+    user_id,
+    include_schemas=False,
+):
+    """
+    Generic function to activate tools.
+
+    Args:
+        tools: List of tools to activate.
+        environment_manager: Environment manager
+        session_id: ID of the session.
+        user_id: ID of the user.
+        include_schemas: Boolean flag to indicate if schemas should be
+            included.
+
+    Returns:
+        tuple: (activated_tools, schemas) if include_schemas=True,
+            else only activated_tools.
+    """
+    # Lazy import
+    from .tool import Tool
+    from .sandbox_tool import SandboxTool
+    from ...sandbox.box.dummy.dummy_sandbox import DummySandbox
+
+    enable_sandbox = False
+
+    # Check tool types and determine if sandbox needs to be enabled
+    for tool in tools:
+        assert isinstance(tool, Tool), f"{tool} must be an instance of Tool"
+        if isinstance(tool, SandboxTool):
+            enable_sandbox = True
+            break
+
+    # Check environment service
+    if enable_sandbox and environment_manager is None:
+        raise ValueError("environment_manager is not set")
+
+    # Connect to sandbox if required
+    if enable_sandbox:
+        sandboxes = environment_manager.connect_sandbox(
+            session_id=session_id,
+            user_id=user_id,
+            tools=tools,
+        )
+    else:
+        sandboxes = [DummySandbox()]
+
+    # Bind tools to sandbox and prepare schemas if required
+    schemas = []  # Initialize schemas list
+    activated_tools = []  # Initialize activated tools list
+
+    for tool in tools:
+        if include_schemas:
+            schemas.append(tool.schema)  # Collect tool schemas
+        for sandbox in sandboxes:
+            if sandbox.sandbox_type == tool.sandbox_type:
+                bound_tool = tool.bind(sandbox)  # Bind tool to the sandbox
+                activated_tools.append(
+                    bound_tool,
+                )  # Add to the activated tools list
+
+    if include_schemas:
+        return activated_tools, schemas
+    return activated_tools

agentscope_runtime/version.py

@@ -0,0 +1,2 @@
+# -*- coding: utf-8 -*-
+__version__ = "v0.0.1"