クラウドデスクトップ上のアプリケーションウィンドウ制御とリサイズ - AgentBay

このトピックでは、Wuying 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}")
else:
    print(f"セッションの作成に失敗しました: {result.error_message}")
    exit(1)

ウィンドウのリストアップ

デスクトップ環境で利用可能なすべてのウィンドウに関する情報を取得できます。

result = session.computer.list_root_windows(timeout_ms=5000)

if result.success:
    windows = result.windows
    print(f"{len(windows)} 個のウィンドウが見つかりました")
    # 実行結果: 0 個のウィンドウが見つかりました (ウィンドウが開いていない場合)
    # または: 5 個のウィンドウが見つかりました (アプリケーションが実行中の場合)
    
    for window in windows:
        print(f"タイトル: {window.title}")
        # 実行結果: タイトル: Google Chrome
        print(f"ウィンドウ ID: {window.window_id}")
        # 実行結果: ウィンドウ ID: 12345678
        print(f"プロセス: {window.pname if window.pname else 'N/A'}")
        # 実行結果: プロセス: chrome
        print(f"PID: {window.pid if window.pid else 'N/A'}")
        # 実行結果: PID: 9876
        print(f"位置: ({window.absolute_upper_left_x}, {window.absolute_upper_left_y})")
        # 実行結果: 位置: (100, 50)
        print(f"サイズ: {window.width}x{window.height}")
        # 実行結果: サイズ: 1280x720
        print(f"子ウィンドウ: {len(window.child_windows)}")
        # 実行結果: 子ウィンドウ: 0
        print("---")
else:
    print(f"ウィンドウのリストアップエラー: {result.error_message}")

パラメーター:

timeout_ms (int, オプション): タイムアウト (ミリ秒)。デフォルト: 3000。

ウィンドウオブジェクト属性:

window_id (int): ウィンドウの一意の識別子。
title (str): ウィンドウのタイトルまたは説明テキスト。
absolute_upper_left_x (Optional[int]): ウィンドウの左上隅の X 座標。
absolute_upper_left_y (Optional[int]): ウィンドウの左上隅の Y 座標。
width (Optional[int]): ウィンドウの幅 (ピクセル単位)。
height (Optional[int]): ウィンドウの高さ (ピクセル単位)。
pid (Optional[int]): ウィンドウを所有するプロセスの ID。
pname (Optional[str]): ウィンドウを所有するプロセスの名前。
child_windows (List[Window]): 子ウィンドウのリスト。

ウィンドウコントロール操作

ウィンドウの状態と位置をコントロールできます。

ウィンドウのアクティブ化

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    activate_result = session.computer.activate_window(window_id)
    # 実行結果: ウィンドウが正常にアクティブ化されました
    
    if activate_result.success:
        print("ウィンドウが正常にアクティブ化されました")
    else:
        print(f"ウィンドウのアクティブ化に失敗しました: {activate_result.error_message}")

ウィンドウの最大化

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    maximize_result = session.computer.maximize_window(window_id)
    # 実行結果: ウィンドウが正常に最大化されました
    
    if maximize_result.success:
        print("ウィンドウが正常に最大化されました")
    else:
        print(f"ウィンドウの最大化に失敗しました: {maximize_result.error_message}")

ウィンドウの最小化

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    minimize_result = session.computer.minimize_window(window_id)
    # 実行結果: ウィンドウが正常に最小化されました
    
    if minimize_result.success:
        print("ウィンドウが正常に最小化されました")
    else:
        print(f"ウィンドウの最小化に失敗しました: {minimize_result.error_message}")

ウィンドウを元に戻す

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    restore_result = session.computer.restore_window(window_id)
    # 実行結果: ウィンドウが正常に元に戻されました
    
    if restore_result.success:
        print("ウィンドウが正常に元に戻されました")
    else:
        print(f"ウィンドウを元に戻すのに失敗しました: {restore_result.error_message}")

ウィンドウのサイズ変更

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    resize_result = session.computer.resize_window(window_id, 800, 600)
    # 実行結果: ウィンドウのサイズが 800x600 に変更されました
    
    if resize_result.success:
        print("ウィンドウのサイズが 800x600 に変更されました")
    else:
        print(f"ウィンドウのサイズ変更に失敗しました: {resize_result.error_message}")

ウィンドウの全画面表示

result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    fullscreen_result = session.computer.fullscreen_window(window_id)
    # 実行結果: ウィンドウが全画面に設定されました
    
    if fullscreen_result.success:
        print("ウィンドウが全画面に設定されました")
    else:
        print(f"全画面への設定に失敗しました: {fullscreen_result.error_message}")

