agentscope-runtime 0.2.0b2__py3-none-any.whl → 1.0.0b1__py3-none-any.whl

agentscope_runtime/sandbox/box/browser/browser_sandbox.py

@@ -53,42 +53,80 @@ class BrowserSandbox(GUIMixin, BaseSandbox):
         )
 
     def browser_close(self):
+        """Close the current browser page."""
         return self.call_tool("browser_close", {})
 
     def browser_resize(self, width: int, height: int):
+        """Resize the browser window.
+
+        Args:
+            width (int): Width of the browser window.
+            height (int): Height of the browser window.
+        """
         return self.call_tool(
             "browser_resize",
             {"width": width, "height": height},
         )
 
     def browser_console_messages(self):
+        """Return all console messages from the browser."""
         return self.call_tool("browser_console_messages", {})
 
     def browser_handle_dialog(self, accept: bool, prompt_text: str = ""):
+        """Handle a dialog popup.
+
+        Args:
+            accept (bool): Whether to accept the dialog.
+            prompt_text (str, optional): Text to input if the dialog is a
+                prompt.
+        """
         return self.call_tool(
             "browser_handle_dialog",
             {"accept": accept, "promptText": prompt_text},
         )
 
     def browser_file_upload(self, paths: list):
+        """Upload one or multiple files in the browser.
+
+        Args:
+            paths (list[str]): Absolute paths to the files to upload.
+        """
         return self.call_tool("browser_file_upload", {"paths": paths})
 
     def browser_press_key(self, key: str):
+        """Press a key on the keyboard.
+
+        Args:
+            key (str): Name of the key to press or a character to enter.
+        """
         return self.call_tool("browser_press_key", {"key": key})
 
     def browser_navigate(self, url: str):
+        """Navigate to a specified URL.
+
+        Args:
+            url (str): The URL to load in the browser.
+        """
         return self.call_tool("browser_navigate", {"url": url})
 
     def browser_navigate_back(self):
+        """Go back to the previous page."""
         return self.call_tool("browser_navigate_back", {})
 
     def browser_navigate_forward(self):
+        """Go forward to the next page."""
         return self.call_tool("browser_navigate_forward", {})
 
     def browser_network_requests(self):
+        """Return all network requests since the page was loaded."""
         return self.call_tool("browser_network_requests", {})
 
     def browser_pdf_save(self, filename: str = ""):
+        """Save the current page as a PDF.
+
+        Args:
+            filename (str, optional): File name to save the PDF as.
+        """
         return self.call_tool("browser_pdf_save", {"filename": filename})
 
     def browser_take_screenshot(
@@ -98,20 +136,33 @@ class BrowserSandbox(GUIMixin, BaseSandbox):
         element: str = "",
         ref: str = "",
     ):
+        """Take a screenshot of the current page or of a specific element.
+
+        Args:
+            raw (bool, optional): If True, save in PNG without compression.
+                Defaults to False (JPEG).
+            filename (str, optional): File name for the screenshot.
+            element (str, optional): Human-readable element description to
+                screenshot.
+            ref (str, optional): Exact element reference from the page
+                snapshot.
+        """
         return self.call_tool(
             "browser_take_screenshot",
-            {
-                "raw": raw,
-                "filename": filename,
-                "element": element,
-                "ref": ref,
-            },
+            {"raw": raw, "filename": filename, "element": element, "ref": ref},
         )
 
     def browser_snapshot(self):
+        """Capture an accessibility snapshot of the current page."""
         return self.call_tool("browser_snapshot", {})
 
     def browser_click(self, element: str, ref: str):
+        """Click on an element in the current page.
+
+        Args:
+            element (str): Human-readable element description to click.
+            ref (str): Exact element reference from the page snapshot.
+        """
         return self.call_tool(
             "browser_click",
             {"element": element, "ref": ref},
@@ -124,6 +175,14 @@ class BrowserSandbox(GUIMixin, BaseSandbox):
         end_element: str,
         end_ref: str,
     ):
