agentlink-sdk 1.0.0__py3-none-any.whl

agentlink_sdk/__init__.py

@@ -0,0 +1,87 @@
+"""
+AgentLink Python SDK
+
+Official Python SDK for China Mobile Cloud AgentLink MCP Gateway.
+Provides sandbox lifecycle management, browser automation, desktop control,
+and tool invocation capabilities.
+
+Usage::
+
+    from agentlink_sdk import AgentLink
+
+    al = AgentLink(api_key="your-api-key")
+
+    # Browser automation
+    al.browser.go("https://www.baidu.com")
+    shot = al.browser.capture()
+    shot.save("page.png")
+
+    # Windows desktop control
+    al.desktop.shell("Get-Date")
+    al.desktop.capture().save("desktop.png")
+
+    # Clean up
+    al.cleanup()
+"""
+
+__version__ = "1.0.0"
+
+from .client import AgentLink
+from .browser import BrowserController
+from .desktop import DesktopController
+from .config import AgentLinkConfig
+from .models.sandbox import SandboxSession, SandboxType, IMAGE_BROWSER, IMAGE_WINDOWS
+from .models.results import (
+    ActionResult,
+    Screenshot,
+    SandboxResult,
+    ToolResult,
+)
+from .exceptions import (
+    AgentLinkError,
+    AgentLinkTimeoutError,
+    ConfigurationError,
+    SandboxError,
+    ToolCallError,
+    SessionError,
+    TransportError,
+    TimeoutError,
+    BrowserError,
+    CommandError,
+    FileSystemError,
+)
+from .logger import set_log_level
+
+__all__ = [
+    "__version__",
+    # Client & controllers
+    "AgentLink",
+    "BrowserController",
+    "DesktopController",
+    # Config
+    "AgentLinkConfig",
+    # Models
+    "SandboxSession",
+    "SandboxType",
+    "IMAGE_BROWSER",
+    "IMAGE_WINDOWS",
+    # Results
+    "ActionResult",
+    "Screenshot",
+    "SandboxResult",
+    "ToolResult",
+    # Exceptions
+    "AgentLinkError",
+    "ConfigurationError",
+    "SandboxError",
+    "ToolCallError",
+    "SessionError",
+    "TransportError",
+    "AgentLinkTimeoutError",
+    "TimeoutError",
+    "BrowserError",
+    "CommandError",
+    "FileSystemError",
+    # Utilities
+    "set_log_level",
+]

agentlink_sdk/browser.py

