浏览器操作系统操作

该 InvokeBrowser API 提供对 Amazon Bedrock AgentCore 浏览器会话的直接操作系统级控制。虽然 WebSocket-based 自动化端点使用 Chrome DevTools 协议 (CDP) 进行浏览器交互，但在操作系统级别 InvokeBrowser 运行，从而启用 CDP 无法处理的操作，例如与打印对话框、键盘快捷键、右键单击上下文菜单、 JavaScript 警报和捕获全屏屏幕截图。

概述

Amazon Bed AgentCore rock 浏览器提供了两种与浏览器会话交互的方式：

WebSocket-based 自动化 (CDP)：通过 WebSocket 连接使用 Chrome DevTools 协议。这非常适合标准的浏览器自动化任务，例如浏览页面、单击 DOM 元素、填写表单和提取页面内容。像 Playwright 这样的库和浏览器使用的库通过这个端点进行连接。
OS-level actions (InvokeBrowser)：使用 REST API 通过鼠标、键盘和屏幕截图操作执行操作系统级交互。这通过处理浏览器级自动化不足的场景来补充 CDP。

InvokeBrowser 当您的代理需要执行以下操作时使用：

与浏览器 DOM 之外的本机操作系统对话框（例如打印 upload/download 对话框、文件对话框或身份验证提示）进行交互
解除阻止 CDP 执行的 JavaScript 警报、确认或提示
使用触发行为的键盘快捷键（例如 ctrl+a、ctrl+p） OS-level
与操作系统呈现的右键单击上下文菜单进行交互
捕获包含浏览器视口之外的内容的完整桌面屏幕截图，例如操作系统通知或多窗口布局
执行跨浏览器窗口或浏览器与桌面之间的拖放操作

InvokeBrowser 遵循与以下模式相同的模式 InvokeCodeInterpreter：具有动作类型调度的单一统一操作。您发送的请求只包含一个操作，并收到相应的结果。

支持的操作

InvokeBrowser 通过BrowserAction联合支持以下操作类型。每个请求必须设置一个操作成员。

鼠标动作

对于所有鼠标操作，坐标值 (x,y) 必须严格位于浏览器会话视口范围内。有效范围为 1 < x < 视口Width-2 和 1 < y < 视Height-2口。默认视口大小为 1456×819 像素，可以在启动会话时使用参数进行配置。viewPort

处理建议	必填字段	可选字段	说明
`mouseClick`	`x`（整数）、`y`（整数）	`button`(MouseButton)、`clickCount`（整数）	在指定的坐标处单击。 `clickCount`: 1—10。 `button`: 左、右、中。
`mouseMove`	`x`（整数）、`y`（整数）	—	将光标移动到指定的坐标。
`mouseDrag`	`startX`（整数）、`startY`（整数）、`endX`（整数）、`endY`（整数）	`button` (MouseButton)	从起点拖动到终点位置。 `button`默认为左。
`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)	捕获完整的操作系统桌面（而不仅仅是浏览器视口）。格式：仅限 PNG。

注意事项

ASCII-only 文本输入：该keyType操作仅支持 ASCII 字符。 Non-ASCII 在输入过程中会跳过字符（例如 Unicode 或多字节字符）。
不验证密钥名称：keyPress和keyShortcut操作不验证是否支持指定的密钥名称。如果您提供的密钥名称无法识别，API 将返回成功状态而不执行预期的操作。请参阅上面列出的支持的密钥名称。
支持的密钥名称：keyPress和keyShortcut操作的密钥名称必须使用小写。支持的密钥包括单个字符 (a— z、0 —9) 和命名密钥enter，例如、、tab、space、、backspace、delete、escape、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
        }
    }
}

响应

通过x-amzn-browser-session-id响应标头返回。sessionId响应正文包含一个带有相应操作结果的result字段。

成功时：


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

失败时，该status字段设置为 FAILED，该error字段包含对失败的描述。

示例

以下示例展示了如何使用 AWS CLI、 AWS 适用于 Python 的 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 在您的浏览器中被禁用或不可用。

要使用 Amazon Web Services 文档，必须启用 Javascript。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

根证书颁发机构

AgentCore 浏览器疑难解答