Run the agent to complete a task. Args: task: Natural language description of the task. Returns: Fi

Run HDC command with optional verbose output. Args: cmd: Command list to execute. **kwargs: Additional arguments for subproc

Get the global device factory instance. Returns: The device factory instance.

Get UI messages dictionary by language. Args: lang: Language code, 'cn' for Chinese, 'en' for English. Returns: Diction

Get ADB command prefix with optional device specifier.

Get HDC command prefix with optional device specifier.

Get the correct WDA URL for a session endpoint. Args: wda_url: Base WDA URL. session_id: Optional session ID. endpoi

Get the correct WDA URL for a session endpoint. Args: wda_url: Base WDA URL. session_id: Optional session ID. endpoi

Check if WebDriverAgent is running and accessible. Args: timeout: Request timeout in seconds. Returns:

Convert relative coordinates (0-1000) to absolute pixels.

Convert relative coordinates (0-1000) to absolute pixels.

Get ADB command prefix with optional device specifier.

Get HDC command prefix with optional device specifier.

Build screen info string for the model. Args: current_app: Current app name. **extra_info: Additional info t

Create a user message with optional image. Args: text: Text content. image_base64: Optional base64-encoded i

Execute an action from the AI model. Args: action: The action dictionary from the model. screen_width: Curre

Helper function for creating 'finish' actions.

Get a single UI message by key and language. Args: key: Message key. lang: Language code, 'cn' for Chinese, 'en' for English

Get WebDriverAgent status information. Returns: Status dictionary or None if not available.

List all connected devices. Returns: List of DeviceInfo objects.

Create a black fallback image when screenshot fails.

Create a black fallback image when screenshot fails.

Execute a single step of the agent loop.

Execute a single step of the agent loop.

Quick helper to list connected iOS devices. Returns: List of DeviceInfo objects.

List all connected iOS devices. Returns: List of DeviceInfo objects. Note: Requires libimobiledevic

List all connected devices. Returns: List of DeviceInfo objects.

Connect to a remote device via TCP/IP. Args: address: Device address in format "host:port" (e.g., "192.168.1.100:5555").

Connect to a remote device via TCP/IP. Args: address: Device address in format "host:port" (e.g., "192.168.1.100:5555").

Create an assistant message.

Create a system message.

Disconnect from a remote device. Args: address: Device address to disconnect. If None, disconnects all. Returns

Capture a screenshot from the connected iOS device. Args: wda_url: WebDriverAgent URL. session_id: Optional WDA session ID.

Get system prompt by language. Args: lang: Language code, 'cn' for Chinese, 'en' for English. Returns: System prompt st

List connected devices.

Pair with an iOS device (required for some operations). Args: device_id: Device UDID. If None, uses first available devi

Parse action from model response. Args: response: Raw response string from the model. Returns: Parsed action dictionary

Remove image content from a message to save context space. Args: message: Message dictionary. Returns:

Send a request to the model. Args: messages: List of message dictionaries in OpenAI format. Returns:

Reset the agent state for a new task.

Run the agent to complete a task. Args: task: Natural language description of the task. Returns: Fi

Execute a single step of the agent. Useful for manual control or debugging. Args: task: Task description (only

Type text into the currently focused input field using ADB Keyboard. Args: text: The text to type. device_id: Optional ADB d

Clear text by sending backspace keys. Args: wda_url: WebDriverAgent URL. session_id: Optional WDA session ID. max_ba

Create a black fallback image when screenshot fails. Args: is_sensitive: Whether the failure was due to sensitive content. Retu

Get ADB command prefix with optional device specifier.

Get detailed information about a specific device. Args: udid: Device UDID. Returns: Dictionary with

Get the handler method for an action.

Get the handler method for an action.

Get HDC command prefix with optional device specifier.

Capture screenshot using idevicescreenshot (libimobiledevice). Args: device_id: Optional device UDID. timeout: Timeout in se

Capture screenshot using WebDriverAgent. Args: wda_url: WebDriverAgent URL. session_id: Optional WDA session ID. tim

Parse the model response into thinking and action parts. Parsing rules: 1. If content contains 'finish(message=', everything

Navigate back (swipe from left edge). Args: wda_url: WebDriverAgent URL. session_id: Optional WDA session ID. delay:

Press back button.

Check if the model API is accessible and the specified model exists. Checks: 1. Network connectivity to the API endpoint 2. Model ex

Check system requirements before running the agent. Checks: 1. libimobiledevice tools installed 2. At least one iOS device connected

Check system requirements before running the agent. Checks: 1. ADB/HDC/iOS tools installed 2. At least one device connected 3. A

Clear text in the currently focused input field. Args: device_id: Optional ADB device ID for multi-device setups.

Clear text.

Detect and set keyboard.

Disconnect from a remote device. Args: address: Device address to disconnect. If None, disconnects all. Returns

Double tap at the specified coordinates using WebDriver W3C Actions API. Args: x: X coordinate. y: Y coordinate. wda

Double tap at coordinates.

Enable TCP/IP debugging on a USB-connected device. This allows subsequent wireless connections to the device. Args:

Basic task example / 基础任务示例

Get the iOS bundle ID for an app. Args: app_name: The display name of the app. Returns: The iOS bundle ID, or None if n

Get the connection class (ADBConnection or HDCConnection).

Get the currently focused app name. Args: device_id: Optional HDC device ID for multi-device setups. Returns: The app n

Get the currently active app bundle ID and name. Args: wda_url: WebDriverAgent URL. session_id: Optional WDA session ID.

Get current app name.

Get the IP address of a connected device. Args: device_id: Device ID. If None, uses first available device. Ret

Get screenshot from device.

Handle iOS device-related commands. Returns: True if a device command was handled (should exit), False otherwise.

Handle device-related commands. Returns: True if a device command was handled (should exit), False otherwise.

Handle iOS device-related commands. Returns: True if a device command was handled (should exit), False otherwise.

Hide the on-screen keyboard. Args: wda_url: WebDriverAgent URL. session_id: Optional WDA session ID.

Press the home button. Args: wda_url: WebDriverAgent URL. session_id: Optional WDA session ID. delay: Delay in secon

Press home button.

Check if a device is connected. Args: device_id: Device UDID to check. If None, checks if any device is connected.

Launch an app by name. Args: app_name: The app name (must be in APP_PACKAGES). wda_url: WebDriverAgent URL. session_

Launch an app.

Get a list of all supported app names. Returns: List of app names.

Get a list of all supported iOS app names. Returns: List of app names.

Long press at the specified coordinates using WebDriver W3C Actions API. Args: x: X coordinate. y: Y coordinate. dur

Long press at coordinates.

Main entry point.

Main entry point.

Parse command line arguments.

Parse command line arguments.

Reset the agent state for a new task.

Restore keyboard.

Send a sequence of keys. Args: keys: List of keys to send. wda_url: WebDriverAgent URL. session_id: Optional WDA ses

Set the global device type. Args: device_type: The device type to use (ADB or HDC).

Set HDC verbose mode globally.

Start a new WebDriverAgent session. Returns: Tuple of (success, session_id or error_message).

Swipe from start to end coordinates using WDA dragfromtoforduration endpoint. Args: start_x: Starting X coordinate. start_y:

Swipe from start to end.

Tap at the specified coordinates using WebDriver W3C Actions API. Args: x: X coordinate. y: Y coordinate. wda_url: W