@@ -0,0 +1,617 @@
+"""
+Browser automation controller.
+
+Wraps the browser sandbox MCP tools into a fluent Python API for
+web navigation, element interaction, screenshots, and JS evaluation.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from .models.results import ActionResult, Screenshot
+from .models.sandbox import IMAGE_BROWSER
+
+# Avoid circular import at runtime; type-checkers resolve via TYPE_CHECKING.
+from typing import TYPE_CHECKING
+if TYPE_CHECKING:
+    from .client import AgentLink
+
+
+class BrowserController:
+    """
+    Browser automation controller.
+
+    Wraps the browser sandbox MCP tools into a fluent Python API for
+    web navigation, element interaction, screenshots, and JS evaluation.
+    """
+
+    def __init__(self, client: AgentLink, image_id: str = IMAGE_BROWSER):
+        self._client = client
+        self._image_id = image_id
+
+    # ---- Navigation ----
+
+    def go(self, url: str, *, sandbox_id: Optional[str] = None) -> ActionResult:
+        """
+        Navigate to *url* in the browser.
+
+        Args:
+            url: Target URL.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Navigation outcome.
+        """
+        args: Dict[str, Any] = {"url": url}
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_navigate", args)
+
+    def back(self, *, sandbox_id: Optional[str] = None) -> ActionResult:
+        """Go back to the previous page in browser history.
+
+        Returns:
+            ActionResult: Navigation outcome.
+        """
+        args: Dict[str, Any] = {}
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_navigate_back", args)
+
+    # ---- Snapshot & Screenshot ----
+
+    def a11y_tree(
+        self,
+        *,
+        filename: Optional[str] = None,
+        depth: Optional[int] = None,
+        sandbox_id: Optional[str] = None,
+    ) -> ActionResult:
+        """
+        Capture an accessibility tree of the current page.
+
+        Each interactive element is tagged with a numeric ``ref`` that
+        can be passed to :meth:`click` / :meth:`fill`.
+
+        Args:
+            filename: Save snapshot to markdown file instead of returning inline.
+            depth: Limit the depth of the snapshot tree.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Accessibility text in ``.text``.
+        """
+        args: Dict[str, Any] = {}
+        if filename is not None:
+            args["filename"] = filename
+        if depth is not None:
+            args["depth"] = depth
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_snapshot", args)
+
+    def capture(
+        self,
+        *,
+        img_type: str = "png",
+        filename: Optional[str] = None,
+        element: Optional[str] = None,
+        ref: Optional[str] = None,
+        full_page: bool = False,
+        sandbox_id: Optional[str] = None,
+    ) -> Screenshot:
+        """
+        Capture a screenshot of the current browser page.
+
+        Args:
+            img_type: Image format (``"png"`` or ``"jpeg"``).
+            filename: File name to save the screenshot to.
+            element: Human-readable element description for element screenshot.
+            ref: Element reference for element screenshot.
+            full_page: Take screenshot of full scrollable page.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            Screenshot: Image payload saveable via ``.save(path)``.
+        """
+        args: Dict[str, Any] = {"type": img_type}
+        if filename is not None:
+            args["filename"] = filename
+        if element is not None:
+            args["element"] = element
+        if ref is not None:
+            args["ref"] = ref
+        if full_page:
+            args["fullPage"] = True
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+
+        result = self._client._invoke_raw(self._image_id, "browser_take_screenshot", args)
+        return Screenshot.from_mcp(result)
+
+    # ---- Element Interaction ----
+
+    def click(
+        self,
+        ref: str,
+        *,
+        element: Optional[str] = None,
+        double_click: bool = False,
+        button: str = "left",
+        modifiers: Optional[List[str]] = None,
+        sandbox_id: Optional[str] = None,
+    ) -> ActionResult:
+        """
+        Click on an element identified by its accessibility ``ref``.
+
+        Call :meth:`a11y_tree` first to discover element refs.
+
+        Args:
+            ref: Element reference from the accessibility tree.
+            element: Human-readable element description.
+            double_click: Perform double click.
+            button: ``"left"``, ``"right"``, or ``"middle"``.
+            modifiers: Modifier keys (e.g. ``["Shift", "Control"]``).
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Click outcome.
+        """
+        args: Dict[str, Any] = {"target": ref}
+        if element is not None:
+            args["element"] = element
+        if double_click:
+            args["doubleClick"] = True
+        if button != "left":
+            args["button"] = button
+        if modifiers:
+            args["modifiers"] = modifiers
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_click", args)
+
+    def hover(self, ref: str, *, element: Optional[str] = None, sandbox_id: Optional[str] = None) -> ActionResult:
+        """Hover over an element.
+
+        Args:
+            ref: Element reference from the accessibility tree.
+            element: Human-readable element description.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Hover outcome.
+        """
+        args: Dict[str, Any] = {"target": ref}
+        if element is not None:
+            args["element"] = element
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_hover", args)
+
+    def drag(
+        self,
+        start_ref: str,
+        end_ref: str,
+        *,
+        start_element: Optional[str] = None,
+        end_element: Optional[str] = None,
+        sandbox_id: Optional[str] = None,
+    ) -> ActionResult:
+        """Drag and drop between two elements.
+
+        Args:
+            start_ref: Source element reference.
+            end_ref: Target element reference.
+            start_element: Human-readable source element description.
+            end_element: Human-readable target element description.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Drag outcome.
+        """
+        args: Dict[str, Any] = {
+            "startTarget": start_ref,
+            "endTarget": end_ref,
+        }
+        if start_element is not None:
+            args["startElement"] = start_element
+        if end_element is not None:
+            args["endElement"] = end_element
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_drag", args)
+
+    # ---- Typing & Form ----
+
+    def fill(
+        self,
+        ref: str,
+        text: str,
+        *,
+        element: Optional[str] = None,
+        submit: bool = False,
+        slowly: bool = False,
+        sandbox_id: Optional[str] = None,
+    ) -> ActionResult:
+        """
+        Type *text* into the input element identified by ``ref``.
+
+        Args:
+            ref: Element reference from the accessibility tree.
+            text: Text to type.
+            element: Human-readable element description.
+            submit: Press Enter after typing.
+            slowly: Type one character at a time (triggers key handlers).
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Typing outcome.
+        """
+        args: Dict[str, Any] = {"target": ref, "text": text}
+        if element is not None:
+            args["element"] = element
+        if submit:
+            args["submit"] = True
+        if slowly:
+            args["slowly"] = True
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_type", args)
+
+    def fill_form(
+        self,
+        fields: List[Dict[str, Any]],
+        *,
+        sandbox_id: Optional[str] = None,
+    ) -> ActionResult:
+        """Fill multiple form fields at once.
+
+        Args:
+            fields: List of field dicts with keys ``name``, ``type``,
+                    ``ref`` (or ``selector``), and ``value``.
+                    ``type`` is one of: ``textbox``, ``checkbox``,
+                    ``radio``, ``combobox``, ``slider``.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Fill outcome.
+        """
+        args: Dict[str, Any] = {"fields": fields}
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_fill_form", args)
+
+    def select_option(
+        self,
+        ref: str,
+        values: List[str],
+        *,
+        element: Optional[str] = None,
+        sandbox_id: Optional[str] = None,
+    ) -> ActionResult:
+        """Select option(s) in a dropdown.
+
+        Args:
+            ref: Element reference from the accessibility tree.
+            values: Array of values to select.
+            element: Human-readable element description.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Selection outcome.
+        """
+        args: Dict[str, Any] = {"target": ref, "values": values}
+        if element is not None:
+            args["element"] = element
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_select_option", args)
+
+    def press_key(self, key: str, *, sandbox_id: Optional[str] = None) -> ActionResult:
+        """Press a key on the keyboard.
+
+        Args:
+            key: Key name (e.g. ``"Enter"``, ``"Tab"``, ``"ArrowLeft"``, ``"a"``).
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Key press outcome.
+        """
+        args: Dict[str, Any] = {"key": key}
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_press_key", args)
+
+    # ---- JavaScript & Code ----
+
+    def evaluate(
+        self,
+        script: str,
+        *,
+        element: Optional[str] = None,
+        ref: Optional[str] = None,
+        filename: Optional[str] = None,
+        sandbox_id: Optional[str] = None,
+    ) -> ActionResult:
+        """
+        Execute JavaScript in the browser context and return the result.
+
+        Args:
+            script: JavaScript function: ``() => { ... }`` or ``(el) => { ... }``.
+            element: Human-readable element description (used with ref).
+            ref: Element reference to evaluate on.
+            filename: Save result to file instead of returning inline.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Return value of the script in ``.data``.
+        """
+        args: Dict[str, Any] = {"function": script}
+        if element is not None:
+            args["element"] = element
+        if ref is not None:
+            args["ref"] = ref
+        if filename is not None:
+            args["filename"] = filename
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_evaluate", args)
+
+    def run_code(self, code: str, *, filename: Optional[str] = None, sandbox_id: Optional[str] = None) -> ActionResult:
+        """Run a Playwright code snippet on the page.
+
+        Args:
+            code: Async JavaScript function receiving ``page`` parameter,
+                  e.g. ``async (page) => { await page.getByRole('button').click(); }``
+            filename: Load code from file instead of inline.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Code execution result.
+        """
+        args: Dict[str, Any] = {"code": code}
+        if filename is not None:
+            args["filename"] = filename
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_run_code", args)
+
+    # ---- Window & Tab Management ----
+
+    def close_tab(self, *, sandbox_id: Optional[str] = None) -> ActionResult:
+        """Close the current browser tab/page.
+
+        This method closes the current browser tab. It is intentionally named
+        ``close_tab`` (rather than ``close``) to avoid confusion with
+        :meth:`AgentLink.close`, which closes the client connection itself.
+
+        Args:
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Close outcome.
+        """
+        args: Dict[str, Any] = {}
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_close", args)
+
+    def resize(self, width: int, height: int, *, sandbox_id: Optional[str] = None) -> ActionResult:
+        """Resize the browser window.
+
+        Args:
+            width: New width in pixels.
+            height: New height in pixels.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Resize outcome.
+        """
+        args: Dict[str, Any] = {"width": width, "height": height}
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_resize", args)
+
+    def tabs(
+        self,
+        action: str = "list",
+        *,
+        index: Optional[int] = None,
+        sandbox_id: Optional[str] = None,
+    ) -> ActionResult:
+        """List, create, close, or select browser tabs.
+
+        Args:
+            action: ``"list"``, ``"new"``, ``"close"``, or ``"select"``.
+            index: Tab index (for close/select).
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Tab operation outcome.
+        """
+        args: Dict[str, Any] = {"action": action}
+        if index is not None:
+            args["index"] = index
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_tabs", args)
+
+    # ---- Dialog & File Upload ----
+
+    def handle_dialog(
+        self,
+        accept: bool,
+        *,
+        prompt_text: Optional[str] = None,
+        sandbox_id: Optional[str] = None,
+    ) -> ActionResult:
+        """Handle a browser dialog (alert, confirm, prompt).
+
+        Args:
+            accept: Whether to accept the dialog.
+            prompt_text: Text for prompt dialog.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Dialog handling outcome.
+        """
+        args: Dict[str, Any] = {"accept": accept}
+        if prompt_text is not None:
+            args["promptText"] = prompt_text
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_handle_dialog", args)
+
+    def file_upload(self, paths: Optional[List[str]] = None, *, sandbox_id: Optional[str] = None) -> ActionResult:
+        """Upload one or multiple files.
+
+        Args:
+            paths: Absolute paths to files. If omitted, file chooser is cancelled.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Upload outcome.
+        """
+        args: Dict[str, Any] = {}
+        if paths is not None:
+            args["paths"] = paths
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_file_upload", args)
+
+    # ---- Diagnostics ----
+
+    def console_messages(
+        self,
+        level: str = "info",
+        *,
+        all_messages: bool = False,
+        filename: Optional[str] = None,
+        sandbox_id: Optional[str] = None,
+    ) -> ActionResult:
+        """Get browser console messages.
+
+        Args:
+            level: Minimum severity level: ``"error"``, ``"warning"``,
+                   ``"info"``, or ``"debug"``.
+            all_messages: Return all messages since session start.
+            filename: Save messages to file instead of returning inline.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Console messages in ``.text``.
+        """
+        args: Dict[str, Any] = {"level": level}
+        if all_messages:
+            args["all"] = True
+        if filename is not None:
+            args["filename"] = filename
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_console_messages", args)
+
+    def network_requests(
+        self,
+        *,
+        static: bool = False,
+        request_body: bool = False,
+        request_headers: bool = False,
+        filter_pattern: Optional[str] = None,
+        filename: Optional[str] = None,
+        sandbox_id: Optional[str] = None,
+    ) -> ActionResult:
+        """Get network requests since page load.
+
+        Args:
+            static: Include static resources (images, fonts, scripts).
+            request_body: Include request bodies.
+            request_headers: Include request headers.
+            filter_pattern: Regex filter for URLs.
+            filename: Save to file instead of returning inline.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Network request data in ``.text``.
+        """
+        args: Dict[str, Any] = {
+            "static": static,
+            "requestBody": request_body,
+            "requestHeaders": request_headers,
+        }
+        if filter_pattern is not None:
+            args["filter"] = filter_pattern
+        if filename is not None:
+            args["filename"] = filename
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_network_requests", args)
+
+    # ---- Wait ----
+
+    def wait_for(
+        self,
+        *,
+        time_secs: Optional[float] = None,
+        text: Optional[str] = None,
+        text_gone: Optional[str] = None,
+        sandbox_id: Optional[str] = None,
+    ) -> ActionResult:
+        """Wait for text to appear, disappear, or a time to pass.
+
+        Args:
+            time_secs: Time to wait in seconds.
+            text: Text to wait for.
+            text_gone: Text to wait for to disappear.
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Wait outcome.
+
+        Raises:
+            ValueError: If none of *time_secs*, *text*, or *text_gone* is provided.
+        """
+        if time_secs is None and text is None and text_gone is None:
+            raise ValueError("At least one of 'time_secs', 'text', or 'text_gone' must be provided.")
+        args: Dict[str, Any] = {}
+        if time_secs is not None:
+            args["time"] = time_secs
+        if text is not None:
+            args["text"] = text
+        if text_gone is not None:
+            args["textGone"] = text_gone
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "browser_wait_for", args)
+
+    # ---- Shell (cross-cutting) ----
+
+    def shell(self, command: str, *, timeout: int = 30, sandbox_id: Optional[str] = None) -> ActionResult:
+        """Execute a shell command in the browser sandbox.
+
+        Args:
+            command: Shell command to execute.
+            timeout: Command timeout in seconds (default: 30).
+            sandbox_id: Explicit sandbox ID.
+
+        Returns:
+            ActionResult: Command output in ``.text``.
+        """
+        args: Dict[str, Any] = {"command": command, "timeout": timeout}
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "shell_exec", args)
+
+    def get_os(self, *, sandbox_id: Optional[str] = None) -> ActionResult:
+        """Get the operating system of the sandbox.
+
+        Returns:
+            ActionResult: OS information in ``.text``.
+        """
+        args: Dict[str, Any] = {}
+        if sandbox_id:
+            args["sandboxId"] = sandbox_id
+        return self._client._invoke(self._image_id, "get_os", args)
+
+    def __repr__(self) -> str:
+        return f"BrowserController(image_id={self._image_id!r})"