UI 自动化-无影 Agent 开发套件 AgentBay(AgentBay)-阿里云帮助中心

本文介绍无影 AgentBay SDK 在云手机中 UI 自动化功能，包括触控操作、文本输入/UI元素检测与屏幕操作。

概述

无影 AgentBay SDK 在云手机中 UI 自动化功能，包括：

触摸操作：用于云手机交互的点击和滑动手势。
文本输入：输入文本和发送硬件按键事件。
UI元素检测：发现和交互UI元素。
屏幕操作：截取屏幕截图进行视觉验证。

创建会话

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session
# 会话创建成功，可用于云手机自动化

触摸操作

点击手势

在特定坐标上点击屏幕：

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

# 在坐标上点击
result = session.mobile.tap(x=500, y=300)
if result.success:
    print("Tap successful")  # 输出: Tap successful
else:
    print(f"Tap failed: {result.error_message}")

agent_bay.delete(session)

滑动手势

从一个点到另一个点执行滑动手势：

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

# 向上滑动（从底部到顶部）
result = session.mobile.swipe(
    start_x=100,
    start_y=500,
    end_x=100,
    end_y=200,
    duration_ms=300
)
if result.success:
    print("Swipe up successful")  # 输出: Swipe up successful

# 向左滑动（从右到左）
result = session.mobile.swipe(
    start_x=500,
    start_y=300,
    end_x=100,
    end_y=300,
    duration_ms=300
)
if result.success:
    print("Swipe left successful")  # 输出: Swipe left successful

agent_bay.delete(session)

参数：

start_x, start_y：起始坐标。
end_x, end_y：结束坐标。
duration_ms：滑动持续时间（毫秒），默认值为300。

文本输入

输入文本

在当前激活的输入框中输入文本：

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

result = session.mobile.input_text("Hello AgentBay!")
if result.success:
    print("Text input successful")  # 输出: Text input successful

agent_bay.delete(session)

发送硬件按键事件

使用KeyCode常量发送Android硬件按键事件：

from agentbay.mobile.mobile import KeyCode

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

# 按HOME键
result = session.mobile.send_key(KeyCode.HOME)
if result.success:
    print("HOME key pressed")  # 输出: HOME key pressed

# KeyCode值为: HOME=3, BACK=4, VOLUME_UP=24, VOLUME_DOWN=25, POWER=26, MENU=82
print(f"HOME keycode value: {KeyCode.HOME}")  # 输出: HOME keycode value: 3

agent_bay.delete(session)

可用的KeyCode常量：

KeyCode	值	描述
`KeyCode.HOME`	3	主页按钮
`KeyCode.BACK`	4	返回按钮
`KeyCode.VOLUME_UP`	24	音量增加按钮
`KeyCode.VOLUME_DOWN`	25	音量减小按钮
`KeyCode.POWER`	26	电源按钮
`KeyCode.MENU`	82	菜单按钮

注意：所有硬件按键都可用于云手机自动化。按键事件发送到Android系统并相应执行。

UI元素检测

获取所有UI元素

检索当前屏幕层次结构中的所有UI元素：

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

result = session.mobile.get_all_ui_elements(timeout_ms=2000)
if result.success:
    print(f"Found {len(result.elements)} UI elements")  # 输出: Found 2172 UI elements
    for element in result.elements:
        # 元素结构各不相同，检查元素数据
        print(f"Element: {element}")
        # 输出示例: Element data contains UI hierarchy information
else:
    print(f"Failed: {result.error_message}")

agent_bay.delete(session)

参数：

timeout_ms: 等待UI元素的超时时间（毫秒），默认值为2000。

屏幕操作

截取屏幕截图

捕获当前云手机屏幕的截图：

session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

result = session.mobile.screenshot()
if result.success:
    screenshot_url = result.data
    print(f"Screenshot URL: {screenshot_url}")
    # 输出：Screenshot URL: https://***.***.aliyuncs.com/***/screenshot_1234567890.png?***
else:
    print(f"Screenshot failed: {result.error_message}")

agent_bay.delete(session)

最佳实践

始终使用云手机系统镜像

云手机UI自动化需要云手机系统镜像（以下示例使用 mobile_latest）：

# 正确 - 使用云手机系统镜像
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

# 错误 - 无法用于云手机操作
session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

正确处理屏幕截图URL

屏幕截图返回OSS URL，而非图像数据：

result = session.mobile.screenshot()
if result.success:
    screenshot_url = result.data
    print(f"Screenshot available at: {screenshot_url}")
    # 输出：Screenshot available at: https://***.***.aliyuncs.com/***/screenshot_1234567890.png?***
    # 根据需要使用URL下载或显示屏幕截图
