agentrun-sdk 0.0.4__py3-none-any.whl

agentrun/sandbox/__sandbox_async_template.py

@@ -0,0 +1,398 @@
+"""Sandbox 高层 API / Sandbox High-Level API
+
+此模块定义沙箱资源的高级API。
+This module defines the high-level API for sandbox resources.
+"""
+
+from typing import List, Literal, Optional, overload, TYPE_CHECKING, Union
+
+from agentrun.sandbox.model import TemplateType
+from agentrun.utils.config import Config
+from agentrun.utils.model import BaseModel
+
+if TYPE_CHECKING:
+    from agentrun.sandbox.browser_sandbox import BrowserSandbox
+    from agentrun.sandbox.code_interpreter_sandbox import CodeInterpreterSandbox
+    from agentrun.sandbox.model import (
+        ListSandboxesInput,
+        ListSandboxesOutput,
+        PageableInput,
+        TemplateInput,
+    )
+    from agentrun.sandbox.template import Template
+
+
+class Sandbox(BaseModel):
+    """Sandbox 实例
+
+    封装了 Sandbox 的基本信息和操作方法
+    """
+
+    _template_type: Optional[TemplateType]
+
+    created_at: Optional[str] = None
+    """沙箱创建时间"""
+    last_updated_at: Optional[str] = None
+    """最后更新时间"""
+    sandbox_arn: Optional[str] = None
+    """沙箱全局唯一资源名称"""
+    sandbox_id: Optional[str] = None
+    """沙箱 ID"""
+    sandbox_idle_timeout_seconds: Optional[int] = None
+    """沙箱空闲超时时间（秒）"""
+    status: Optional[str] = None
+    """沙箱状态"""
+    template_id: Optional[str] = None
+    """模板 ID"""
+    template_name: Optional[str] = None
+    """模板名称"""
+    _config: Optional[Config] = None
+    """配置对象，用于子类的 data_api 初始化"""
+
+    @classmethod
+    def __get_client(cls):
+        """获取 Sandbox 客户端"""
+        from .client import SandboxClient
+
+        return SandboxClient()
+
+    @classmethod
+    @overload
+    async def create_async(
+        cls,
+        template_type: Literal[TemplateType.CODE_INTERPRETER],
+        template_name: Optional[str] = None,
+        sandbox_idle_timeout_seconds: Optional[int] = 600,
+        config: Optional[Config] = None,
+    ) -> "CodeInterpreterSandbox":
+        ...
+
+    @classmethod
+    @overload
+    async def create_async(
+        cls,
+        template_type: Literal[TemplateType.BROWSER],
+        template_name: Optional[str] = None,
+        sandbox_idle_timeout_seconds: Optional[int] = 600,
+        config: Optional[Config] = None,
+    ) -> "BrowserSandbox":
+        ...
+
+    @classmethod
+    async def create_async(
+        cls,
+        template_type: TemplateType,
+        template_name: Optional[str] = None,
+        sandbox_idle_timeout_seconds: Optional[int] = 600,
+        config: Optional[Config] = None,
+    ) -> Union["CodeInterpreterSandbox", "BrowserSandbox"]:
+
+        if template_name is None:
+            # todo 可以考虑为用户创建一个模板？
+            raise ValueError("template_name is required")
+
+        # 先根据传入的template_name，获取template的类型
+        template = await cls.get_template_async(template_name, config=config)
+
+        # 根据 template 类型创建相应的 Sandbox 子类
+        from agentrun.sandbox.browser_sandbox import BrowserSandbox
+        from agentrun.sandbox.code_interpreter_sandbox import (
+            CodeInterpreterSandbox,
+        )
+
+        if template_type != template.template_type:
+            raise ValueError(
+                f"template_type of {template_name} is {template.template_type},"
+                f" not {template_type}"
+            )
+
+        # 创建 Sandbox（返回基类实例）
+        base_sandbox = await cls.__get_client().create_sandbox_async(
+            template_name=template_name,
+            sandbox_idle_timeout_seconds=sandbox_idle_timeout_seconds,
+        )
+
+        # 根据 template 类型转换为对应的子类实例
+        sandbox = None
+        if template.template_type == TemplateType.CODE_INTERPRETER:
+            sandbox = CodeInterpreterSandbox.model_validate(
+                base_sandbox.model_dump(by_alias=False)
+            )
+        elif template.template_type == TemplateType.BROWSER:
+            sandbox = BrowserSandbox.model_validate(
+                base_sandbox.model_dump(by_alias=False)
+            )
+        else:
+            raise ValueError(
+                f"template_type {template.template_type} is not supported"
+            )
+
+        sandbox._config = config
+        return sandbox
+
+    @classmethod
+    async def stop_by_id_async(cls, sandbox_id: str):
+        """通过 ID 停止 Sandbox（异步）
+
+        Args:
+            sandbox_id: Sandbox ID
+            config: 配置对象
+
+        Returns:
+            Sandbox: Sandbox 对象
+        """
+        if sandbox_id is None:
+            raise ValueError("sandbox_id is required")
+        # todo 后续适配后使用 stop()
+        return await cls.__get_client().delete_sandbox_async(sandbox_id)
+
+    @classmethod
+    async def delete_by_id_async(cls, sandbox_id: str):
+        """通过 ID 删除 Sandbox（异步）
+
+        Args:
+            sandbox_id: Sandbox ID
+            config: 配置对象
+
+        Returns:
+            Sandbox: Sandbox 对象
+        """
+        if sandbox_id is None:
+            raise ValueError("sandbox_id is required")
+        return await cls.__get_client().delete_sandbox_async(sandbox_id)
+
+    @classmethod
+    async def list_async(
+        cls,
+        input: Optional["ListSandboxesInput"] = None,
+        config: Optional[Config] = None,
+    ) -> "ListSandboxesOutput":
+        """列出 Sandboxes（异步）
+
+        Args:
+            input: 列表查询配置
+            config: 配置对象
+
+        Returns:
+            ListSandboxesOutput: Sandbox 列表结果
+        """
+        return await cls.__get_client().list_sandboxes_async(input, config)
+
+    @classmethod
+    @overload
+    async def connect_async(
+        cls,
+        sandbox_id: str,
+        template_type: Literal[TemplateType.CODE_INTERPRETER],
+        config: Optional[Config] = None,
+    ) -> "CodeInterpreterSandbox":
+        ...
+
+    @classmethod
+    @overload
+    async def connect_async(
+        cls,
+        sandbox_id: str,
+        template_type: Literal[TemplateType.BROWSER],
+        config: Optional[Config] = None,
+    ) -> "BrowserSandbox":
+        ...
+
+    @classmethod
+    @overload
+    async def connect_async(
+        cls,
+        sandbox_id: str,
+        template_type: None = None,
+        config: Optional[Config] = None,
+    ) -> Union["CodeInterpreterSandbox", "BrowserSandbox"]:
+        ...
+
+    @classmethod
+    async def connect_async(
+        cls,
+        sandbox_id: str,
+        template_type: Optional[TemplateType] = None,
+        config: Optional[Config] = None,
+    ) -> Union["CodeInterpreterSandbox", "BrowserSandbox"]:
+        """连接一个SandBox（异步）
+
+        Args:
+            sandbox_id: Sandbox ID
+            type: 可选的类型参数，用于类型提示和运行时验证
+            config: 配置对象
+
+        Returns:
+            Sandbox: 根据模板类型返回对应的 Sandbox 子类对象
+
+        Raises:
+            ValueError: 如果模板类型不支持或与预期类型不匹配
+        """
+        if sandbox_id is None:
+            raise ValueError("sandbox_id is required")
+
+        # 先获取 sandbox 信息
+        sandbox = await cls.__get_client().get_sandbox_async(
+            sandbox_id, config=config
+        )
+
+        # 根据 template_name 获取 template 类型
+        if sandbox.template_name is None:
+            raise ValueError(f"Sandbox {sandbox_id} has no template_name")
+
+        template = await cls.get_template_async(
+            sandbox.template_name, config=config
+        )
+
+        # 如果提供了 type 参数，验证类型是否匹配
+        if (
+            template_type is not None
+            and template.template_type != template_type
+        ):
+            raise ValueError(
+                f"Sandbox {sandbox_id} has template type"
+                f" {template.template_type}, but expected {template_type}"
+            )
+
+        # 根据 template 类型创建相应的 Sandbox 子类
+        from agentrun.sandbox.browser_sandbox import BrowserSandbox
+        from agentrun.sandbox.code_interpreter_sandbox import (
+            CodeInterpreterSandbox,
+        )
+
+        result = None
+        if template.template_type == TemplateType.CODE_INTERPRETER:
+            result = CodeInterpreterSandbox.model_validate(
+                sandbox.model_dump(by_alias=False)
+            )
+        elif template.template_type == TemplateType.BROWSER:
+            result = BrowserSandbox.model_validate(
+                sandbox.model_dump(by_alias=False)
+            )
+        else:
+            raise ValueError(
+                f"Unsupported template type: {template.template_type}. "
+                "Expected 'code-interpreter' or 'browser'"
+            )
+
+        result._config = config
+        return result
+
+    # ==================== Template 相关类方法 ====================
+
+    @classmethod
+    async def create_template_async(
+        cls, input: "TemplateInput", config: Optional[Config] = None
+    ) -> "Template":
+        """创建 Template（异步）
+
+        Args:
+            input: Template 配置
+            config: 配置对象
+
+        Returns:
+            Template: 创建的 Template 对象
+        """
+        if input.template_type is None:
+            raise ValueError("template_type is required")
+        return await cls.__get_client().create_template_async(
+            input, config=config
+        )
+
+    @classmethod
+    async def get_template_async(
+        cls, template_name: str, config: Optional[Config] = None
+    ) -> "Template":
+        """获取 Template（异步）
+
+        Args:
+            template_name: Template 名称
+            config: 配置对象
+
+        Returns:
+            Template: Template 对象
+        """
+        if template_name is None:
+            raise ValueError("template_name is required")
+        return await cls.__get_client().get_template_async(
+            template_name, config=config
+        )
+
+    @classmethod
+    async def update_template_async(
+        cls,
+        template_name: str,
+        input: "TemplateInput",
+        config: Optional[Config] = None,
+    ) -> "Template":
+        """更新 Template（异步）
+
+        Args:
+            template_name: Template 名称
+            input: Template 更新配置
+            config: 配置对象
+
+        Returns:
+            Template: 更新后的 Template 对象
+        """
+        if template_name is None:
+            raise ValueError("template_name is required")
+        return await cls.__get_client().update_template_async(
+            template_name, input, config=config
+        )
+
+    @classmethod
+    async def delete_template_async(
+        cls, template_name: str, config: Optional[Config] = None
+    ) -> "Template":
+        """删除 Template（异步）
+
+        Args:
+            template_name: Template 名称
+            config: 配置对象
+
+        Returns:
+            Template: 删除的 Template 对象
+        """
+        if template_name is None:
+            raise ValueError("template_name is required")
+        return await cls.__get_client().delete_template_async(
+            template_name, config=config
+        )
+
+    @classmethod
+    async def list_templates_async(
+        cls,
+        input: Optional["PageableInput"] = None,
+        config: Optional[Config] = None,
+    ) -> List["Template"]:
+        """列出 Templates（异步）
+
+        Args:
+            input: 分页配置
+            config: 配置对象
+
+        Returns:
+            List[Template]: Template 列表
+        """
+        return await cls.__get_client().list_templates_async(
+            input, config=config
+        )
+
+    async def get_async(self):
+        if self.sandbox_id is None:
+            raise ValueError("sandbox_id is required to get a Sandbox")
+
+        return await self.connect_async(self.sandbox_id)
+
+    async def delete_async(self):
+        if self.sandbox_id is None:
+            raise ValueError("sandbox_id is required to delete a Sandbox")
+
+        return await self.delete_by_id_async(self.sandbox_id)
+
+    async def stop_async(self):
+        if self.sandbox_id is None:
+            raise ValueError("sandbox_id is required to stop a Sandbox")
+        # todo 后续适配后使用 stop()
+        return await self.delete_by_id_async(self.sandbox_id)

