agentscope-runtime 0.1.5b2__py3-none-any.whl → 0.2.0__py3-none-any.whl

agentscope_runtime/sandbox/manager/server/app.py

@@ -6,11 +6,13 @@ import logging
 
 from typing import Optional
 
+import httpx
 import websockets
+
 from fastapi import FastAPI, HTTPException, Request, Depends
 from fastapi import WebSocket, WebSocketDisconnect
 from fastapi.middleware.cors import CORSMiddleware
-from fastapi.responses import JSONResponse
+from fastapi.responses import JSONResponse, Response
 from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
 
 from ...manager.server.config import get_settings
@@ -20,6 +22,7 @@ from ...manager.server.models import (
 )
 from ...manager.sandbox_manager import SandboxManager
 from ...model.manager_config import SandboxManagerEnvConfig
+from ...utils import dynamic_import, http_to_ws
 from ....version import __version__
 
 # Configure logging
@@ -61,6 +64,7 @@ def get_config() -> SandboxManagerEnvConfig:
             redis_enabled=settings.REDIS_ENABLED,
             container_deployment=settings.CONTAINER_DEPLOYMENT,
             default_mount_dir=settings.DEFAULT_MOUNT_DIR,
+            readonly_mounts=settings.READONLY_MOUNTS,
             storage_folder=settings.STORAGE_FOLDER,
             port_range=settings.PORT_RANGE,
             pool_size=settings.POOL_SIZE,
@@ -77,6 +81,18 @@ def get_config() -> SandboxManagerEnvConfig:
             redis_container_pool_key=settings.REDIS_CONTAINER_POOL_KEY,
             k8s_namespace=settings.K8S_NAMESPACE,
             kubeconfig_path=settings.KUBECONFIG_PATH,
+            agent_run_access_key_id=settings.AGENT_RUN_ACCESS_KEY_ID,
+            agent_run_access_key_secret=settings.AGENT_RUN_ACCESS_KEY_SECRET,
+            agent_run_account_id=settings.AGENT_RUN_ACCOUNT_ID,
+            agent_run_region_id=settings.AGENT_RUN_REGION_ID,
+            agent_run_cpu=settings.AGENT_RUN_CPU,
+            agent_run_memory=settings.AGENT_RUN_MEMORY,
+            agent_run_vpc_id=settings.AGENT_RUN_VPC_ID,
+            agent_run_vswitch_ids=settings.AGENT_RUN_VSWITCH_IDS,
+            agent_run_security_group_id=settings.AGENT_RUN_SECURITY_GROUP_ID,
+            agent_run_prefix=settings.AGENT_RUN_PREFIX,
+            agentrun_log_project=settings.AGENT_RUN_LOG_PROJECT,
+            agentrun_log_store=settings.AGENT_RUN_LOG_STORE,
         )
     return _config
 
@@ -134,15 +150,21 @@ def create_endpoint(method):
             logger.info(
                 f"Calling {method.__name__} with data: {data}",
             )
-            result = method(**data)
+
+            # Check if the method is asynchronous
+            if inspect.iscoroutinefunction(method):
+                # If async, just await it
+                result = await method(**data)
+            else:
+                # If sync, run it in a thread to avoid blocking the event loop
+                result = await asyncio.to_thread(method, **data)
+
             if hasattr(result, "model_dump_json"):
                 return JSONResponse(content={"data": result.model_dump_json()})
             return JSONResponse(content={"data": result})
+
         except Exception as e:
-            error = (
-                f"Error in {method.__name__}: {str(e)},"
-                # f" {traceback.format_exc()}"
-            )
+            error = f"Error in {method.__name__}: {str(e)}"
             logger.error(error)
             raise HTTPException(status_code=500, detail=error) from e
 
@@ -194,11 +216,38 @@ async def health_check():
     """Health check endpoint"""
     return HealthResponse(
         status="healthy",
-        version=_sandbox_manager.default_type.value,
+        version=str(_sandbox_manager.default_type),
     )
 
 
