應用管理 - AgentBay

本文介紹使用 AgentBay SDK 對雲電腦進行應用管理的相關能力。包含如何在雲環境中發現、啟動、監控和控制傳統型應用程式。

概述

Computer Use模組為案頭環境提供全面的應用程式管理能力，包括：

應用程式發現 - 尋找系統中已安裝的應用程式。
應用程式生命週期管理 - 啟動和停止傳統型應用程式。
進程監控 - 跟蹤正在啟動並執行應用程式及其進程。
案頭自動化 - 自動化複雜的案頭工作流程。

建立會話

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 environment variable is required")

agent_bay = AgentBay(api_key=api_key)

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

if result.success:
    session = result.session
    print(f"Session created: {session.session_id}")
    # Output: Session created: session-xxxxxxxxxxxxxxxxx
else:
    print(f"Failed to create session: {result.error_message}")
    exit(1)

擷取已安裝的應用程式

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

# Verification: Result type is InstalledAppListResult
# Verification: Success = True
# Verification: Found 76 installed applications on test system

if result.success:
    apps = result.data
    print(f"Found {len(apps)} installed applications")
    # Output: Found 76 installed applications
    
    for app in apps[:5]:
        print(f"Name: {app.name}")
        print(f"Start Command: {app.start_cmd}")
        print(f"Stop Command: {app.stop_cmd if app.stop_cmd else 'N/A'}")
        print(f"Work Directory: {app.work_directory if app.work_directory else 'N/A'}")
        print("---")
    # Output example:
    # Name: AptURL
    # Start Command: apturl %u
    # Stop Command: N/A
    # Work Directory: N/A
    # ---
    # Name: Bluetooth Transfer
    # Start Command: bluetooth-sendto
    # Stop Command: N/A
    # Work Directory: N/A
    # ---
else:
    print(f"Error: {result.error_message}")

參數說明：

start_menu (bool): 是否包含開始菜單中的應用程式。
desktop (bool): 是否包含傳統型應用程式。
ignore_system_apps (bool): 是否過濾掉系統應用程式。

傳回值：

包含 InstalledApp 對象列表的 InstalledAppListResult。

啟動應用程式

通過命令啟動

start_cmd = "/usr/bin/google-chrome-stable"

result = session.computer.start_app(start_cmd)

# 驗證: 結果類型為 ProcessListResult
# 驗證: 成功 = True
# 驗證: 啟動了 6 個進程 (chrome 主進程 + 輔助進程)

if result.success:
    processes = result.data
    print(f"Application started with {len(processes)} processes")
    # 輸出: Application started with 6 processes
    
    for process in processes:
        print(f"Process: {process.pname} (PID: {process.pid})")
    # 輸出樣本:
    # Process: chrome (PID: 4443)
    # Process: cat (PID: 4448)
    # Process: cat (PID: 4449)
    # Process: chrome (PID: 4459)
    # Process: chrome (PID: 4460)
    # Process: chrome (PID: 4462)
else:
    print(f"Failed to start application: {result.error_message}")

指定工作目錄啟動

start_cmd = "/usr/bin/google-chrome-stable"
work_directory = "/tmp"

result = session.computer.start_app(
    start_cmd=start_cmd,
    work_directory=work_directory
)

# 驗證: 結果類型為 ProcessListResult
# 驗證: 成功 = True
# 驗證: 應用程式在指定的工作目錄中啟動

if result.success:
    processes = result.data
    print(f"Application started with {len(processes)} processes")
    # 輸出: Application started with 6 processes
else:
    print(f"Failed to start application: {result.error_message}")

從已安裝應用列表啟動

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

# 驗證: 成功檢索到已安裝的應用程式列表

if result.success:
    apps = result.data
    
    target_app = None
    for app in apps:
        if "chrome" in app.name.lower():
            target_app = app
            break
    
    # 驗證: 在應用程式列表中找到了 "Google Chrome"
    
    if target_app:
        print(f"Starting {target_app.name}...")
        # 輸出: Starting Google Chrome...
        
        start_result = session.computer.start_app(target_app.start_cmd)
        
        # 驗證: 成功啟動了應用程式
        
        if start_result.success:
            print("Application started successfully!")
            # 輸出: Application started successfully!
        else:
            print(f"Failed to start: {start_result.error_message}")
    else:
        print("Target application not found")

