このトピックでは、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 環境変数が必要です")
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.session_id}")
# 出力例: セッションが作成されました: session-xxxxxxxxxxxxxxxxx
else:
print(f"セッションの作成に失敗しました: {result.error_message}")
exit(1)インストール済みアプリケーションの取得
result = session.computer.get_installed_apps(
start_menu=True,
desktop=False,
ignore_system_apps=True
)
# 検証: 戻り値の型は InstalledAppListResult
# 検証: success = True
# 検証: テストシステムで 76 個のインストール済みアプリケーションが検出されました
if result.success:
apps = result.data
print(f"{len(apps)} 個のインストール済みアプリケーションが見つかりました")
# 出力例: 76 個のインストール済みアプリケーションが見つかりました
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("---")
# 出力例:
# 名前: AptURL
# 起動コマンド: apturl %u
# 停止コマンド: N/A
# 作業ディレクトリ: N/A
# ---
# 名前: Bluetooth Transfer
# 起動コマンド: bluetooth-sendto
# 停止コマンド: N/A
# 作業ディレクトリ: N/A
# ---
else:
print(f"エラー: {result.error_message}")パラメーターの説明：
start_menu（bool）：スタートメニューからのアプリケーションを含めるか否か。desktop（bool）：デスクトップアプリケーションを含めるか否か。ignore_system_apps（bool）：システムアプリケーションを除外するか否か。
戻り値：
InstalledAppListResultオブジェクト。これはInstalledAppオブジェクトのリストを含みます。
アプリケーションの起動
コマンドによる起動
start_cmd = "/usr/bin/google-chrome-stable"
result = session.computer.start_app(start_cmd)
# 検証: 戻り値の型は ProcessListResult
# 検証: success = True
# 検証: 6 個のプロセス（Chrome のメインプロセスおよびヘルパー・プロセス）が起動されました
if result.success:
processes = result.data
print(f"{len(processes)} 個のプロセスでアプリケーションが起動しました")
# 出力例: 6 個のプロセスでアプリケーションが起動しました
for process in processes:
print(f"プロセス: {process.pname} (PID: {process.pid})")
# 出力例:
# プロセス: chrome (PID: 4443)
# プロセス: cat (PID: 4448)
# プロセス: cat (PID: 4449)
# プロセス: chrome (PID: 4459)
# プロセス: chrome (PID: 4460)
# プロセス: chrome (PID: 4462)
else:
print(f"アプリケーションの起動に失敗しました: {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
# 検証: success = True
# 検証: アプリケーションが指定された作業ディレクトリで起動されました
if result.success:
processes = result.data
print(f"{len(processes)} 個のプロセスでアプリケーションが起動しました")
# 出力例: 6 個のプロセスでアプリケーションが起動しました
else:
print(f"アプリケーションの起動に失敗しました: {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"{target_app.name} を起動しています...")
# 出力例: Google Chrome を起動しています...
start_result = session.computer.start_app(target_app.start_cmd)
# 検証: アプリケーションの起動に成功しました
if start_result.success:
print("アプリケーションの起動に成功しました！")
# 出力例: アプリケーションの起動に成功しました！
else:
print(f"起動に失敗しました: {start_result.error_message}")
else:
print("対象アプリケーションが見つかりません")アプリケーションの停止
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.pname} (PID: {process.pid})")
# 出力例:
# プロセス: chrome (PID: 6378)
# プロセス: cat (PID: 6383)
# プロセス: 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
# 検証: success = True
if result.success:
print(f"PID {target_pid} のプロセスを正常に停止しました")
# 出力例: PID 6378 のプロセスを正常に停止しました
else:
print(f"プロセスの停止に失敗しました: {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.pname} (PID: {process.pid})")
target_pname = process.pname
break
# 検証: 「chrome」というプロセス名が取得されました
if target_pname:
result = session.computer.stop_app_by_pname(target_pname)
# 検証: 戻り値の型は AppOperationResult
# 検証: success = True
if result.success:
print(f"プロセス {target_pname} を正常に停止しました")
# 出力例: プロセス chrome を正常に停止しました
else:
print(f"プロセスの停止に失敗しました: {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("アプリケーションの起動に成功しました！")
result = session.computer.stop_app_by_cmd(target_app.stop_cmd)
# 検証: 戻り値の型は AppOperationResult
if result.success:
print("コマンドを使用してアプリケーションを正常に停止しました")
else:
print(f"アプリケーションの停止に失敗しました: {result.error_message}")実行中のアプリケーションの一覧表示
result = session.computer.list_visible_apps()
# 検証: 戻り値の型は ProcessListResult
# 検証: success = True
# 検証: 表示可能なウィンドウを持つアプリケーションが 1 個検出されました（chrome）
if result.success:
visible_apps = result.data
print(f"{len(visible_apps)} 個の実行中のアプリケーションが見つかりました")
# 出力例: 1 個の実行中のアプリケーションが見つかりました
for app in visible_apps:
print(f"プロセス: {app.pname}")
print(f"PID: {app.pid}")
print(f"コマンドライン: {app.cmdline}")
print("---")
# 出力例:
# プロセス: chrome
# PID: 6378
# コマンドライン: /opt/google/chrome/chrome
# ---
else:
print(f"エラー: {result.error_message}")Process オブジェクトの属性：
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 環境変数が必要です")
agent_bay = AgentBay(api_key=api_key)
params = CreateSessionParams(image_id="linux_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}")
# 出力例: セッションが作成されました: session-xxxxxxxxxxxxxxxxx
print("ステップ 1: インストール済みアプリケーションの検索中...")
apps_result = session.computer.get_installed_apps(
start_menu=True,
desktop=False,
ignore_system_apps=True
)
# 検証: 76 個のアプリケーションが正常に取得されました
if not apps_result.success:
print(f"アプリケーションの取得に失敗しました: {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 が見つかりません")
agent_bay.delete(session)
exit(1)
print(f"見つかったアプリケーション: {target_app.name}")
# 出力例: 見つかったアプリケーション: Google Chrome
print("ステップ 2: アプリケーションの起動中...")
start_result = session.computer.start_app(target_app.start_cmd)
# 検証: 6 個のプロセスが正常に起動されました
if not start_result.success:
print(f"アプリケーションの起動に失敗しました: {start_result.error_message}")
agent_bay.delete(session)
exit(1)
print(f"{len(start_result.data)} 個のプロセスでアプリケーションが起動しました")
# 出力例: 6 個のプロセスでアプリケーションが起動しました
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("ステップ 3: アプリケーションの読み込みを待機中...")
time.sleep(5)
print("ステップ 4: 実行中のアプリケーションを確認中...")
visible_result = session.computer.list_visible_apps()
# 検証: 表示可能なアプリケーションが 1 個検出されました
if visible_result.success:
print(f"{len(visible_result.data)} 個の表示可能なアプリケーションが見つかりました")
# 出力例: 1 個の表示可能なアプリケーションが見つかりました
print("ステップ 5: アプリケーションの停止中...")
if start_result.data:
stop_result = session.computer.stop_app_by_pid(start_result.data[0].pid)
# 検証: アプリケーションの停止に成功しました
if stop_result.success:
print("アプリケーションの停止に成功しました")
# 出力例: アプリケーションの停止に成功しました
else:
print(f"アプリケーションの停止に失敗しました: {stop_result.error_message}")
print("セッションのクリーンアップ中...")
agent_bay.delete(session)
print("ワークフローが完了しました！")
# 出力例: ワークフローが完了しました！
# === 完全なワークフローの検証結果 ===
# ✓ セッションの作成: 成功
# ✓ インストール済みアプリケーションの取得: 76 個のアプリケーションが見つかりました
# ✓ 対象アプリケーションの検出: Google Chrome が見つかりました
# ✓ アプリケーションの起動: 6 個のプロセスが起動しました
# ✓ 表示可能なアプリケーションの一覧表示: 1 個の表示可能なアプリケーションが見つかりました
# ✓ アプリケーションの停止: 正常に停止しました
# ✓ セッションのクリーンアップ: 成功API リファレンス
クラウドコンピューターのアプリケーション管理メソッド
すべてのアプリケーション管理メソッドは、session.computer.* を通じてアクセスできます：
メソッド | パラメーター | 戻り値 | 説明 |
|
|
| インストール済みアプリケーションの一覧を取得します |
|
|
| アプリケーションを起動します |
|
|
| PID を指定してアプリケーションを停止します |
|
|
| プロセス名を指定してアプリケーションを停止します |
|
|
| 停止コマンドを指定してアプリケーションを停止します |
| なし |
| 現在表示可能なアプリケーションを一覧表示します |
戻り値の型
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）：一意のリクエスト識別子。