浏览器操作系统操作

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

概述

亚马逊 Bedrock AgentCore 浏览器提供了两种与浏览器会话交互的方式：

WebSocket-based 自动化 (CDP)：通过 WebSocket 连接使用 Chrome DevTools 协议。这非常适合标准浏览器自动化任务，例如浏览页面、单击 DOM 元素、填写表单和提取页面内容。像 Playwright 和 browser-use 这样的库通过这个端点进行连接。
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`默认为 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)	捕获完整的操作系统桌面（不仅仅是浏览器视口）。格式：仅限 PNG。

注意事项

ASCII-only 文本输入：该keyType操作仅支持 ASCII 字符。 Non-ASCII 输入期间会跳过字符（例如 Unicode 或多字节字符）。
不验证密钥名称：keyPress和keyShortcut操作不验证是否支持指定的密钥名称。如果您提供无法识别的密钥名称，则 API 将在不执行预期操作的情况下返回 SUCCESS 状态。请参阅上面列出的支持的密钥名称。
支持的密钥名称：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、Python AWS 开发工具包 (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。请参阅浏览器的帮助页面以了解相关说明。

文档惯例

根证书颁发机构

文件系统配置