瀏覽器作業系統動作

InvokeBrowser API 提供對 Amazon Bedrock AgentCore 瀏覽器工作階段的直接作業系統層級控制。雖然 WebSocket 型自動化端點使用 Chrome DevTools 通訊協定 (CDP) 進行瀏覽器互動，但 InvokeBrowser 會在作業系統層級運作，啟用 CDP 無法處理的動作，例如與列印對話方塊、鍵盤快速鍵、滑鼠右鍵內容功能表、JavaScript 提醒和擷取全螢幕螢幕擷取畫面互動。

概觀

Amazon Bedrock AgentCore 瀏覽器提供兩種與瀏覽器工作階段互動的方式：

WebSocket 型自動化 (CDP) ：透過 WebSocket 連線使用 Chrome DevTools 通訊協定。這非常適合標準瀏覽器自動化任務，例如導覽頁面、按一下 DOM 元素、填寫表單和擷取頁面內容。透過此端點進行 Playwright 和瀏覽器使用等程式庫連線。
作業系統層級動作 (InvokeBrowser)：使用 REST API 透過滑鼠、鍵盤和螢幕擷取畫面動作執行作業系統層級互動。這透過處理瀏覽器層級自動化不足的情況來補充 CDP。

當您的代理程式需要下列項目時，請使用 InvokeBrowser：

與瀏覽器 DOM 外部的原生作業系統對話方塊互動，例如列印對話方塊、檔案上傳/下載對話方塊或身分驗證提示
停用封鎖 CDP 執行的 JavaScript 提醒、確認或提示
使用觸發作業系統層級行為的鍵盤快速鍵（例如 ctrl+a、ctrl+p)
與作業系統轉譯的右鍵內容功能表互動
擷取包含瀏覽器檢視區外內容的完整桌面螢幕擷取畫面，例如作業系統通知或多視窗配置
執行跨瀏覽器視窗或瀏覽器與桌面之間的drag-and-drop操作

InvokeBrowser 遵循與 InvokeCodeInterpreter 相同的模式：具有動作類型分派的單一統一操作。您可以只傳送一個動作的請求，並接收對應的結果。

支援的動作

InvokeBrowser 透過BrowserAction聯集支援下列動作類型。每個請求必須設定一個動作成員。

滑鼠動作

對於所有滑鼠動作，座標值 x (y、) 必須嚴格位於瀏覽器工作階段檢視區邊界內。有效範圍為 1 < x < viewportWidth-2 和 1 < y < viewportHeight-2。預設檢視區大小為 1456 × 819 像素，可在使用 viewPort 參數啟動工作階段時設定。

Action	必要欄位	選填欄位	說明
`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`捲動。

鍵盤動作

Action	必要欄位	選填欄位	說明
`keyType`	`text` (字串)	—	輸入文字字串。長度上限：10，000 個字元。
`keyPress`	`key` (字串)	`presses` （整數）	按按鍵 N 次。 `presses`：1–100。預設值為 1。
`keyShortcut`	`keys` (KeyList)	—	按按鍵組合 `["ctrl", "s"]` （例如，)。最多 5 個金鑰。

螢幕擷取畫面動作

Action	必要欄位	選填欄位	說明
`screenshot`	—	`format` (ScreenshotFormat)	擷取完整的作業系統桌面（不只是瀏覽器檢視區）。格式：僅限 PNG。

考量事項

僅限 ASCII 的文字輸入 ：keyType動作僅支援 ASCII 字元。輸入期間會略過非 ASCII 字元（例如 Unicode 或多位元組字元）。
沒有金鑰名稱驗證 ： keyPress和 keyShortcut動作不會驗證是否支援指定的金鑰名稱。如果您提供無法辨識的金鑰名稱，API 會傳回 SUCCESS 狀態，而不執行預期的動作。請參閱上述支援的金鑰名稱。
支援的金鑰名稱 ： keyPress和 keyShortcut動作的金鑰名稱必須為小寫。支援的金鑰包括單一字元 ( a – z 、 0 – 9 ) 和具名金鑰，例如 enter 、tab、、spacebackspace、deleteescape、ctrl、alt、shift。

請求和回應格式

請求


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

請求內文包含action一個欄位，其中只有一個BrowserAction聯集的成員：


{
    "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、適用於 Python 的 AWS SDK (Boto3) 和 API 叫用瀏覽器動作。

範例

AWS CLI

若要在特定位置按一下：


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

若要在特定位置按一下：


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

若要在特定位置按一下：


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"
        }
    }
  }'

您的瀏覽器已停用或無法使用 Javascript。

您必須啟用 Javascript，才能使用 AWS 文件。請參閱您的瀏覽器說明頁以取得說明。

文件慣用形式

根憑證授權單位

AgentCore 瀏覽器故障診斷