停止應用程式

通過PID停止

start_result = session.computer.start_app("/usr/bin/google-chrome-stable")

# 驗證: 應用程式成功啟動，包含多個進程

if start_result.success:
    target_pid = None
    for process in start_result.data:
        print(f"Process: {process.pname} (PID: {process.pid})")
        # 輸出樣本:
        # Process: chrome (PID: 6378)
        # Process: cat (PID: 6383)
        # Process: cat (PID: 6384)
        
        if 'chrome' in process.pname.lower():
            target_pid = process.pid
            break
    
    if target_pid:
        result = session.computer.stop_app_by_pid(target_pid)
        
        # 驗證: 結果類型為 AppOperationResult
        # 驗證: 成功 = True
        
        if result.success:
            print(f"Successfully stopped process {target_pid}")
            # 輸出: Successfully stopped process 6378
        else:
            print(f"Failed to stop process: {result.error_message}")

通過進程名稱停止

start_result = session.computer.start_app("/usr/bin/google-chrome-stable")

# 驗證: 應用程式成功啟動

if start_result.success:
    target_pname = None
    for process in start_result.data:
        print(f"Process: {process.pname} (PID: {process.pid})")
        target_pname = process.pname
        break
    
    # 驗證: 擷取到進程名稱 "chrome"
    
    if target_pname:
        result = session.computer.stop_app_by_pname(target_pname)
        
        # 驗證: 結果類型為 AppOperationResult
        # 驗證: 成功 = True
        
        if result.success:
            print(f"Successfully stopped process {target_pname}")
            # 輸出: Successfully stopped process chrome
        else:
            print(f"Failed to stop process: {result.error_message}")

通過停止命令停止

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

# 驗證: 成功檢索到已安裝的應用程式

if result.success:
    apps = result.data
    
    target_app = None
    for app in apps:
        if app.stop_cmd:
            target_app = app
            break
    
    # 注意: Linux 上大多數傳統型應用程式都沒有定義 stop_cmd
    # 這是正常的 - 應使用 stop_app_by_pid 或 stop_app_by_pname
    
    if target_app:
        start_result = session.computer.start_app(target_app.start_cmd)
        
        if start_result.success:
            print("Application started successfully!")
            
            result = session.computer.stop_app_by_cmd(target_app.stop_cmd)
            
            # 驗證: 結果類型為 AppOperationResult
            
            if result.success:
                print("Successfully stopped application using command")
            else:
                print(f"Failed to stop application: {result.error_message}")

列出正在啟動並執行應用程式

result = session.computer.list_visible_apps()

# 驗證: 結果類型為 ProcessListResult
# 驗證: 成功 = True
# 驗證: 找到了 1 個可見應用程式 (具有可見視窗的 chrome)

if result.success:
    visible_apps = result.data
    print(f"Found {len(visible_apps)} running applications")
    # 輸出: Found 1 running applications
    
    for app in visible_apps:
        print(f"Process: {app.pname}")
        print(f"PID: {app.pid}")
        print(f"Command: {app.cmdline}")
        print("---")
    # 輸出樣本:
    # Process: chrome
    # PID: 6378
    # Command: /opt/google/chrome/chrome
    # ---
else:
    print(f"Error: {result.error_message}")

進程對象屬性:

pname (str): 進程名稱。
pid (int): 進程ID。
cmdline (str): 用於啟動進程的完整命令列。

完整工作流程樣本

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 environment variable is required")

agent_bay = AgentBay(api_key=api_key)

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

if not result.success:
    print(f"Failed to create session: {result.error_message}")
    exit(1)

session = result.session
print(f"Session created: {session.session_id}")
# 輸出: Session created: session-xxxxxxxxxxxxxxxxx

print("Step 1: Finding installed applications...")
apps_result = session.computer.get_installed_apps(
    start_menu=True,
    desktop=False,
    ignore_system_apps=True
)

# 驗證: 成功檢索到 76 個應用程式

if not apps_result.success:
    print(f"Failed to get apps: {apps_result.error_message}")
    agent_bay.delete(session)
    exit(1)

