本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

# 浏览器操作系统操作
<a name="browser-invoke"></a>

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

## 概述
<a name="browser-invoke-overview"></a>

亚马逊 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：采用行动型调度的单一统一行动。您发送的请求仅包含一个操作，并收到相应的结果。

## 支持的操作
<a name="browser-invoke-supported-actions"></a>

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

### 鼠标动作
<a name="browser-invoke-mouse-actions"></a>

对于所有鼠标操作，坐标值 (`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`滚动。 | 

### 键盘动作
<a name="browser-invoke-keyboard-actions"></a>


| 处理建议 | 必填字段 | 可选字段 | 说明 | 
| --- | --- | --- | --- | 
|  `keyType`  |  `text`（字符串） | — | 键入文本字符串。最大长度：10,000 个字符。 | 
|  `keyPress`  |  `key`（字符串） |  `presses`（整数） | 按下按键 N 次。`presses`: 1—100。默认值为 1。 | 
|  `keyShortcut`  |  `keys` (KeyList) | — | 按下组合键（例如，`["ctrl", "s"]`）。最多 5 个密钥。 | 

### 屏幕截图操作
<a name="browser-invoke-screenshot-action"></a>


| 处理建议 | 必填字段 | 可选字段 | 说明 | 
| --- | --- | --- | --- | 
|  `screenshot`  | — |  `format` (ScreenshotFormat) | 捕获完整的操作系统桌面（不仅仅是浏览器视口）。格式：仅限 PNG。 | 

## 注意事项
<a name="browser-invoke-considerations"></a>
+  **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`。

## 请求和响应格式
<a name="browser-invoke-request-response"></a>

### 请求
<a name="browser-invoke-request"></a>

```
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
        }
    }
}
```

### 响应
<a name="browser-invoke-response"></a>

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

成功时：

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

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

## 示例
<a name="browser-invoke-examples"></a>

以下示例说明如何使用 Amazon CLI、Python Amazon 开发工具包 (Boto3) 和 API 调用浏览器操作。

**Example**  

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

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")
   ```

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