View a markdown version of this page

Browser OS アクション - Amazon Bedrock AgentCore
概要サポートされているアクション考慮事項リクエストとレスポンスの形式例

Browser OS アクション

InvokeBrowser API は、Amazon Bedrock AgentCore Browser セッションを直接オペレーティングシステムレベルで制御します。WebSocket ベースのオートメーションエンドポイントはブラウザの操作に Chrome DevTools Protocol (CDP) を使用しますが、InvokeBrowser は OS レベルで動作し、印刷ダイアログ、キーボードショートカット、右クリックコンテキストメニュー、JavaScript アラート、全画面スクリーンショットのキャプチャなど、CDP が処理できないアクションを有効にします。

概要

Amazon Bedrock AgentCore ブラウザには、ブラウザセッションを操作する 2 つの方法があります。

  • WebSocket ベースの自動化 (CDP) : WebSocket 接続経由で Chrome DevTools プロトコルを使用します。これは、ページの移動、DOM 要素のクリック、フォームの入力、ページコンテンツの抽出などの標準的なブラウザ自動化タスクに最適です。Playwright やブラウザ使用などのライブラリは、このエンドポイントを介して接続します。

  • OS レベルのアクション (InvokeBrowser) : REST API を使用して、マウス、キーボード、スクリーンショットのアクションを通じてオペレーティングシステムレベルのインタラクションを実行します。これは、ブラウザレベルの自動化が不十分なシナリオを処理することで CDP を補完します。

エージェントが以下を行う必要がある場合はInvokeBrowser を使用します。

  • ブラウザ DOM の外部にある印刷ダイアログ、ファイルのアップロード/ダウンロードダイアログ、認証プロンプトなどのネイティブ OS ダイアログを操作する

  • CDP 実行をブロックする JavaScript アラート、確認、またはプロンプトを却下する

  • OS レベルの動作をトリガーするキーボードショートカット (ctrl+a、ctrl+p など) を使用する

  • オペレーティングシステムによってレンダリングされた右クリックコンテキストメニューを操作する

  • OS 通知やマルチウィンドウレイアウトなど、ブラウザビューポート外のコンテンツを含むデスクトップ全体のスクリーンショットをキャプチャする

  • ブラウザウィンドウ間またはブラウザとデスクトップ間のdrag-and-drop操作を実行する

InvokeBrowser は、InvokeCodeInterpreter と同じパターンに従います。アクションタイプのディスパッチを使用した単一の統合オペレーションです。1 つのアクションのみでリクエストを送信し、対応する結果を受け取ります。

サポートされているアクション

InvokeBrowser は、 BrowserActionユニオンを通じて次のアクションタイプをサポートしています。リクエストごとに 1 つのアクションメンバーを設定する必要があります。

マウスアクション

すべてのマウスアクションで、座標値 (、y) x はブラウザセッションビューポートの境界内に厳密に存在する必要があります。有効な範囲は 1 < x < viewportWidth-2 と 1 < y < viewportHeight-2 です。デフォルトのビューポートサイズは 1456 x 819 ピクセルで、 viewPortパラメータを使用してセッションを開始するときに設定できます。

アクション 必須フィールド 任意フィールド 説明

mouseClick