-@app.websocket("/browser/{sandbox_id}/cast")
+@app.get("/desktop/{sandbox_id}/{path:path}")
+async def proxy_vnc_static(sandbox_id: str, path: str):
+    container_json = _sandbox_manager.container_mapping.get(sandbox_id)
+    if not container_json:
+        return Response(status_code=404)
+
+    base_url = container_json.get("url")
+    if not base_url:
+        return Response(status_code=404)
+
+    target_url = f"{base_url}/{path}"
+
+    try:
+        async with httpx.AsyncClient() as client:
+            upstream = await client.get(target_url)
+            return Response(
+                content=upstream.content,
+                media_type=upstream.headers.get("content-type"),
+            )
+    except httpx.RequestError as exc:
+        logger.error(f"Upstream request to {target_url} failed: {repr(exc)}")
+        return JSONResponse(
+            status_code=502,
+            content={"detail": f"Upstream request failed: {str(exc)}"},
+        )
+
+
+@app.websocket("/desktop/{sandbox_id}")
 async def websocket_endpoint(
     websocket: WebSocket,
     sandbox_id: str,
@@ -212,7 +261,7 @@ async def websocket_endpoint(
     )
     service_address = None
     if container_json:
-        service_address = container_json.get("front_browser_ws")
+        service_address = http_to_ws(f"{container_json.get('url')}/websockify")
 
     logger.debug(f"service_address: {service_address}")
 
@@ -237,8 +286,17 @@ async def websocket_endpoint(
             # Forward messages from client to target server
             async def forward_to_service():
                 try:
-                    async for message in websocket.iter_text():
-                        await target_ws.send(message)
+                    while True:
+                        message = await websocket.receive()
+
+                        if message["type"] == "websocket.receive":
+                            if "bytes" in message:
+                                await target_ws.send(message["bytes"])
+                            elif "text" in message:
+                                await target_ws.send(message["text"])
+                        elif message["type"] == "websocket.disconnect":
+                            break
+
                 except WebSocketDisconnect:
                     logger.debug(
                         f"WebSocket disconnected from client for sandbox"
@@ -266,9 +324,6 @@ async def websocket_endpoint(
         await websocket.close()
 
 
-# TODO: add socketio relay endpoint for filesystem
-
-
 def setup_logging(log_level: str):
     """Setup logging configuration based on log level"""
     # Convert string to logging level
@@ -311,8 +366,21 @@ def main():
         default="INFO",
         help="Set the logging level (default: INFO)",
     )
+
+    parser.add_argument(
+        "--extension",
+        action="append",
+        help="Path to a Python file or module name to load as an extension",
+    )
+
     args = parser.parse_args()
 
+    if args.extension:
+        for ext in args.extension:
+            logger.info(f"Loading extension: {ext}")
+            mod = dynamic_import(ext)
+            logger.info(f"Extension loaded: {mod.__name__}")
+
     # Setup logging based on command line argument
     setup_logging(args.log_level)
 

agentscope_runtime/sandbox/manager/server/config.py

@@ -1,6 +1,8 @@
 # -*- coding: utf-8 -*-
 import os
-from typing import Optional, Tuple, Literal
+import json
+
+from typing import Optional, Tuple, Literal, Dict, Union, List
 from pydantic_settings import BaseSettings
 from pydantic import field_validator, ConfigDict
 from dotenv import load_dotenv
@@ -17,12 +19,22 @@ class Settings(BaseSettings):
     BEARER_TOKEN: Optional[str] = None
 
     # Runtime Manager settings
-    DEFAULT_SANDBOX_TYPE: str = "base"
+    DEFAULT_SANDBOX_TYPE: Union[str, List[str]] = "base"
     POOL_SIZE: int = 1
     AUTO_CLEANUP: bool = True
     CONTAINER_PREFIX_KEY: str = "runtime_sandbox_container_"
-    CONTAINER_DEPLOYMENT: Literal["docker", "cloud", "k8s"] = "docker"
+    CONTAINER_DEPLOYMENT: Literal[
+        "docker",
+        "cloud",
+        "k8s",
+        "agentrun",
+    ] = "docker"
     DEFAULT_MOUNT_DIR: str = "sessions_mount_dir"
+    # Read-only mounts (host_path -> container_path)
+    # Example in .env:
+    # READONLY_MOUNTS={"\/opt\/shared": "\/mnt\/shared", "\/etc\/timezone":
+    # "\/etc\/timezone"}
+    READONLY_MOUNTS: Optional[Dict[str, str]] = None
     STORAGE_FOLDER: str = "runtime_sandbox_storage"
     PORT_RANGE: Tuple[int, int] = (49152, 59152)
 
@@ -47,6 +59,24 @@ class Settings(BaseSettings):
     K8S_NAMESPACE: str = "default"
     KUBECONFIG_PATH: Optional[str] = None
 
+    # AgentRun settings
+    AGENT_RUN_ACCOUNT_ID: Optional[str] = None
+    AGENT_RUN_ACCESS_KEY_ID: Optional[str] = None
+    AGENT_RUN_ACCESS_KEY_SECRET: Optional[str] = None
+    AGENT_RUN_REGION_ID: str = "cn-hangzhou"
+
+    AGENT_RUN_CPU: float = 2.0
+    AGENT_RUN_MEMORY: int = 2048
+
+    AGENT_RUN_VPC_ID: Optional[str] = None
+    AGENT_RUN_VSWITCH_IDS: Optional[list[str]] = None
+    AGENT_RUN_SECURITY_GROUP_ID: Optional[str] = None
+
+    AGENT_RUN_PREFIX: str = "agentscope-sandbox"
+
+    AGENT_RUN_LOG_PROJECT: Optional[str] = None
+    AGENT_RUN_LOG_STORE: Optional[str] = None
+
     model_config = ConfigDict(
         case_sensitive=True,
         extra="allow",
@@ -59,6 +89,23 @@ class Settings(BaseSettings):
             return 1
         return value
 
+    @field_validator("DEFAULT_SANDBOX_TYPE", mode="before")
+    @classmethod
+    def parse_default_type(cls, v):
+        if isinstance(v, str):
+            v = v.strip()
+            if v.startswith("[") and v.endswith("]"):
+                try:
+                    return json.loads(v)
+                except json.JSONDecodeError:
+                    return [
+                        item.strip()
+                        for item in v[1:-1].split(",")
+                        if item.strip()
+                    ]
+            return [item.strip() for item in v.split(",") if item.strip()]
+        return v
+
 
 _settings: Optional[Settings] = None
 

agentscope_runtime/sandbox/model/container.py

@@ -1,5 +1,5 @@
 # -*- coding: utf-8 -*-
-from typing import List
+from typing import List, Optional, Dict
 
 from pydantic import BaseModel, Field
 
@@ -20,31 +20,12 @@ class ContainerModel(BaseModel):
         description="Human-readable name for the container",
     )
 
-    base_url: str = Field(
+    url: str = Field(
         ...,
-        description="Base URL for accessing the container",
+        description="URL for accessing the container",
     )
 
-    browser_url: str = Field(
-        ...,
-        description="URL for browser interface within the container",
-    )
-
-    front_browser_ws: str = Field(
-        ...,
-        description="WebSocket URL for the browser used by frontend",
-    )
-
-    client_browser_ws: str = Field(
-        ...,
-        description="WebSocket URL for the browser used by runtime client",
-    )
-
-    artifacts_sio: str = Field(
-        ...,
-        description="Socketio URL for the artifacts used by frontend",
-    )
-    ports: List[int] = Field(
+    ports: List[int | str] = Field(
         ...,
         description="List of occupied port numbers",
     )
@@ -70,5 +51,13 @@ class ContainerModel(BaseModel):
         description="Image version of the container",
     )
 
+    meta: Optional[Dict] = Field(default_factory=dict)
+
+    timeout: Optional[int] = Field(
+        None,
+        description="Timeout in seconds for container operations",
+        ge=0,
+    )
+
     class Config:
         extra = "allow"

agentscope_runtime/sandbox/model/manager_config.py

@@ -1,7 +1,7 @@
 # -*- coding: utf-8 -*-
 # pylint: disable=no-self-argument
 import os
-from typing import Optional, Literal, Tuple
+from typing import Optional, Literal, Tuple, Dict
 from pydantic import BaseModel, Field, model_validator
 
 
@@ -27,10 +27,15 @@ class SandboxManagerEnvConfig(BaseModel):
         ...,
         description="Indicates if Redis is enabled.",
     )
-    container_deployment: Literal["docker", "cloud", "k8s"] = Field(
+    container_deployment: Literal[
+        "docker",
+        "cloud",
+        "k8s",
+        "agentrun",
+    ] = Field(
         ...,
-        description="Container deployment backend: 'docker', 'cloud', "
-        "or 'k8s'.",
+        description="Container deployment backend: 'docker', 'cloud', 'k8s'"
+        "or 'agentrun'.",
     )
 
     default_mount_dir: Optional[str] = Field(
@@ -38,6 +43,13 @@ class SandboxManagerEnvConfig(BaseModel):
         description="Path for local file system storage.",
     )
 
+    readonly_mounts: Optional[Dict[str, str]] = Field(
+        default=None,
+        description="Read-only mount mapping: host_path -> container_path. "
+        "Example: { '/data/shared': '/mnt/shared', '/etc/timezone': "
+        "'/etc/timezone' }",
+    )
+
     port_range: Tuple[int, int] = Field(
         (49152, 59152),
         description="Range of ports to be used by the manager.",
@@ -112,8 +124,64 @@ class SandboxManagerEnvConfig(BaseModel):
         "in-cluster config or default kubeconfig.",
     )
 
+    # AgentRun settings
+    agent_run_access_key_id: Optional[str] = Field(
+        None,
+        description="Access key ID for AgentRun. Required if "
+        "container_deployment is 'agentrun'.",
+    )
+    agent_run_access_key_secret: Optional[str] = Field(
+        None,
+        description="Access key secret for AgentRun. "
+        "Required if container_deployment is 'agentrun'.",
+    )
+    agent_run_account_id: Optional[str] = Field(
+        None,
+        description="Account ID for AgentRun. Required if "
+        "container_deployment is 'agentrun'.",
+    )
+    agent_run_region_id: str = Field(
+        "cn-hangzhou",
+        description="Region ID for AgentRun.",
+    )
+    agent_run_cpu: float = Field(
+        2,
+        description="CPU allocation for AgentRun containers.",
+    )
+    agent_run_memory: int = Field(
+        2048,
+        description="Memory allocation for AgentRun containers in MB.",
+    )
+    agent_run_vpc_id: Optional[str] = Field(
+        None,
+        description="VPC ID for AgentRun. Required if container_deployment "
+        "is 'agentrun'.",
+    )
+    agent_run_vswitch_ids: Optional[list[str]] = Field(
+        None,
+        description="VSwitch IDs for AgentRun. Required if "
+        "container_deployment is 'agentrun'.",
+    )
+    agent_run_security_group_id: Optional[str] = Field(
+        None,
+        description="Security group ID for AgentRun. "
+        "Required if container_deployment is 'agentrun'.",
+    )
+    agent_run_prefix: str = Field(
+        "agentscope-sandbox_",
+        description="Prefix for AgentRun resources.",
+    )
+    agentrun_log_project: Optional[str] = Field(
+        None,
+        description="Log project for AgentRun.",
+    )
+    agentrun_log_store: Optional[str] = Field(
+        None,
+        description="Log store for AgentRun.",
+    )
+
     @model_validator(mode="after")
-    def check_settings(cls, self):
+    def check_settings(self):
         if self.default_mount_dir:
             os.makedirs(self.default_mount_dir, exist_ok=True)
 
@@ -161,4 +229,24 @@ class SandboxManagerEnvConfig(BaseModel):
                         f"{field_name} must be set when redis is enabled",
                     )
 
+        if self.container_deployment == "agentrun":
+            required_agentrun_fields = [
+                self.agent_run_access_key_id,
+                self.agent_run_access_key_secret,
+                self.agent_run_account_id,
+            ]
+            for field_name, field_value in zip(
+                [
+                    "agent_run_access_key_id",
+                    "agent_run_access_key_secret",
+                    "agent_run_account_id",
+                ],
+                required_agentrun_fields,
+            ):
+                if not field_value:
+                    raise ValueError(
+                        f"{field_name} must be set when "
+                        f"container_deployment is 'agentrun'",
+                    )
+
         return self

agentscope_runtime/sandbox/registry.py

@@ -42,7 +42,7 @@ class SandboxRegistry:
         sandbox_type: SandboxType | str,
         resource_limits: Dict = None,
         security_level: str = "medium",  # Not used for now
-        timeout: int = 300,
+        timeout: int = 60,
         description: str = "",
         environment: Dict = None,
         runtime_config: Optional[Dict] = None,

agentscope_runtime/sandbox/tools/gui/__init__.py

@@ -0,0 +1,7 @@
+# -*- coding: utf-8 -*-
+from .tool import computer_use
+
+
+__all__ = [
+    "computer_use",
+]

agentscope_runtime/sandbox/tools/gui/tool.py

@@ -0,0 +1,77 @@
+# -*- coding: utf-8 -*-
+# flake8: noqa: E501
+# pylint: disable=line-too-long
+from typing import Dict
+
+from ..sandbox_tool import SandboxTool
+
+
+class ComputerUseTool(SandboxTool):
+    """
+    Use a mouse and keyboard to interact with a computer, and take screenshots.
+    """
+
+    _name: str = "computer"
+    _sandbox_type: str = "gui"
+    _tool_type: str = "computer_use"
+    _schema: Dict = {
+        "name": "computer",
+        "description": (
+            "Use a mouse and keyboard to interact with a computer, and take screenshots.\n"
+            "* 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.\n"
+            "* Always prefer using keyboard shortcuts rather than clicking, where possible.\n"
+            "* 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.\n"
+            "* 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. E.g. if you click on Firefox and a window doesn't open, try taking another screenshot.\n"
+            "* Whenever you intend to move the cursor to click on an element like an icon, you should consult a screenshot to determine the coordinates of the element before moving the cursor.\n"
+            "* If you tried clicking on a program or link but it failed to load, even after waiting, try adjusting your cursor position so that the tip of the cursor visually falls on the element that you want to click.\n"
+            "* 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."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": [
+                        "key",
+                        "type",
+                        "mouse_move",
+                        "left_click",
+                        "left_click_drag",
+                        "right_click",
+                        "middle_click",
+                        "double_click",
+                        "get_screenshot",
+                        "get_cursor_position",
+                    ],
+                    "description": (
+                        "The action to perform. The available actions are:\n"
+                        "* key: Press a key or key-combination on the keyboard.\n"
+                        "* type: Type a string of text on the keyboard.\n"
+                        "* get_cursor_position: Get the current (x, y) pixel coordinate of the cursor on the screen.\n"
+                        "* mouse_move: Move the cursor to a specified (x, y) pixel coordinate on the screen.\n"
+                        "* left_click: Click the left mouse button.\n"
+                        "* left_click_drag: Click and drag the cursor to a specified (x, y) pixel coordinate on the screen.\n"
+                        "* right_click: Click the right mouse button.\n"
+                        "* middle_click: Click the middle mouse button.\n"
+                        "* double_click: Double-click the left mouse button.\n"
+                        "* get_screenshot: Take a screenshot of the screen."
+                    ),
+                },
+                "coordinate": {
+                    "type": "array",
+                    "items": {"type": "number"},
+                    "minItems": 2,
+                    "maxItems": 2,
+                    "description": "(x, y): The x (pixels from the left edge) and y (pixels from the top edge) coordinates",
+                },
+                "text": {
+                    "type": "string",
+                    "description": "Text to type or key command to execute",
+                },
+            },
+            "required": ["action"],
+        },
+    }
+
+
+computer_use = ComputerUseTool()