else:
    print(f"Screenshot failed: {result.error_message}")

常见用例

示例1: 应用导航

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

try:
    # 点击应用图标
    tap_result = session.mobile.tap(x=200, y=400)
    print(f"App tap result: {tap_result.success}")  # 输出: App tap result: True
    
    # 等待应用加载
    import time
    time.sleep(2)
    
    # 滑动导航
    swipe_result = session.mobile.swipe(
        start_x=400,
        start_y=600,
        end_x=100,
        end_y=600,
        duration_ms=300
    )
    print(f"Navigation swipe result: {swipe_result.success}")  # 输出: Navigation swipe result: True
    
    # 点击按钮
    button_result = session.mobile.tap(x=300, y=800)
    print(f"Button tap result: {button_result.success}")  # 输出: Button tap result: True
    
finally:
    agent_bay.delete(session)

示例2: 移动端表单输入

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

try:
    # 点击用户名字段
    username_tap = session.mobile.tap(x=300, y=400)
    print(f"Username field focused: {username_tap.success}")  # 输出: Username field focused: True
    
    # 输入用户名
    username_input = session.mobile.input_text("john_doe")
    print(f"Username entered: {username_input.success}")  # 输出: Username entered: True
    
    # 点击密码字段
    password_tap = session.mobile.tap(x=300, y=500)
    print(f"Password field focused: {password_tap.success}")  # 输出: Password field focused: True
    
    # 输入密码
    password_input = session.mobile.input_text("secure_password")
    print(f"Password entered: {password_input.success}")  # 输出: Password entered: True
    
    # 点击登录按钮
    login_tap = session.mobile.tap(x=300, y=650)
    print(f"Login button pressed: {login_tap.success}")  # 输出: Login button pressed: True
    
finally:
    agent_bay.delete(session)

示例3: UI元素发现和交互

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

try:
    # 获取所有可点击元素
    result = session.mobile.get_clickable_ui_elements(timeout_ms=3000)
    
    if result.success:
        print(f"Found {len(result.elements)} clickable elements")  # 输出: Found 3 clickable elements
        
        # 分析元素以找到目标
        for i, element in enumerate(result.elements):
            print(f"Element {i+1}: {element}")  
            # 输出示例:
            # Element 1: UI element with interaction capabilities
            # Element 2: UI element with interaction capabilities  
            # Element 3: UI element with interaction capabilities
    
    # 截取屏幕截图进行验证
    screenshot = session.mobile.screenshot()
    if screenshot.success:
        screenshot_url = screenshot.data
        print(f"Screenshot URL: {screenshot_url}")
        # 输出: Screenshot URL: https://***.***.aliyuncs.com/***/screenshot_1234567890.png?***
    
finally:
    agent_bay.delete(session)

示例4: 滚动浏览内容

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
session_params = CreateSessionParams(image_id="mobile_latest")
session = agent_bay.create(session_params).session

try:
    # 多次向下滚动
    for i in range(3):
        scroll_result = session.mobile.swipe(
            start_x=300,
            start_y=800,
            end_x=300,
            end_y=200,
            duration_ms=400
        )
        print(f"Scroll down {i+1}: {scroll_result.success}")  # 输出: Scroll down 1: True, etc.
        
        # 滚动间短暂暂停
        import time
        time.sleep(1)
    
    # 向上滚动
    up_result = session.mobile.swipe(
        start_x=300,
        start_y=200,
        end_x=300,
        end_y=800,
        duration_ms=400
    )
    print(f"Scroll up result: {up_result.success}")  # 输出: Scroll up result: True
    
finally:
    agent_bay.delete(session)

故障排除

常见问题

"Tool not found"错误
- 确保使用的是云手机系统镜像（例如image_id="mobile_latest"）
- 验证会话是否创建成功。
- 检查 API KEY 和终结点是否配置正确。
硬件按键操作
- 硬件按键操作向 Android 系统发送按键事件。
- 检查 result.success 状态以验证按键是否发送成功。
- 错误处理示例：
```
result = session.mobile.send_key(KeyCode.HOME)
if not result.success:
    print(f"Key press failed: {result.error_message}")
```
UI元素检测返回空结果
- 增加 timeout_ms 参数。
- 截取屏幕截图以验证当前UI状态。
- 确保目标屏幕已完全加载。
屏幕截图URL处理
- 屏幕截图返回OSS URL，而非图像数据。
- result.data 包含下载URL，而非图像本身。
- 如有需要，可使用URL下载屏幕截图。
滑动手势未按预期工作
- 验证坐标是否在屏幕范围内。
- 调整 duration_ms 以适应不同手势速度。
- 确保起始和结束坐标创建有意义的滑动方向。