agentrun/sandbox/__template_async_template.py

@@ -0,0 +1,150 @@
+"""Template 高层 API / Template High-Level API
+
+此模块定义沙箱模板资源的高级API。
+This module defines the high-level API for sandbox template resources.
+"""
+
+from typing import Dict, List, Optional
+
+from agentrun.sandbox.model import (
+    PageableInput,
+    TemplateContainerConfiguration,
+    TemplateCredentialConfiguration,
+    TemplateInput,
+    TemplateLogConfiguration,
+    TemplateMcpOptions,
+    TemplateMcpState,
+    TemplateNetworkConfiguration,
+    TemplateOssConfiguration,
+    TemplateType,
+)
+from agentrun.utils.config import Config
+from agentrun.utils.model import BaseModel
+
+
+class Template(BaseModel):
+    """Template 实例
+
+    封装了 Template 的基本信息和操作方法
+    """
+
+    template_id: Optional[str] = None
+    """模板 ID"""
+    template_name: Optional[str] = None
+    """模板名称"""
+    template_version: Optional[str] = None
+    """模板版本"""
+    template_arn: Optional[str] = None
+    """模板 ARN"""
+    resource_name: Optional[str] = None
+    """资源名称"""
+    template_type: Optional[TemplateType] = None
+    """模板类型"""
+    cpu: Optional[float] = None
+    """CPU 核数"""
+    memory: Optional[int] = None
+    """内存大小（MB）"""
+    disk_size: Optional[int] = None
+    """磁盘大小（GB）"""
+    description: Optional[str] = None
+    """描述"""
+    execution_role_arn: Optional[str] = None
+    """执行角色 ARN"""
+    sandbox_idle_timeout_in_seconds: Optional[int] = None
+    """沙箱空闲超时时间（秒）"""
+    sandbox_ttlin_seconds: Optional[int] = None
+    """沙箱存活时间（秒）"""
+    share_concurrency_limit_per_sandbox: Optional[int] = None
+    """每个沙箱的最大并发会话数"""
+    template_configuration: Optional[Dict] = None
+    """模板配置"""
+    environment_variables: Optional[Dict] = None
+    """环境变量"""
+    network_configuration: Optional[TemplateNetworkConfiguration] = None
+    """网络配置"""
+    oss_configuration: Optional[List[TemplateOssConfiguration]] = None
+    """OSS 配置列表"""
+    log_configuration: Optional[TemplateLogConfiguration] = None
+    """日志配置"""
+    credential_configuration: Optional[TemplateCredentialConfiguration] = None
+    """凭证配置"""
+    container_configuration: Optional[TemplateContainerConfiguration] = None
+    """容器配置"""
+    mcp_options: Optional[TemplateMcpOptions] = None
+    """MCP 选项"""
+    mcp_state: Optional[TemplateMcpState] = None
+    """MCP 状态"""
+    created_at: Optional[str] = None
+    """创建时间"""
+    last_updated_at: Optional[str] = None
+    """最后更新时间"""
+    status: Optional[str] = None
+    """状态"""
+    status_reason: Optional[str] = None
+    """状态原因"""
+
+    @classmethod
+    def __get_client(cls, config: Optional[Config] = None):
+        """获取 Sandbox 客户端"""
+        from .client import SandboxClient
+
+        return SandboxClient(config)
+
+    @classmethod
+    async def create_async(
+        cls, input: TemplateInput, config: Optional[Config] = None
+    ):
+        return await cls.__get_client(config=config).create_template_async(
+            input, config=config
+        )
+
+    @classmethod
+    async def delete_by_name_async(
+        cls, template_name: str, config: Optional[Config] = None
+    ):
+        return await cls.__get_client(config=config).delete_template_async(
+            template_name=template_name, config=config
+        )
+
+    @classmethod
+    async def update_by_name_async(
+        cls,
+        template_name: str,
+        input: TemplateInput,
+        config: Optional[Config] = None,
+    ):
+        return await cls.__get_client(config=config).update_template_async(
+            template_name=template_name, input=input, config=config
+        )
+
+    @classmethod
+    async def get_by_name_async(
+        cls, template_name: str, config: Optional[Config] = None
+    ):
+        return await cls.__get_client(config=config).get_template_async(
+            template_name=template_name, config=config
+        )
+
+    @classmethod
+    async def list_templates_async(
+        cls,
+        input: Optional[PageableInput] = None,
+        config: Optional[Config] = None,
+    ):
+        return await cls.__get_client(config=config).list_templates_async(
+            input, config=config
+        )
+
+    async def create_sandbox_async(
+        self,
+        sandbox_idle_timeout_seconds: Optional[int] = None,
+        config: Optional[Config] = None,
+    ):
+        if self.template_name is None:
+            raise ValueError("Template name is required")
+
+        return await self.__get_client(config=config).create_sandbox_async(
+            self.template_name,
+            sandbox_idle_timeout_seconds=sandbox_idle_timeout_seconds,
+            config=config,
+        )