+        """Drag from one element and drop onto another.
+
+        Args:
+            start_element (str): Human-readable source element description.
+            start_ref (str): Exact source element reference.
+            end_element (str): Human-readable target element description.
+            end_ref (str): Exact target element reference.
+        """
         return self.call_tool(
             "browser_drag",
             {
@@ -135,6 +194,12 @@ class BrowserSandbox(GUIMixin, BaseSandbox):
         )
 
     def browser_hover(self, element: str, ref: str):
+        """Hover over an element in the current page.
+
+        Args:
+            element (str): Human-readable element description.
+            ref (str): Exact element reference from the page snapshot.
+        """
         return self.call_tool(
             "browser_hover",
             {"element": element, "ref": ref},
@@ -148,6 +213,17 @@ class BrowserSandbox(GUIMixin, BaseSandbox):
         submit: bool = False,
         slowly: bool = False,
     ):
+        """Type text into an editable element.
+
+        Args:
+            element (str): Human-readable element description.
+            ref (str): Exact element reference.
+            text (str): Text to type into the element.
+            submit (bool, optional): Press Enter after typing. Defaults to
+                False.
+            slowly (bool, optional): Type one character at a time. Defaults
+                to False.
+        """
         return self.call_tool(
             "browser_type",
             {
@@ -160,25 +236,46 @@ class BrowserSandbox(GUIMixin, BaseSandbox):
         )
 
     def browser_select_option(self, element: str, ref: str, values: list):
+        """Select options in a dropdown.
+
+        Args:
+            element (str): Human-readable element description.
+            ref (str): Exact element reference.
+            values (list[str]): Values to select.
+        """
         return self.call_tool(
             "browser_select_option",
-            {
-                "element": element,
-                "ref": ref,
-                "values": values,
-            },
+            {"element": element, "ref": ref, "values": values},
         )
 
     def browser_tab_list(self):
+        """List all browser tabs."""
         return self.call_tool("browser_tab_list", {})
 
     def browser_tab_new(self, url: str = ""):
+        """Open a new browser tab.
+
+        Args:
+            url (str, optional): URL to open in the new tab. Blank if not
+                provided.
+        """
         return self.call_tool("browser_tab_new", {"url": url})
 
     def browser_tab_select(self, index: int):
+        """Select a browser tab by index.
+
+        Args:
+            index (int): Index of the tab to select.
+        """
         return self.call_tool("browser_tab_select", {"index": index})
 
     def browser_tab_close(self, index: int = None):
+        """Close a browser tab.
+
+        Args:
+            index (int, optional): Index of the tab to close.
+            Closes current tab if not provided.
+        """
         return self.call_tool("browser_tab_close", {"index": index})
 
     def browser_wait_for(
@@ -187,6 +284,13 @@ class BrowserSandbox(GUIMixin, BaseSandbox):
         text: str = None,
         text_gone: str = None,
     ):
+        """Wait for text to appear/disappear or for a specified time.
+
+        Args:
+            time (float, optional): Seconds to wait.
+            text (str, optional): Text to wait for.
+            text_gone (str, optional): Text to wait to disappear.
+        """
         return self.call_tool(
             "browser_wait_for",
             {

agentscope_runtime/sandbox/box/cloud/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+from .cloud_sandbox import CloudSandbox
+
+__all__ = ["CloudSandbox"]

agentscope_runtime/sandbox/box/cloud/cloud_sandbox.py

@@ -0,0 +1,254 @@
+# -*- coding: utf-8 -*-
+"""
+CloudSandbox base class for cloud-based sandbox implementations.
+
+This module provides a base class for cloud sandbox implementations that
+don't rely on local container management but instead communicate directly
+with cloud APIs.
+"""
+import logging
+from typing import Any, Dict, Optional
+from abc import ABC, abstractmethod
+
+from ...enums import SandboxType
+from ...box.sandbox import Sandbox
+
+logger = logging.getLogger(__name__)
+
+
+class CloudSandbox(Sandbox, ABC):
+    """
+    Base class for cloud-based sandbox implementations.
+
+    This class provides a unified interface for cloud sandbox services that
+    don't depend on local container management. Instead, they communicate
+    directly with cloud APIs to manage remote environments.
+
+    Key features:
+    - No local container dependency
+    - Direct cloud API communication
+    - Unified interface for cloud sandbox operations
+    - Support for different cloud providers
+    """
+
+    def __init__(
+        self,
+        sandbox_id: Optional[str] = None,
+        timeout: int = 3000,
+        base_url: Optional[str] = None,
+        bearer_token: Optional[str] = None,
+        sandbox_type: SandboxType = SandboxType.AGENTBAY,
+        **kwargs,
+    ):
+        """
+        Initialize the cloud sandbox.
+
+        Args:
+            sandbox_id: Optional sandbox ID for existing sessions
+            timeout: Timeout for operations in seconds
+            base_url: Base URL for cloud API (optional, may use default)
+            bearer_token: Authentication token for cloud API
+            sandbox_type: Type of sandbox (default: AGENTBAY)
+            **kwargs: Additional cloud-specific configuration
+        """
+        # Initialize base attributes (similar to parent class but without
+        # SandboxManager)
+        # Note: We don't call super().__init__() because CloudSandbox uses a
+        # different architecture - it doesn't need SandboxManager, instead it
+        # communicates directly with cloud APIs through cloud_client.
+        self.base_url = base_url
+        self.embed_mode = False
+        self.manager_api = None
+
+        # Store cloud-specific configuration
+        self.cloud_config = kwargs
+        self.bearer_token = bearer_token
+
+        # Initialize cloud client
+        self.cloud_client = self._initialize_cloud_client()
+
+        # Initialize sandbox ID
+        if sandbox_id is None:
+            sandbox_id = self._create_cloud_sandbox()
+            if sandbox_id is None:
+                raise RuntimeError(
+                    "Failed to create cloud sandbox. "
+                    "Please check your cloud API credentials and "
+                    "configuration.",
+                )
+
+        self._sandbox_id = sandbox_id
+        self.sandbox_type = sandbox_type
+        self.timeout = timeout
+
+        logger.info(f"Cloud sandbox initialized with ID: {self._sandbox_id}")
+
+    @abstractmethod
+    def _initialize_cloud_client(self):
+        """
+        Initialize the cloud client for API communication.
+
+        This method should be implemented by subclasses to create
+        the appropriate cloud client (e.g., AgentBay client).
+
+        Returns:
+            Cloud client instance
+        """
+        # Abstract method - must be implemented by subclasses
+
+    @abstractmethod
+    def _create_cloud_sandbox(self) -> Optional[str]:
+        """
+        Create a new cloud sandbox.
+
+        This method should be implemented by subclasses to create
+        a new sandbox using the cloud provider's API.
+
+        Returns:
+            Sandbox ID if successful, None otherwise
+        """
+        # Abstract method - must be implemented by subclasses
+
+    @abstractmethod
+    def _delete_cloud_sandbox(self, sandbox_id: str) -> bool:
+        """
+        Delete a cloud sandbox.
+
+        Args:
+            sandbox_id: ID of the sandbox to delete
+
+        Returns:
+            True if successful, False otherwise
+        """
+        # Abstract method - must be implemented by subclasses
+
+    @abstractmethod
+    def _call_cloud_tool(
+        self,
+        tool_name: str,
+        arguments: Dict[str, Any],
+    ) -> Any:
+        """
+        Call a tool in the cloud environment.
+
+        Args:
+            tool_name: Name of the tool to call
+            arguments: Arguments for the tool
+
+        Returns:
+            Tool execution result
+        """
+        # Abstract method - must be implemented by subclasses
+
+    def call_tool(
+        self,
+        name: str,
+        arguments: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        """
+        Call a tool in the cloud sandbox.
+
+        Args:
+            name: Name of the tool to call
+            arguments: Arguments for the tool
+
+        Returns:
+            Tool execution result
+        """
+        if arguments is None:
+            arguments = {}
+
+        return self._call_cloud_tool(name, arguments)
+
+    def get_info(self) -> Dict[str, Any]:
+        """
+        Get information about the cloud sandbox.
+
+        Returns:
+            Dictionary containing sandbox information
+        """
+        return {
+            "sandbox_id": self._sandbox_id,
+            "sandbox_type": self.sandbox_type.value,
+            "cloud_provider": self._get_cloud_provider_name(),
+            "timeout": self.timeout,
+        }
+
+    @abstractmethod
+    def _get_cloud_provider_name(self) -> str:
+        """
+        Get the name of the cloud provider.
+
+        Returns:
+            Name of the cloud provider (e.g., "AgentBay")
+        """
+        # Abstract method - must be implemented by subclasses
+
+    def list_tools(self, tool_type: Optional[str] = None) -> Dict[str, Any]:
+        """
+        List available tools in the cloud sandbox.
+
+        Args:
+            tool_type: Optional filter for tool type
+
+        Returns:
+            Dictionary containing available tools
+        """
+        # Default implementation - subclasses can override
+        return {
+            "tools": [],
+            "tool_type": tool_type,
+            "sandbox_id": self._sandbox_id,
+        }
+
+    def add_mcp_servers(
+        self,
+        server_configs: Dict[str, Any],
+        overwrite: bool = False,
+    ) -> Dict[str, Any]:
+        """
+        Add MCP servers to the cloud sandbox.
+
+        Args:
+            server_configs: Configuration for MCP servers
+            overwrite: Whether to overwrite existing configurations
+
+        Returns:
+            Result of the operation
+        """
+        # Default implementation - subclasses can override
+        return {
+            "success": True,
+            "message": "MCP servers added successfully",
+            "overwrite": overwrite,
+        }
+
+    def _cleanup(self):
+        """
+        Clean up cloud sandbox resources.
+
+        This method is called when the sandbox is being destroyed.
+        It ensures that cloud resources are properly released.
+        """
+        try:
+            if self._sandbox_id:
+                success = self._delete_cloud_sandbox(self._sandbox_id)
+                if success:
+                    logger.info(
+                        f"Cloud session {self._sandbox_id} deleted "
+                        f"successfully",
+                    )
+                else:
+                    logger.warning(
+                        f"Failed to delete cloud session {self._sandbox_id}",
+                    )
+        except Exception as e:
+            logger.error(f"Error during cloud sandbox cleanup: {e}")
+
+    def __enter__(self):
+        """Context manager entry."""
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback):
+        """Context manager exit with cleanup."""
+        self._cleanup()

agentscope_runtime/sandbox/box/filesystem/filesystem_sandbox.py

@@ -35,15 +35,41 @@ class FilesystemSandbox(GUIMixin, BaseSandbox):
         )
 
     def read_file(self, path: str):
+        """Read the complete contents of a file.
+
+        Args:
+            path (str): Path to the file to read.
+        """
         return self.call_tool("read_file", {"path": path})
 
     def read_multiple_files(self, paths: list):
+        """Read the contents of multiple files simultaneously.
+
+        Args:
+            paths (list[str]): List of file paths to read.
+        """
         return self.call_tool("read_multiple_files", {"paths": paths})
 
     def write_file(self, path: str, content: str):
+        """Create a new file or overwrite an existing file with new content.
+
+        Args:
+            path (str): Path to the file to write.
+            content (str): Content to write to the file.
+        """
         return self.call_tool("write_file", {"path": path, "content": content})
 
     def edit_file(self, path: str, edits: list, dry_run: bool = False):
+        """Make line-based edits to a text file.
+
+        Args:
+            path (str): Path to the file to edit.
+            edits (list[dict]): List of edits to make. Each edit must contain:
+                oldText (str): Text to search for (exact match).
+                newText (str): Text to replace with.
+            dry_run (bool): If True, preview the changes using git-style
+                diff format.
+        """
         return self.call_tool(
             "edit_file",
             {
@@ -54,15 +80,39 @@ class FilesystemSandbox(GUIMixin, BaseSandbox):
         )
 
     def create_directory(self, path: str):
+        """Create a new directory or ensure it exists.
+
+        Args:
+            path (str): Path to the directory to create.
+        """
         return self.call_tool("create_directory", {"path": path})
 
     def list_directory(self, path: str):
+        """
+        Get a detailed listing of all files and directories in a specified
+        path.
+
+        Args:
+            path (str): Path to list contents from.
+        """
         return self.call_tool("list_directory", {"path": path})
 
     def directory_tree(self, path: str):
+        """
+        Get a recursive tree view of files and directories as a JSON structure.
+
+        Args:
+            path (str): Path to get tree structure from.
+        """
         return self.call_tool("directory_tree", {"path": path})
 
     def move_file(self, source: str, destination: str):
+        """Move or rename files and directories.
+
+        Args:
+            source (str): Source path to move from.
+            destination (str): Destination path to move to.
+        """
         return self.call_tool(
             "move_file",
             {"source": source, "destination": destination},
@@ -74,6 +124,13 @@ class FilesystemSandbox(GUIMixin, BaseSandbox):
         pattern: str,
         exclude_patterns: list = [],
     ):
+        """Recursively search for files and directories matching a pattern.
+
+        Args:
+            path (str): Starting path for the search.
+            pattern (str): Pattern to match files/directories.
+            exclude_patterns (list[str]): Patterns to exclude from the search.
+        """
         return self.call_tool(
             "search_files",
             {
@@ -84,7 +141,16 @@ class FilesystemSandbox(GUIMixin, BaseSandbox):
         )
 
     def get_file_info(self, path: str):
+        """
+        Retrieve detailed metadata about a file or directory.
+
+        Args:
+            path (str): Path to the file or directory.
+        """
         return self.call_tool("get_file_info", {"path": path})
 
     def list_allowed_directories(self):
+        """
+        Returns the list of directories that this serveris allowed to access.
+        """
         return self.call_tool("list_allowed_directories", {})

agentscope_runtime/sandbox/box/gui/gui_sandbox.py

@@ -1,4 +1,5 @@
 # -*- coding: utf-8 -*-
+# flake8: noqa: E501
 import logging
 from typing import Optional, Union, Tuple, List
 
@@ -72,6 +73,47 @@ class GuiSandbox(GUIMixin, BaseSandbox):
         coordinate: Optional[Union[List[float], Tuple[float, float]]] = None,
         text: Optional[str] = None,
     ):
+        """Use a mouse and keyboard to interact with a computer, and take screenshots.
+
+        This is an interface to a desktop GUI. You do not have access to a terminal or
+        applications menu. You must click on desktop icons to start applications.
+
+        Guidelines:
+            * Always prefer using keyboard shortcuts rather than clicking, where possible.
+            * If you see boxes with two letters in them, typing these letters will click
+              that element. Use this instead of other shortcuts or clicking, where possible.
+            * Some applications may take time to start or process actions, so you may
+              need to wait and take successive screenshots to see the results of your
+              actions. For example, if you click on Firefox and a window doesn't open,
+              try taking another screenshot.
+            * Whenever you intend to move the cursor to click on an element (like an icon),
+              consult a screenshot to determine the coordinates of the element before moving
+              the cursor.
+            * If clicking on a program or link fails to load, even after waiting, try adjusting
+              your cursor position so that the tip falls visually on the element you want to click.
+            * Make sure to click any buttons, links, icons, etc., with the cursor tip in the center
+              of the element. Don't click boxes on their edges unless asked.
+
+        Args:
+            action (str): The action to perform. Options are:
+                * `key`: Press a key or key-combination on the keyboard.
+                * `type`: Type a string of text.
+                * `get_cursor_position`: Get the current (x, y) pixel coordinate of the cursor.
+                * `mouse_move`: Move the cursor to a specified (x, y) coordinate.
+                * `left_click`: Click the left mouse button.
+                * `left_click_drag`: Click and drag to a specified coordinate.
+                * `right_click`: Click the right mouse button.
+                * `middle_click`: Click the middle mouse button.
+                * `double_click`: Double-click the left mouse button.
+                * `get_screenshot`: Take a screenshot of the screen.
+            coordinate (list[float] | tuple[float, float], optional):
+                The (x, y) pixel coordinates.
+                x = pixels from the left edge, y = pixels from the top edge.
+            text (str, optional): Text to type or key command to execute.
+
+        Returns:
+            Any: Result of performing the specified computer action.
+        """
         payload = {"action": action}
         if coordinate is not None:
             payload["coordinate"] = coordinate

agentscope_runtime/sandbox/box/mobile/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+from .mobile_sandbox import MobileSandbox
+
+__all__ = ["MobileSandbox"]