使用者介面自動化 - AgentBay

本文介紹無影 AgentBay SDK 在雲手機中使用者介面自動化功能，包括觸控操作、文本輸入/UI元素檢測與螢幕操作。

概述

無影 AgentBay SDK 在雲手機中使用者介面自動化功能，包括：

觸摸操作：用於雲手機互動的點擊和滑動手勢。
文本輸入：輸入文本和發送硬體按鍵事件。
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 以適應不同手勢速度。
- 確保起始和結束座標建立有意義的滑動方向。