AgentBay SDK によるマウス、キーボード、画面キャプチャの自動化 - AgentBay

このトピックでは、デスクトップ環境におけるクラウドコンピューター向けの Wuying AgentBay SDK の UI 自動化機能について説明します。これらの機能は、マウス、キーボード、および画面操作をサポートしています。

概要

「Computer Use」モジュールは、クラウドコンピュータ向けの強力な UI 自動化機能を提供し、以下を含みます：

マウス操作 — クリック、移動、ドラッグ、スクロールを正確に制御します。
キーボード操作 — テキストを入力し、キーの組み合わせを送信します。
画面操作 — スクリーンショットを取得し、画面情報を取得します。

セッションの作成

from agentbay import AgentBay
from agentbay.session_params import CreateSessionParams

agent_bay = AgentBay()
# Use windows_latest or linux_latest
session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

マウス操作

クリック操作

click_mouse() メソッドは、複数のクリックタイプをサポートします。型安全性を確保するには、MouseButton 列挙を使用します。サポートされるボタンの種類は、以下のとおりです。

MouseButton.LEFT
MouseButton.RIGHT
MouseButton.MIDDLE
MouseButton.DOUBLE_LEFT

from agentbay.computer import MouseButton

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

# Left-click
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.LEFT)
if result.success:
    print("Left-click successful")
# Output: Left-click successful

# Right-click
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.RIGHT)
if result.success:
    print("Right-click successful")
# Output: Right-click successful

# Middle-click
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.MIDDLE)
if result.success:
    print("Middle-click successful")
# Output: Middle-click successful

# Double-click with the left button
result = session.computer.click_mouse(x=500, y=300, button=MouseButton.DOUBLE_LEFT)
if result.success:
    print("Double-click successful")
# Output: Double-click successful

agent_bay.delete(session)

マウスの移動

マウスカーソルを指定された座標に移動します。

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

result = session.computer.move_mouse(x=600, y=400)
if result.success:
    print("Mouse moved successfully")
# Output: Mouse moved successfully

agent_bay.delete(session)

マウスのドラッグ

MouseButton 列挙を使用して、マウスをあるポイントから別のポイントへドラッグします。サポートされているボタンの種類は次のとおりです。

MouseButton.LEFT
MouseButton.RIGHT
MouseButton.MIDDLE

from agentbay.computer import MouseButton

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

# Drag with the left button
result = session.computer.drag_mouse(
    from_x=100, 
    from_y=100, 
    to_x=200, 
    to_y=200, 
    button=MouseButton.LEFT
)
if result.success:
    print("Drag operation successful")
# Output: Drag operation successful

agent_bay.delete(session)

ホイールのスクロール

特定の座標でマウスホイールをスクロールするには、ScrollDirection 列挙を使用します。サポートされている方向は次のとおりです:

ScrollDirection.UP
ScrollDirection.DOWN
ScrollDirection.LEFT
ScrollDirection.RIGHT

from agentbay.computer import ScrollDirection

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

# Scroll up
result = session.computer.scroll(x=500, y=500, direction=ScrollDirection.UP, amount=3)
if result.success:
    print("Scroll up successful")
# Output: Scroll up successful

# Scroll down
result = session.computer.scroll(x=500, y=500, direction=ScrollDirection.DOWN, amount=5)
if result.success:
    print("Scroll down successful")
# Output: Scroll down successful

agent_bay.delete(session)

カーソル位置の取得

import json

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

result = session.computer.get_cursor_position()
if result.success:
    cursor_data = json.loads(result.data)
    print(f"Cursor is at x={cursor_data['x']}, y={cursor_data['y']}")
# Output: Cursor is at x=512, y=384

agent_bay.delete(session)

キーボード操作

テキスト入力

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

result = session.computer.input_text("Hello AgentBay!")
if result.success:
    print("Text input successful")
# Output: Text input successful

agent_bay.delete(session)

キーの押下

キーの組み合わせを入力します。修飾キーがサポートされています。

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

# Press Ctrl+A to select all
result = session.computer.press_keys(keys=["Ctrl", "a"])
if result.success:
    print("Key press successful")
# Output: Key press successful

# Press Ctrl+C to copy
result = session.computer.press_keys(keys=["Ctrl", "c"])
if result.success:
    print("Copy command sent")
# Output: Copy command sent

agent_bay.delete(session)

キーの解放

キー押下時に hold=True を設定すると、クラウドコンピュータはそのキーを押し続けます。関連する操作を完了した後は、他のキー操作との競合を回避するためにキーを解放します。

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

# Hold down the Ctrl key
session.computer.press_keys(keys=["Ctrl"], hold=True)

# ... Perform other operations ...

# Release the Ctrl key
result = session.computer.release_keys(keys=["Ctrl"])
if result.success:
    print("Key release successful")
# Output: Key release successful

agent_bay.delete(session)

画面操作

スクリーンショットの取得

現在の画面のスナップショットを取得します。スクリーンショットはクラウドストレージに保存され、ダウンロード URL が返されます。

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

result = session.computer.screenshot()
if result.success:
    screenshot_url = result.data
    print(f"Screenshot URL: {screenshot_url}")
# Output: Screenshot URL: https://***.***.aliyuncs.com/***/screenshot_1234567890.png?***

agent_bay.delete(session)

画面サイズの取得

import json

session_params = CreateSessionParams(image_id="windows_latest")
session = agent_bay.create(session_params).session

result = session.computer.get_screen_size()
if result.success:
    screen_data = json.loads(result.data)
    print(f"Screen width: {screen_data['width']}")
    print(f"Screen height: {screen_data['height']}")
    print(f"DPI zoom factor: {screen_data['dpiScalingFactor']}")
# Output: Screen width: 1024
# Output: Screen height: 768
# Output: DPI zoom factor: 1.0

agent_bay.delete(session)

トラブルシューティング

よくある質問

「ツールが見つかりません」エラー。
- 使用しているクラウドコンピュータイメージが windows_latest または linux_latest であることを確認してください。
スクリーンショット生成後に返されるダウンロードリンク (URL) の処理方法。
- スクリーンショットは Object Storage Service (OSS) に自動的に保存されます。
- result.data には、イメージデータではなくダウンロード URL が含まれています。
- この URL を使用してスクリーンショットをダウンロードします。