ウィンドウを閉じる

# 注: この操作はウィンドウを永久に閉じるため、注意して使用してください。
result = session.computer.list_root_windows()

if result.success and result.windows:
    window_id = result.windows[0].window_id
    
    close_result = session.computer.close_window(window_id)
    
    if close_result.success:
        print("ウィンドウが正常に閉じられました")
    else:
        print(f"ウィンドウを閉じるのに失敗しました: {close_result.error_message}")

完全なウィンドウコントロール関数

import time

def control_window(session, window_id):
    print(f"ウィンドウ ID をコントロールしています: {window_id}")
    
    try:
        session.computer.activate_window(window_id)
        print("ウィンドウがアクティブ化されました")
    except Exception as e:
        print(f"アクティブ化に失敗しました: {e}")
    
    time.sleep(1)
    
    try:
        session.computer.maximize_window(window_id)
        print("ウィンドウが最大化されました")
    except Exception as e:
        print(f"最大化に失敗しました: {e}")
    
    time.sleep(1)
    
    try:
        session.computer.minimize_window(window_id)
        print("ウィンドウが最小化されました")
    except Exception as e:
        print(f"最小化に失敗しました: {e}")
    
    time.sleep(1)
    
    try:
        session.computer.restore_window(window_id)
        print("ウィンドウが元に戻されました")
    except Exception as e:
        print(f"元に戻すのに失敗しました: {e}")
    
    try:
        session.computer.resize_window(window_id, 800, 600)
        print("ウィンドウのサイズが 800x600 に変更されました")
    except Exception as e:
        print(f"サイズ変更に失敗しました: {e}")

windows = session.computer.list_root_windows()
if windows.success and windows.windows:
    control_window(session, windows.windows[0].window_id)

フォーカス管理

システムのフォーカス動作をコントロールして、ウィンドウがフォーカスを奪うのを防ぐことができます。

try:
    session.computer.focus_mode(True)
    # 実行結果: フォーカスモードが有効になりました - ウィンドウはフォーカスを奪いません
    print("フォーカスモードが有効になりました - ウィンドウはフォーカスを奪いません")
except Exception as e:
    print(f"フォーカスモードの有効化に失敗しました: {e}")

try:
    session.computer.focus_mode(False)
    # 実行結果: フォーカスモードが無効になりました
    print("フォーカスモードが無効になりました")
except Exception as e:
    print(f"フォーカスモードの無効化に失敗しました: {e}")

パラメーター:

on (bool): True に設定するとフォーカスモードが有効になり、False に設定すると無効になります。

アクティブなウィンドウの取得

現在アクティブなウィンドウに関する情報を取得できます。

# 注: アクティブなウィンドウがない場合、この操作は失敗することがあります。
result = session.computer.get_active_window(timeout_ms=5000)

if result.success:
    active_window = result.window
    # 実行結果 (ウィンドウがアクティブな場合):
    # アクティブなウィンドウ:
    #   タイトル: Google Chrome
    #   ウィンドウ ID: 87654321
    #   プロセス: chrome
    #   PID: 4321
    #   位置: (0, 0)
    #   サイズ: 1920x1080
    print(f"アクティブなウィンドウ:")
    print(f"  タイトル: {active_window.title}")
    print(f"  ウィンドウ ID: {active_window.window_id}")
    print(f"  プロセス: {active_window.pname}")
    print(f"  PID: {active_window.pid}")
    print(f"  位置: ({active_window.absolute_upper_left_x}, {active_window.absolute_upper_left_y})")
    print(f"  サイズ: {active_window.width}x{active_window.height}")
else:
    # 実行結果 (アクティブなウィンドウがない場合):
    # アクティブなウィンドウの取得に失敗しました: レスポンスエラー (アクティブなウィンドウがない場合の期待される結果)
    print(f"アクティブなウィンドウの取得に失敗しました: {result.error_message}")

パラメーター:

timeout_ms (int, オプション): タイムアウト (ミリ秒)。デフォルト: 3000。

完全なワークフローの例

次の例は、アプリケーションを起動し、そのウィンドウをコントロールする方法を示しています。

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-04bdwfj7u688ec96t

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

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)

if not start_result.success:
    print(f"アプリケーションの起動に失敗しました: {start_result.error_message}")
    agent_bay.delete(session)
    exit(1)

print(f"アプリケーションが起動し、{len(start_result.data)} 個のプロセスが開始されました")
# 実行結果: アプリケーションが起動し、6 個のプロセスが開始されました

print("ステップ 3: アプリケーションウィンドウの読み込みを待機...")
time.sleep(5)

print("ステップ 4: アプリケーションウィンドウを検索...")
windows_result = session.computer.list_root_windows()

if not windows_result.success:
    print(f"ウィンドウのリストアップに失敗しました: {windows_result.error_message}")
    agent_bay.delete(session)
    exit(1)

app_window = None
for window in windows_result.windows:
    if target_app.name.lower() in window.title.lower():
        app_window = window
        break

if not app_window and windows_result.windows:
    app_window = windows_result.windows[0]
    print("利用可能な最初のウィンドウを使用しています")

if app_window:
    print(f"ウィンドウが見つかりました: {app_window.title}")
    # 実行結果: ウィンドウが見つかりました: Welcome to Google Chrome
    
    print("ステップ 5: ウィンドウをコントロール...")
    try:
        session.computer.activate_window(app_window.window_id)
        print("ウィンドウがアクティブ化されました")
        # 実行結果: ウィンドウがアクティブ化されました
        
        time.sleep(1)
        session.computer.maximize_window(app_window.window_id)
        print("ウィンドウが最大化されました")
        # 実行結果: ウィンドウが最大化されました
        
        time.sleep(1)
        session.computer.resize_window(app_window.window_id, 1024, 768)
        print("ウィンドウのサイズが 1024x768 に変更されました")
        # 実行結果: ウィンドウのサイズが 1024x768 に変更されました
        
    except Exception as e:
        print(f"ウィンドウコントロールに失敗しました: {e}")

print("セッションをクリーンアップしています...")
agent_bay.delete(session)
print("ワークフローが完了しました！")
# 実行結果: セッションが正常に削除されました

API リファレンス

ウィンドウマネージャーのメソッド

メソッド	パラメーター	戻り値	説明
`list_root_windows()`	`timeout_ms: int = 3000`	`WindowListResult`	すべてのルートウィンドウをリストアップします
`get_active_window()`	`timeout_ms: int = 3000`	`WindowInfoResult`	現在アクティブなウィンドウを取得します
`activate_window()`	`window_id: int`	`BoolResult`	ウィンドウをアクティブ化します
`maximize_window()`	`window_id: int`	`BoolResult`	ウィンドウを最大化します
`minimize_window()`	`window_id: int`	`BoolResult`	ウィンドウを最小化します
`restore_window()`	`window_id: int`	`BoolResult`	ウィンドウを元に戻します
`close_window()`	`window_id: int`	`BoolResult`	ウィンドウを閉じます
`fullscreen_window()`	`window_id: int`	`BoolResult`	ウィンドウを全画面表示にします
`resize_window()`	`window_id: int`<br/>`width: int`<br/>`height: int`	`BoolResult`	ウィンドウのサイズを変更します
`focus_mode()`	`on: bool`	`BoolResult`	フォーカスモードを切り替えます

戻り値の型

WindowListResult

success (bool): 操作が成功したかどうかを示します。
windows (List[Window]): ウィンドウオブジェクトのリスト。
error_message (str): 操作が失敗した場合のエラーメッセージ。
request_id (str): 一意のリクエスト識別子。

Window

window_id (int): ウィンドウの一意の識別子。
title (str): ウィンドウのタイトルまたは説明テキスト。
absolute_upper_left_x (Optional[int]): ウィンドウの左上隅の X 座標。
absolute_upper_left_y (Optional[int]): ウィンドウの左上隅の Y 座標。
width (Optional[int]): ウィンドウの幅 (ピクセル単位)。
height (Optional[int]): ウィンドウの高さ (ピクセル単位)。
pid (Optional[int]): ウィンドウを所有するプロセスの ID。
pname (Optional[str]): ウィンドウを所有するプロセスの名前。
child_windows (List[Window]): 子ウィンドウのリスト。

WindowInfoResult

success (bool): 操作が成功したかどうかを示します。
window (Window): ウィンドウオブジェクト。
error_message (str): 操作が失敗した場合のエラーメッセージ。
request_id (str): 一意のリクエスト識別子。

BoolResult

success (bool): 操作が成功したかどうかを示します。
data (bool): 操作の結果データ。
error_message (str): 操作が失敗した場合のエラーメッセージ。
request_id (str): 一意のリクエスト識別子。