target_app = None
for app in apps_result.data:
    if "chrome" in app.name.lower():
        target_app = app
        break

# 驗證: 找到了 "Google Chrome" 應用程式

if not target_app:
    print("Google Chrome not found")
    agent_bay.delete(session)
    exit(1)

print(f"Found application: {target_app.name}")
# 輸出: Found application: Google Chrome

print("Step 2: Launching application...")
start_result = session.computer.start_app(target_app.start_cmd)

# 驗證: 成功啟動了 6 個進程

if not start_result.success:
    print(f"Failed to start app: {start_result.error_message}")
    agent_bay.delete(session)
    exit(1)

print(f"Application started with {len(start_result.data)} processes")
# 輸出: Application started with 6 processes

for process in start_result.data:
    print(f"  - {process.pname} (PID: {process.pid})")
# 輸出樣本:
#   - chrome (PID: 6420)
#   - cat (PID: 6425)
#   - cat (PID: 6426)
#   - chrome (PID: 6436)
#   - chrome (PID: 6437)
#   - chrome (PID: 6439)

print("Step 3: Waiting for application to load...")
time.sleep(5)

print("Step 4: Checking running applications...")
visible_result = session.computer.list_visible_apps()

# 驗證: 找到了 1 個可見應用程式

if visible_result.success:
    print(f"Found {len(visible_result.data)} visible applications")
    # 輸出: Found 1 visible applications

print("Step 5: Stopping application...")
if start_result.data:
    stop_result = session.computer.stop_app_by_pid(start_result.data[0].pid)
    
    # 驗證: 成功停止了應用程式
    
    if stop_result.success:
        print("Application stopped successfully")
        # 輸出: Application stopped successfully
    else:
        print(f"Failed to stop application: {stop_result.error_message}")

print("Cleaning up session...")
agent_bay.delete(session)
print("Workflow completed!")
# 輸出: Workflow completed!

# === 完整工作流程驗證結果 ===
# ✓ 會話建立: 成功
# ✓ 擷取已安裝應用程式: 找到 76 個應用程式
# ✓ 尋找目標應用程式: 找到 Google Chrome
# ✓ 啟動應用程式: 啟動了 6 個進程
# ✓ 列出可見應用程式: 1 個可見應用程式
# ✓ 停止應用程式: 成功停止
# ✓ 會話清理: 成功

API 參考

雲電腦應用程式管理方法

所有應用程式管理方法都通過 session.computer.* 訪問：

方法	參數	傳回值	描述
`get_installed_apps()`	`start_menu: bool = True`<br/>`desktop: bool = False`<br/>`ignore_system_apps: bool = True`	`InstalledAppListResult`	擷取已安裝應用程式列表
`start_app()`	`start_cmd: str`<br/>`work_directory: str = ""`<br/>`activity: str = ""`	`ProcessListResult`	啟動應用程式
`stop_app_by_pid()`	`pid: int`	`AppOperationResult`	通過進程ID停止應用程式
`stop_app_by_pname()`	`pname: str`	`AppOperationResult`	通過進程名稱停止應用程式
`stop_app_by_cmd()`	`stop_cmd: str`	`AppOperationResult`	通過停止命令停止應用程式
`list_visible_apps()`	無	`ProcessListResult`	列出當前可見的應用程式

傳回型別

InstalledAppListResult

success (bool): 操作是否成功。
data (List[InstalledApp]): 已安裝應用程式列表。
error_message (str): 操作失敗時的錯誤訊息。
request_id (str): 唯一請求標識符。

InstalledApp

name (str): 應用程式名稱。
start_cmd (str): 啟動應用程式的命令。
stop_cmd (Optional[str]): 停止應用程式的命令。
work_directory (Optional[str]): 應用程式的工作目錄。

ProcessListResult

success (bool): 操作是否成功。
data (List[Process]): 進程對象列表。
error_message (str): 操作失敗時的錯誤訊息。
request_id (str): 唯一請求標識符。

Process

pname (str): 進程名稱。
pid (int): 進程ID。
cmdline (Optional[str]): 完整命令列。

AppOperationResult

success (bool): 操作是否成功。
error_message (str): 操作失敗時的錯誤訊息。
request_id (str): 唯一請求標識符。