agentscope_runtime/sandbox/tools/mcp_tool.py

@@ -119,6 +119,7 @@ class MCPConfigConverter:
         self,
         *,
         sandbox: Optional[Sandbox] = None,
+        sandbox_type: Optional[SandboxType | str] = None,
     ) -> List[MCPTool]:
         """
         Converts to a list of MCPTool instances.
@@ -130,7 +131,10 @@ class MCPConfigConverter:
         if box is None:
             from ..registry import SandboxRegistry
 
-            cls_ = SandboxRegistry.get_classes_by_type("base")
+            if sandbox_type is None:
+                sandbox_type = SandboxType.BASE
+
+            cls_ = SandboxRegistry.get_classes_by_type(sandbox_type)
             # Use proper context manager
             with cls_() as tmp_box:
                 return self._process_tools(tmp_box)
@@ -156,7 +160,7 @@ class MCPConfigConverter:
                     MCPTool(
                         sandbox=box,
                         name=tool_name,
-                        sandbox_type=SandboxType.BASE,
+                        sandbox_type=box.sandbox_type,
                         tool_type=server_name,
                         schema=tool_info["json_schema"]["function"],
                         server_configs={

agentscope_runtime/sandbox/tools/tool.py

@@ -37,6 +37,10 @@ class Tool(ABC):
         self._name = name
         self._tool_type = tool_type
 
+    @property
+    def __name__(self) -> str:
+        return self.name
+
     @property
     @abstractmethod
     def name(self) -> str: