在 Amazon Bedrock AgentCore Browser 中引入操作系统级操作

用于自动化网页工作流的人工智能（AI）智能体，运行在浏览器的网页层之内，也就是 Playwright 与浏览器开发者工具协议（Chrome DevTools Protocol，CDP）所暴露的文档对象模型（DOM）。AgentCore Browser 为此提供一个安全、隔离的浏览器环境，并且对绝大多数自动化都很适用：浏览页面、填写表单、点击元素、提取内容。但网页层有一条硬边界。操作系统所渲染的任何东西（原生对话框、安全提示、证书选择器、上下文菜单，甚至浏览器设置）都完全位于 DOM 之外。CDP 看不见它们，Playwright 也无法与它们交互。

当一个网页应用调用 window.print() 并出现系统打印对话框时，Playwright 没有可以交互的 DOM。当一个工作流需要键盘快捷键或右键上下文菜单时，CDP 没有机制在操作系统层面发出这些命令。当一次浏览器会话遇到 macOS 隐私对话框、Windows 安全提示或证书选择器时，这些东西对网页自动化层是不可见的。这类情形往往会在生产环境中出现。它们由特定的应用状态、操作系统配置或用户权限触发，而不是出现在测试中；在测试里，网页内容足够可预测，因而能够对照验证。

对启用视觉的智能体而言，这个挑战还会叠加。一种常见架构是：截取一张屏幕截图，把它发给模型，收回坐标或指令，然后执行。这个循环对网页内容效果很好，但在原生用户界面出现的那一刻就会中断。屏幕截图能拍到它，模型能对它推理，然后却没有任何东西可以用来行动。CDP 够不到操作系统所渲染的内容。智能体正好看见该做什么，却没有办法去做。

我们宣布为 AgentCore Browser 提供操作系统级操作（OS Level Actions）。这项新能力通过 InvokeBrowser API 暴露直接的操作系统控制，从而打通这些场景，使智能体可以与屏幕上可见的内容交互，而不只是与浏览器网页层所能访问的内容交互。把完整桌面屏幕截图与操作系统层面的鼠标和键盘控制结合起来，智能体就可以在同一次会话中观察原生用户界面、对它推理，并采取行动。本文说明操作系统级操作如何工作、支持哪些操作，以及如何开始使用。

操作系统级操作如何工作

操作系统级操作可用于新建的和已有的浏览器配置，无需额外设置。会话处于活动状态之后，你通过 InvokeBrowser API 分发操作。每一次调用只携带一个操作，由它的类型和参数标识，并返回 SUCCESS 或 FAILED 状态。活动会话用 x-amzn-browser-session-id 头来标识，该头把每一次操作系统级操作绑定到正确的浏览器会话。

预期的交互模式是一个“操作—屏幕截图—反应”循环。智能体采取一个操作（点击、输入或快捷键），截取一张屏幕截图以观察屏幕的当前状态，然后根据它所看到的内容决定下一个操作。这个循环让智能体能够对动态用户界面作出反应。这包括可能在工作流中途出现的原生对话框和操作系统提示。

1. 智能体发送一个操作。这可以是使用 InvokeBrowser 的一次鼠标点击、按键或快捷键。
2. AgentCore 在完整的操作系统桌面上执行该操作，并返回 SUCCESS 或 FAILED。
3. 智能体请求一张屏幕截图，以观察当前屏幕状态。
4. AgentCore 捕获完整桌面，包括原生对话框、操作系统模态框，以及浏览器窗口之外的用户界面，并返回一张采用 Base64 编码的 PNG。
5. 智能体对屏幕截图进行推理，把它发给一个视觉模型，以判断发生了什么以及下一步做什么。
6. 智能体根据所观察到的内容发送下一个操作，并继续这个循环。

支持的操作

操作系统级操作分为三类：鼠标控制、键盘输入和视觉捕获。下表概括八种操作及其字段与约束。

鼠标操作

鼠标操作覆盖指针交互的全部范围：点击、移动、拖拽和滚动。对 mouseClick 而言，坐标字段是可选的。如果省略，点击落在当前光标位置，并使用左键单击。当先前的一次 mouseMove 已经把光标就位时，这很有用。mouseDrag 需要四个坐标，即起点和终点位置。mouseScroll 接受一个位置以及两个轴上的增量值——负的 deltaY 向下滚动，正值向上滚动。例如，右键上下文菜单就是一次 mouseClick，在目标坐标处把 button 设为 RIGHT。请注意，由于浏览器会话运行在虚拟化环境中，某些上下文菜单项可能不会按预期工作。

键盘操作

三种键盘操作覆盖不同层次的输入。keyType 用于输入文本。它直接发送字符，并处理最长 10,000 个字符的字符串。keyPress 用于必须被重复按下的单个键，例如用 tab 在表单字段之间前进，或用 escape 关闭一个模态框。keyShortcut 用于组合键——传入一个键名数组，AgentCore 会同时按下它们。

keyPress 与 keyShortcut 的键名必须为小写。支持的键包括单个字符（a–z、0–9），以及命名键，例如 enter、tab、space、backspace、delete、escape、ctrl、alt 和 shift。

例如，要选中全部文本，你会使用 keyShortcut，并传入 ["ctrl", "a"]。

{
  "action": {
    "keyShortcut": {
      "keys": ["ctrl", "a"]
    }
  }
}

屏幕截图

screenshot 操作捕获完整的操作系统桌面，并在响应中返回一张 Base64 编码的 PNG。它是唯一返回数据的操作。其他操作只返回一个状态（SUCCESS 或 FAILED），并在失败时返回一个错误字段。

{
   "action":{
      "screenshot":{
         "format":"PNG"
      }
   }
}

开始使用

下面的示例按配套笔记本的方式，走一遍“操作—屏幕截图—反应”循环。配套笔记本端到端演示了全部八种操作；完整可运行的笔记本从那里开始。

设置客户端并创建浏览器

你需要两个客户端：一个控制面客户端（bedrock-agentcore-control），用于管理浏览器资源；一个数据面客户端（bedrock-agentcore），用于在会话期间分发操作。

import boto3
import time

browser_boto3 = boto3.client('bedrock-agentcore-control', region_name='us-west-2')

BROWSER_NAME = "browser_with_os_actions"

在启动会话之前，你需要一个 AWS 身份与访问管理（IAM）执行角色，以及一个浏览器资源。该执行角色需要 bedrock-agentcore:InvokeBrowser、bedrock-agentcore:StartBrowserSession 和 bedrock-agentcore:StopBrowserSession 权限。配套笔记本包含一个为你创建该角色的辅助函数：

from helpers.utils import create_agentcore_execution_role, SAMPLE_ROLE_NAME

execution_role_arn = create_agentcore_execution_role(SAMPLE_ROLE_NAME)

角色创建之后，创建一个自定义浏览器：

created_browser = browser_boto3.create_browser(
    name=BROWSER_NAME,
    executionRoleArn=execution_role_arn,
    networkConfiguration={
        'networkMode': 'PUBLIC'
    }
)

browser_id = created_browser['browserId']
print(f"Browser ID: {browser_id}")

启动浏览器会话

浏览器资源创建之后，启动一个会话。viewPort 设置屏幕分辨率。它决定鼠标操作的坐标空间，以及所捕获屏幕截图的尺寸。sessionTimeoutSeconds 控制会话在被自动终止之前可以存活多久。

# These helpers are included in the companion notebook repository
from helpers.browser import get_credentials, invoke, start_session, stop_session

creds, default_region = get_credentials()
BEDROCK_AGENTCORE_DP_ENDPOINT = f"https://bedrock-agentcore.{default_region}.amazonaws.com/"

sid = start_session(BEDROCK_AGENTCORE_DP_ENDPOINT, browser_id, region=default_region, credentials=creds)

# Wait for session to initialize — adjust if needed for your environment
time.sleep(3)

start_session 辅助函数发送一个经过签名版本 4（SigV4）签名的 PUT 请求来创建会话，并返回 sessionId。invoke 辅助函数负责为单个操作签名并分发。

调用一次操作系统级操作

会话运行之后，你可以通过 invoke 辅助函数分发操作系统级操作。每一次调用只接受一个操作——在这个例子中，是屏幕坐标 (600, 370) 处的一次左键点击：

r = invoke(
    BEDROCK_AGENTCORE_DP_ENDPOINT, sid,
    {"mouseClick": {"x": 600, "y": 370, "button": "LEFT"}},
    region=default_region, credentials=creds, browser_id=browser_id
)

print(f"Mouse click status: {r.status_code}, action: {r.json()['result']}")

响应会告诉你该操作是成功还是失败。坐标对应屏幕像素。如果会话视口是 1920×1080，有效的 x 值范围是 0 到 1919，y 是 0 到 1079。超出屏幕尺寸的坐标会返回 ValidationException。

捕获屏幕截图

每一次操作之后，智能体必须观察发生了什么。screenshot 操作捕获完整桌面，并把图像作为 Base64 编码的 PNG 返回：

import base64
from IPython.display import Image, display

r = invoke(
    BEDROCK_AGENTCORE_DP_ENDPOINT, sid,
    {"screenshot": {"format": "PNG"}},
    region=default_region, credentials=creds, browser_id=browser_id
)

img_bytes = base64.b64decode(r.json()['result']['screenshot']['data'])
display(Image(img_bytes))

这是循环中的观察步骤。智能体把屏幕截图发给一个视觉模型，由该模型对屏幕上的内容进行推理，并返回下一步要采取的操作。这个周期重复，直到工作流完成。

合在一起：关闭一个打印对话框

下面是“操作—屏幕截图—反应”循环在实践中的样子。假设智能体浏览到一个会触发 window.print() 的页面，并出现一个原生打印对话框。智能体不能通过 CDP 与它交互，但可以用操作系统级操作做到。首先，智能体截取一张屏幕截图，以查看屏幕的当前状态：

r = invoke(
    BEDROCK_AGENTCORE_DP_ENDPOINT, sid,
    {"screenshot": {"format": "PNG"}},
    region=default_region, credentials=creds, browser_id=browser_id
)

# Send the screenshot to a vision model to identify the dialog and locate the Cancel button.
# The vision model integration depends on your agent architecture — see the Bedrock
# InvokeModel API for how to send images to Claude or other models.
# The model returns coordinates, e.g.: {"x": 410, "y": 535}

视觉模型识别出打印对话框，并返回取消按钮的坐标。智能体点击它：

r = invoke(
    BEDROCK_AGENTCORE_DP_ENDPOINT, sid,
    {"mouseClick": {"x": 410, "y": 535, "button": "LEFT"}},
    region=default_region, credentials=creds, browser_id=browser_id
)

print(f"Click status: {r.status_code}, action: {r.json()['result']}")

智能体再截取一张屏幕截图，以确认对话框已被关闭，然后工作流继续。

停止会话并清理

工作流完成之后，停止会话并清理资源：

stop_session(BEDROCK_AGENTCORE_DP_ENDPOINT, sid, browser_id, region=default_region, credentials=creds)

要删除浏览器资源和 IAM 角色：

browser_boto3.delete_browser(browserId=browser_id)
print(f"Browser {browser_id} deleted")

from helpers.utils import delete_agentcore_execution_role, SAMPLE_ROLE_NAME
delete_agentcore_execution_role(SAMPLE_ROLE_NAME)

这些步骤——行动、观察、决定——构成“操作—屏幕截图—反应”模式的核心。配套笔记本使用一次真实的浏览器会话，走查八种受支持的操作，包括鼠标拖拽、滚动、键盘输入和快捷键组合。

结论

当我们推出 Amazon Bedrock AgentCore Browser 时，它为 AI 智能体提供了一个全托管的、基于云的浏览器环境，用以与网站交互。它通过 Playwright 和 CDP 浏览页面、提取内容，并大规模自动化工作流。操作系统级操作把这一能力从网页层延伸到屏幕上可见的用户界面元素。原生对话框、安全提示、键盘快捷键和浏览器边框不再是阻碍。智能体现在可以在同一次会话中观察完整的操作系统桌面、对它推理，并采取行动。

与 AgentCore Browser 已有的能力相结合，例如视觉理解，以及与 Playwright 和 Amazon Nova Act 的框架集成，操作系统级操作补上了浏览器自动化覆盖范围中的最后一处缺口。

要开始构建：

• 按照 Amazon Bedrock AgentCore 开发者指南操作
• 试用配套笔记本，做一次动手走查
• 关于浏览器自动化的更广背景，见 Amazon Bedrock AgentCore Browser 文档

PRIMARY_SOURCE: https://aws.amazon.com/blogs/machine-learning/introducing-os-level-actions-in-amazon-bedrock-agentcore-browser