AgentBay：應用管理

概述

Mobile Use模組為Android行動裝置提供應用程式管理功能，包括：

1. 應用程式發現 - 查詢裝置上已安裝的應用程式。

2. 應用程式生命週期管理 - 使用包名啟動和停止行動裝置 App程式。

3. Activity管理 - 啟動特定的Android Activity。

4. 進程監控 - 跟蹤正在啟動並執行應用程式及其進程。

建立會話

import os
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

api_key = os.getenv("AGENTBAY_API_KEY")
if not api_key:
    raise ValueError("AGENTBAY_API_KEY 環境變數是必需的")

agent_bay = AgentBay(api_key=api_key)

params = CreateSessionParams(image_id="mobile_latest")
result = agent_bay.create(params)

if result.success:
    session = result.session
    print(f"會話已建立: {session.session_id}")
else:
    print(f"建立會話失敗: {result.error_message}")
    exit(1)

# 實際輸出:
# 會話已建立: session-04bdw8o39c9uiwet4

擷取已安裝的應用程式

查詢行動裝置上已安裝的應用程式列表。

result = session.mobile.get_installed_apps(
    start_menu=True,
    desktop=False,
    ignore_system_apps=True
)

if result.success:
    apps = result.data
    print(f"找到 {len(apps)} 個已安裝的應用程式")
   
    for app in apps[:5]:
        print(f"名稱: {app.name}")
        print(f"啟動命令: {app.start_cmd}")
        print(f"停止命令: {app.stop_cmd if app.stop_cmd else 'N/A'}")
        print(f"工作目錄: {app.work_directory if app.work_directory else 'N/A'}")
        print("---")
else:
    print(f"錯誤：{result.error_message}")

# 實際輸出 (使用當前 mobile_latest 鏡像)：
# 找到 0 個已安裝的應用程式

參數：

• start_menu (bool): 是否包含開始菜單應用程式。

• desktop (bool): 是否包含傳統型應用程式。

• ignore_system_apps (bool): 是否過濾系統應用程式。

傳回值：

• 包含 InstalledApp 對象列表的 InstalledAppListResult。

啟動應用程式

使用帶有包名的"monkey -p"命令格式啟動行動裝置 App程式。

# 使用 "monkey -p" 格式啟動 Android 應用程式
start_cmd = "monkey -p com.android.settings"

result = session.mobile.start_app(start_cmd)

if result.success:
    processes = result.data
    print(f"應用程式已啟動，共 {len(processes)} 個進程")

    for process in processes:
        print(f"進程: {process.pname} (PID: {process.pid})")
else:
    print(f"啟動應用程式失敗：{result.error_message}")

# 實際輸出：
# 應用程式已啟動，共 1 個進程
# 進程: com.android.settings (PID: 2805)

start_cmd = "monkey -p com.android.settings"
activity = ".Settings"

result = session.mobile.start_app(
    start_cmd=start_cmd,
    activity=activity
)

if result.success:
    processes = result.data
    print(f"應用程式已啟動，Activity為 {activity}")
    print(f"找到 {len(processes)} 個進程")
    
    for process in processes:
        print(f"進程: {process.pname} (PID: {process.pid})")
else:
    print(f"啟動應用程式失敗: {result.error_message}")

# 實際輸出:
# 應用程式已啟動，Activity為 .Settings
# 找到 1 個進程
# 進程: com.android.settings (PID: 2921)

停止應用程式

# 啟動一個應用程式
start_result = session.mobile.start_app("monkey -p com.android.settings")

if start_result.success:
    print("應用程式啟動成功")
    for process in start_result.data:
        print(f"  進程: {process.pname} (PID: {process.pid})")

    # 使用包名停止應用程式
    result = session.mobile.stop_app_by_cmd("com.android.settings")

    if result.success:
        print("應用程式已成功停止")
    else:
        print(f"停止應用程式失敗: {result.error_message}")

# 實際輸出:
# 應用程式啟動成功
#   進程: com.android.settings (PID: 3042)
# 應用程式已成功停止

完整工作流程樣本

import os
import time
from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

api_key = os.getenv("AGENTBAY_API_KEY")
if not api_key:
    raise ValueError("AGENTBAY_API_KEY 環境變數是必需的")

agent_bay = AgentBay(api_key=api_key)

# 建立移動會話
params = CreateSessionParams(image_id="mobile_latest")
result = agent_bay.create(params)

if not result.success:
    print(f"建立會話失敗: {result.error_message}")
    exit(1)

session = result.session
print(f"會話已建立: {session.session_id}")

# 步驟 1: 啟動應用程式
print("步驟 1: 啟動設定應用程式...")
start_result = session.mobile.start_app("monkey -p com.android.settings")

if not start_result.success:
    print(f"啟動應用程式失敗: {start_result.error_message}")
    agent_bay.delete(session)
    exit(1)

print(f"應用程式已啟動，共 {len(start_result.data)} 個進程")
for process in start_result.data:
    print(f"  - {process.pname} (PID: {process.pid})")

# 步驟 2: 等待應用程式載入
print("步驟 2: 等待應用程式載入...")
time.sleep(3)

# 步驟 3: 停止應用程式
print("步驟 3: 停止應用程式...")
stop_result = session.mobile.stop_app_by_cmd("com.android.settings")
if stop_result.success:
    print("應用程式已成功停止")
else:
    print(f"停止應用程式失敗：{stop_result.error_message}")

# 清理
print("清理會話...")
agent_bay.delete(session)
print("工作流程已完成!")

# 實際輸出：
# 會話已建立：session-04bdwfj7tnhfnzibx
# 步驟 1: 啟動設定應用程式...
# 應用程式已啟動，共 1 個進程
#   - com.android.settings (PID: 3268)
# 步驟 2: 等待應用程式載入...
# 步驟 3: 停止應用程式...
# 應用程式已成功停止
# 清理會話...
# 工作流程已完成

API參考

session.mobile.start_app("monkey -p com.android.settings")

session.mobile.stop_app_by_cmd("com.android.settings")

session.mobile.start_app(
    start_cmd="monkey -p com.android.settings",
    activity=".Settings"
)