agentrun/sandbox/api/__browser_data_async_template.py

@@ -0,0 +1,140 @@
+"""浏览器沙箱数据API模板 / Browser Sandbox Data API Template
+
+此模板用于生成浏览器沙箱数据API代码。
+This template is used to generate browser sandbox data API code.
+"""
+
+from typing import Optional
+from urllib.parse import parse_qs, urlencode, urlparse
+
+from agentrun.utils.config import Config
+
+from .sandbox_data import SandboxDataAPI
+
+
+class BrowserDataAPI(SandboxDataAPI):
+
+    def __init__(
+        self,
+        sandbox_id: str,
+        config: Optional[Config] = None,
+    ):
+        self.sandbox_id = sandbox_id
+        super().__init__(
+            sandbox_id=sandbox_id,
+            config=config,
+        )
+
+    def get_cdp_url(self, record: Optional[bool] = False):
+        """
+        Generate the WebSocket URL for Chrome DevTools Protocol (CDP) connection.
+
+        This method constructs a WebSocket URL by:
+        1. Converting the HTTP endpoint to WebSocket protocol (ws://)
+        2. Parsing the existing URL and query parameters
+        3. Adding the session ID to the query parameters
+        4. Reconstructing the complete WebSocket URL
+
+        Returns:
+            str: The complete WebSocket URL for CDP automation connection,
+                 including the session ID in the query parameters.
+
+        Example:
+            >>> api = BrowserDataAPI("browser123", "session456")
+            >>> api.get_cdp_url()
+            'ws://example.com/ws/automation?sessionId=session456'
+        """
+        cdp_url = self.with_path("/ws/automation").replace("http", "ws")
+        u = urlparse(cdp_url)
+        query_dict = parse_qs(u.query)
+        query_dict["tenantId"] = [self.config.get_account_id()]
+        if record:
+            query_dict["recording"] = ["true"]
+        new_query = urlencode(query_dict, doseq=True)
+        new_u = u._replace(query=new_query)
+        return new_u.geturl()
+
+    def get_vnc_url(self, record: Optional[bool] = False):
+        """
+        Generate the WebSocket URL for VNC (Virtual Network Computing) live view connection.
+
+        This method constructs a WebSocket URL for real-time browser viewing by:
+        1. Converting the HTTP endpoint to WebSocket protocol (ws://)
+        2. Parsing the existing URL and query parameters
+        3. Adding the session ID to the query parameters
+        4. Reconstructing the complete WebSocket URL
+
+        Returns:
+            str: The complete WebSocket URL for VNC live view connection,
+                 including the session ID in the query parameters.
+
+        Example:
+            >>> api = BrowserDataAPI("browser123", "session456")
+            >>> api.get_vnc_url()
+            'ws://example.com/ws/liveview?sessionId=session456'
+        """
+        vnc_url = self.with_path("/ws/liveview").replace("http", "ws")
+        u = urlparse(vnc_url)
+        query_dict = parse_qs(u.query)
+        query_dict["tenantId"] = [self.config.get_account_id()]
+        if record:
+            query_dict["recording"] = ["true"]
+        new_query = urlencode(query_dict, doseq=True)
+        new_u = u._replace(query=new_query)
+        return new_u.geturl()
+
+    def sync_playwright(
+        self,
+        browser_type: str = "chrome",
+        record: Optional[bool] = False,
+        config: Optional[Config] = None,
+    ):
+        from .playwright_sync import BrowserPlaywrightSync
+
+        cfg = Config.with_configs(self.config, config)
+        _, headers, _ = self.auth(headers=cfg.get_headers(), config=cfg)
+        return BrowserPlaywrightSync(
+            self.get_cdp_url(record=record),
+            browser_type=browser_type,
+            headers=headers,
+        )
+
+    def async_playwright(
+        self,
+        browser_type: str = "chrome",
+        record: Optional[bool] = False,
+        config: Optional[Config] = None,
+    ):
+        from .playwright_async import BrowserPlaywrightAsync
+
+        cfg = Config.with_configs(self.config, config)
+        _, headers, _ = self.auth(headers=cfg.get_headers(), config=cfg)
+        return BrowserPlaywrightAsync(
+            self.get_cdp_url(record=record),
+            browser_type=browser_type,
+            headers=headers,
+        )
+
+    async def list_recordings_async(self):
+        return await self.get_async("/recordings")
+
+    async def delete_recording_async(self, filename: str):
+        return await self.delete_async(f"/recordings/{filename}")
+
+    async def download_recording_async(self, filename: str, save_path: str):
+        """
+        Asynchronously download a recording video file and save it to local path.
+
+        Args:
+            filename: The name of the recording file to download
+            save_path: Local file path to save the downloaded video file (.mkv)
+
+        Returns:
+            Dictionary with 'saved_path' and 'size' keys
+
+        Examples:
+            >>> await api.download_recording_async("recording.mp4", "/local/video.mkv")
+        """
+        return await self.get_video_async(
+            f"/recordings/{filename}", save_path=save_path
+        )