x (整数）、 y (整数)

button (MouseButton)、 clickCount (整数)

指定された座標をクリックします。 clickCount: 1～10。 button: 左、右、中間。

mouseMove

x (整数）、 y (整数)

—

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

mouseDrag

startX (整数）、 startY (整数）、 endX (整数）、 endY (整数)

button (MouseButton)

開始位置から終了位置までドラッグします。 のbuttonデフォルトは LEFT です。

mouseScroll

x (整数）、 y (整数)

deltaX (整数）、 deltaY (整数)

指定された位置までスクロールします。deltaX/deltaY: -1000～1000。負のdeltaYスクロールダウン。

キーボードアクション

アクション 必須フィールド 任意フィールド 説明

keyType

text (文字列)

—

テキストの文字列を入力します。最大長: 10,000 文字。

keyPress

key (文字列)

presses (整数)

キーを N 回押します。 presses: 1～100。デフォルトは 1 です。

keyShortcut

keys (KeyList)

—

キーの組み合わせ ( など) ["ctrl", "s"] を押します。最大 5 つのキー。

スクリーンショットアクション

アクション 必須フィールド 任意フィールド 説明

screenshot

—

format (ScreenshotFormat)

OS デスクトップ全体 (ブラウザビューポートだけでなく) をキャプチャします。形式: PNG のみ。

考慮事項

  • ASCII のみのテキスト入力: keyTypeアクションは ASCII 文字のみをサポートします。ASCII 以外の文字 (Unicode やマルチバイト文字など) は、入力中にスキップされます。

  • キー名の検証なし: keyPressおよび keyShortcutアクションは、指定されたキー名がサポートされているかどうかを検証しません。認識されないキー名を指定すると、API は意図したアクションを実行せずに SUCCESS ステータスを返します。上記のサポートされているキー名を参照してください。

  • サポートされているキー名 : keyPressおよび keyShortcutアクションのキー名は小文字である必要があります。サポートされているキーには、単一文字 ( a – z 、 0 – 9 ) tab とenter、、、、space、backspace、、、、 delete などの名前付きキーが含まれますescapectrlaltshift。

リクエストとレスポンスの形式

[リクエスト]

POST /browsers/{browserIdentifier}/sessions/invoke HTTP/1.1
x-amzn-browser-session-id: sessionId
Content-type: application/json

リクエスト本文には、BrowserActionユニオンセットの 1 つのメンバーのみを含む actionフィールドが含まれています。

{
    "action": {
        "mouseClick": {
            "x": 100,
            "y": 200,
            "button": "LEFT",
            "clickCount": 1
        }
    }
}

[応答]

sessionId はレスポンスx-amzn-browser-session-idヘッダーを介して返されます。レスポンス本文には、対応するアクション結果を含むresultフィールドが含まれます。

成功時:

{
    "result": {
        "mouseClick": {
            "status": "SUCCESS",
            "error": null
        }
    }
}

失敗した場合、 statusフィールドは FAILED に設定され、 errorフィールドには失敗の説明が含まれます。

例

次の例は、 AWS CLI、 AWS SDK for Python (Boto3)、および API を使用してブラウザアクションを呼び出す方法を示しています。

例
AWS CLI

  1. 特定の位置をクリックします。

    aws bedrock-agentcore invoke-browser \
  --region <Region> \
  --browser-identifier "aws.browser.v1" \
  --session-id "<your-session-id>" \
  --action '{"mouseClick": {"x": 100, "y": 200, "button": "LEFT", "clickCount": 1}}'

    テキストを入力するには:

    aws bedrock-agentcore invoke-browser \
  --region <Region> \
  --browser-identifier "aws.browser.v1" \
  --session-id "<your-session-id>" \
  --action '{"keyType": {"text": "Hello, world!"}}'

    キーボードショートカットを押すには:

    aws bedrock-agentcore invoke-browser \
  --region <Region> \
  --browser-identifier "aws.browser.v1" \
  --session-id "<your-session-id>" \
  --action '{"keyShortcut": {"keys": ["ctrl", "s"]}}'

    スクリーンショットを撮るには:

    aws bedrock-agentcore invoke-browser \
  --region <Region> \
  --browser-identifier "aws.browser.v1" \
  --session-id "<your-session-id>" \
  --action '{"screenshot": {"format": "PNG"}}'
Boto3

  1. 特定の位置をクリックします。

    response = dp_client.invoke_browser(
    browserIdentifier="aws.browser.v1",
    sessionId="<your-session-id>",
    action={
        "mouseClick": {
            "x": 100,
            "y": 200,
            "button": "LEFT",
            "clickCount": 1
        }
    }
)
print(f"Status: {response['result']['mouseClick']['status']}")

    テキストを入力するには:

    response = dp_client.invoke_browser(
    browserIdentifier="aws.browser.v1",
    sessionId="<your-session-id>",
    action={
        "keyType": {
            "text": "Hello, world!"
        }
    }
)

    スクリーンショットを撮って保存するには:

    import base64

response = dp_client.invoke_browser(
    browserIdentifier="aws.browser.v1",
    sessionId="<your-session-id>",
    action={
        "screenshot": {
            "format": "PNG"
        }
    }
)

if response['result']['screenshot']['status'] == 'SUCCESS':
    image_data = base64.b64decode(response['result']['screenshot']['data'])
    with open("screenshot.png", "wb") as f:
        f.write(image_data)
    print("Screenshot saved as screenshot.png")
API

  1. 特定の位置をクリックします。

    awscurl -X POST \
  "https://bedrock-agentcore.<Region>.amazonaws.com/browsers/aws.browser.v1/sessions/invoke" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-amzn-browser-session-id: <your-session-id>" \
  --service bedrock-agentcore \
  --region <Region> \
  -d '{
    "action": {
        "mouseClick": {
            "x": 100,
            "y": 200,
            "button": "LEFT",
            "clickCount": 1
        }
    }
  }'

    スクリーンショットを撮るには:

    awscurl -X POST \
  "https://bedrock-agentcore.<Region>.amazonaws.com/browsers/aws.browser.v1/sessions/invoke" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -H "x-amzn-browser-session-id: <your-session-id>" \
  --service bedrock-agentcore \
  --region <Region> \
  -d '{
    "action": {
        "screenshot": {
            "format": "PNG"
        }
    }
  }'