> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt

# AgentBrowser 类

`AgentBrowser` 类使用 [agent-browser](https://github.com/vercel-labs/agent-browser) 库提供确定性浏览器自动化。它使用无障碍树快照和元素 ref（例如 `@e5`）实现精确、可复现的交互。

需要可靠的确定性浏览器自动化时，请使用 `AgentBrowser`。如需使用自然语言的 AI 驱动交互，请参阅 [`StagehandBrowser`](https://mastra.zisheng.pro/reference/browser/stagehand-browser)。

## 用法示例

```typescript
import { Agent } from '@mastra/core/agent'
import { AgentBrowser } from '@mastra/agent-browser'

const browser = new AgentBrowser({
  headless: true,
  viewport: { width: 1280, height: 720 },
  scope: 'thread',
})

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  instructions: `You can browse the web. Use browser_snapshot to see the page structure,
then interact with elements using their refs (e.g., @e5).`,
  model: 'openai/gpt-5.6-sol',
  browser,
})
```

## 构造函数参数

**headless** (`boolean`): 是否以无头模式（无可见 UI）运行浏览器。 (Default: `true`)

**viewport** (`{ width: number; height: number } | 'window'`): 浏览器视口尺寸；也可设为 'window'，以匹配真实浏览器窗口，而不使用固定尺寸。 (Default: `{ width: 1280, height: 720 }`)

**timeout** (`number`): 浏览器操作的默认超时时间（毫秒）。 (Default: `30000`)

**cdpUrl** (`string | (() => string | Promise<string>)`): 用于连接现有浏览器的 CDP WebSocket URL。适用于云浏览器 Provider。

**scope** (`'shared' | 'thread'`): 浏览器实例作用域。'shared' 让所有线程共享一个浏览器。'thread' 为每个线程提供独立浏览器。 (Default: `'thread' (or 'shared' when cdpUrl is provided)`)

**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): 浏览器准备就绪后调用的回调。

**onClose** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): 浏览器关闭前调用的回调。

**screencast** (`ScreencastOptions`): 将浏览器帧流式传输到 Studio 的配置。

**recording** (`BrowserRecordingOptions`): 用于添加浏览器录制工具的 Alpha 选项。提供 outputDir 可将 browser\_record 和 browser\_record\_caption 添加到工具集。还可以设置 maxDurationMs、maxWidth 和 maxHeight，作为每次录制的默认值。

**excludeTools** (`BrowserToolName[]`): 要从浏览器工具集中排除的工具名称。对于不支持某些能力（例如视觉）的模型，可用此选项禁用特定工具。

## 工具

`AgentBrowser` 提供 16 个用于浏览器自动化的确定性工具。所有与元素交互的工具都使用无障碍树快照中的 ref。

配置 `recording` 后，`AgentBrowser` 还会添加 Alpha 版 `browser_record` 和 `browser_record_caption` 工具。请参阅[浏览器录制（Alpha）](https://mastra.zisheng.pro/docs/browser/recording)。

### 核心工具

| 工具                   | 描述                                             |
| -------------------- | ---------------------------------------------- |
| `browser_goto`       | 导航到 URL                                        |
| `browser_snapshot`   | 获取包含元素 ref 的无障碍树快照                             |
| `browser_click`      | 按 ref 点击元素                                     |
| `browser_type`       | 向元素中输入文本                                       |
| `browser_press`      | 按下键盘按键                                         |
| `browser_select`     | 从下拉菜单中选择选项                                     |
| `browser_scroll`     | 滚动页面或元素                                        |
| `browser_screenshot` | 截取 PNG 屏幕截图（默认为视口；设置 `fullPage: true` 可截取完整页面） |
| `browser_close`      | 关闭浏览器                                          |

### 扩展工具

| 工具                 | 描述                             |
| ------------------ | ------------------------------ |
| `browser_hover`    | 将鼠标悬停在元素上                      |
| `browser_back`     | 在浏览器历史记录中后退                    |
| `browser_dialog`   | 处理浏览器对话框（alert、confirm、prompt） |
| `browser_wait`     | 等待元素状态变化                       |
| `browser_tabs`     | 管理浏览器标签页（列出、新建、切换、关闭）          |
| `browser_drag`     | 拖放元素                           |
| `browser_evaluate` | 在页面中执行 JavaScript（逃生舱）         |

要排除特定工具，请在构造函数中传入 `excludeTools`：

```typescript
const browser = new AgentBrowser({
  excludeTools: ['browser_screenshot'],
})
```

## 工具参考

### `browser_goto`

导航到 URL。

```text
// Tool input
{
  "url": "https://example.com",
  "waitUntil": "domcontentloaded",
  "timeout": 30000
}
```

| 参数          | 类型                                              | 描述            |
| ----------- | ----------------------------------------------- | ------------- |
| `url`       | `string`                                        | 要打开的 URL      |
| `waitUntil` | `"load" \| "domcontentloaded" \| "networkidle"` | 何时将导航视为完成（可选） |
| `timeout`   | `number`                                        | 导航超时时间（毫秒，可选） |

### `browser_snapshot`

获取页面的无障碍树快照。返回 `@e5` 之类的元素 ref，供其他工具使用。

```text
// Tool input
{
  "interactiveOnly": true,
  "maxDepth": 10
}
```

| 参数                | 类型        | 描述             |
| ----------------- | --------- | -------------- |
| `interactiveOnly` | `boolean` | 是否仅包含交互式元素（可选） |
| `maxDepth`        | `number`  | 最大树深度（可选）      |

**示例输出：**

```text
[document] Example Page
  [banner]
    [link @e1] Home
    [link @e2] About
  [main]
    [heading @e3] Welcome
    [textbox @e4] Search...
    [button @e5] Submit
```

### `browser_click`

使用快照中的 ref 点击元素。

```text
{
  "ref": "@e5",
  "button": "left",
  "clickCount": 1,
  "modifiers": ["Control", "Shift"]
}
```

| 参数           | 类型                              | 描述              |
| ------------ | ------------------------------- | --------------- |
| `ref`        | `string`                        | 快照中的元素 ref（必需）  |
| `button`     | `"left" \| "right" \| "middle"` | 鼠标按键（可选）        |
| `clickCount` | `number`                        | 激活次数；双击时为 2（可选） |
| `modifiers`  | `string[]`                      | 修饰键（可选）         |

### `browser_type`

向输入元素中输入文本。

```text
// Tool input
{
  "ref": "@e4",
  "text": "search query",
  "clear": true,
  "delay": 50
}
```

| 参数      | 类型        | 描述             |
| ------- | --------- | -------------- |
| `ref`   | `string`  | 快照中的元素 ref（必需） |
| `text`  | `string`  | 要输入的文本（必需）     |
| `clear` | `boolean` | 是否先清除现有内容（可选）  |
| `delay` | `number`  | 按键之间的延迟（毫秒，可选） |

### `browser_press`

按下键盘按键。

```text
// Tool input
{
  "key": "Enter",
  "modifiers": ["Control"]
}

// Key combinations
{ "key": "Control+a" }
{ "key": "Control+c" }
```

| 参数          | 类型         | 描述                                              |
| ----------- | ---------- | ----------------------------------------------- |
| `key`       | `string`   | 按键名称（例如 "Enter"、"Tab"、"Escape"、"Control+a"）（必需） |
| `modifiers` | `string[]` | 修饰键（可选）                                         |

### `browser_select`

从下拉菜单中选择选项。请提供 `value`、`label` 或 `index` 之一。

```text
// Tool input - by value
{
  "ref": "@e10",
  "value": "option-value"
}

// Tool input - by label
{
  "ref": "@e10",
  "label": "Option Text"
}

// Tool input - by index
{
  "ref": "@e10",
  "index": 0
}
```

### `browser_scroll`

滚动页面或特定元素。

```text
// Tool input
{
  "direction": "down",
  "amount": 300,
  "ref": "@e15"
}
```

| 参数          | 类型                                    | 描述                 |
| ----------- | ------------------------------------- | ------------------ |
| `direction` | `"up" \| "down" \| "left" \| "right"` | 滚动方向（必需）           |
| `amount`    | `number`                              | 滚动像素数，默认为 300（可选）  |
| `ref`       | `string`                              | 要滚动的元素；省略时滚动页面（可选） |

### `browser_hover`

将鼠标悬停在元素上以触发悬停效果。

```text
// Tool input
{
  "ref": "@e7"
}
```

### `browser_back`

在浏览器历史记录中后退。

```text
// Tool input (no parameters required)

```

### `browser_dialog`

处理浏览器对话框（alert、confirm、prompt）。点击触发对话框的元素并进行处理。

```text
// Tool input
{
  "triggerRef": "@e5",
  "action": "accept",
  "text": "response"
}
```

| 参数           | 类型                      | 描述                |
| ------------ | ----------------------- | ----------------- |
| `triggerRef` | `string`                | 触发对话框的元素（必需）      |
| `action`     | `"accept" \| "dismiss"` | 处理对话框的方式（必需）      |
| `text`       | `string`                | prompt 对话框的文本（可选） |

### `browser_wait`

等待元素达到特定状态。

```text
// Tool input
{
  "ref": "@e20",
  "state": "visible",
  "timeout": 30000
}
```

| 参数        | 类型                                                  | 描述             |
| --------- | --------------------------------------------------- | -------------- |
| `ref`     | `string`                                            | 要等待的元素 ref（可选） |
| `state`   | `"visible" \| "hidden" \| "attached" \| "detached"` | 要等待的状态（可选）     |
| `timeout` | `number`                                            | 最大等待时间（毫秒，可选）  |

### `browser_tabs`

管理浏览器标签页。

```text
// List all tabs
{ "action": "list" }

// Open new tab
{ "action": "new", "url": "https://example.com" }

// Switch to tab by index
{ "action": "switch", "index": 0 }

// Close tab by index
{ "action": "close", "index": 1 }
```

### `browser_drag`

将元素拖到目标位置。

```text
// Tool input
{
  "sourceRef": "@e10",
  "targetRef": "@e20"
}
```

| 参数          | 类型       | 描述         |
| ----------- | -------- | ---------- |
| `sourceRef` | `string` | 要拖动的元素（必需） |
| `targetRef` | `string` | 放置目标元素（必需） |

### `browser_evaluate`

在页面上下文中执行 JavaScript。当其他工具无法覆盖你的使用场景时，可将其作为逃生舱。

```text
// Tool input
{
  "script": "document.title",
  "returnValue": true
}
```

| 参数            | 类型        | 描述                  |
| ------------- | --------- | ------------------- |
| `script`      | `string`  | 要执行的 JavaScript（必需） |
| `returnValue` | `boolean` | 是否返回结果（可选）          |

### `browser_screenshot`

将当前页面截取为 PNG 屏幕截图（默认为视口。设置 `fullPage: true` 可截取完整页面）。返回支持视觉能力的模型可直接解读的图像内容。只需要文本或结构化数据时，请使用 `browser_snapshot`。

```text
// Viewport only (default)

// Full scrollable page
{ "fullPage": true }
```

| 参数         | 类型        | 描述                                  |
| ---------- | --------- | ----------------------------------- |
| `fullPage` | `boolean` | 是否截取完整的可滚动页面，而不是仅截取视口（可选，默认值：false） |

### `browser_close`

关闭浏览器并清理资源。

```text
// Tool input (no parameters required)

```

## ref 的工作原理

`browser_snapshot` 工具返回一个无障碍树，其中包含 `@e1`、`@e2` 等元素 ref。这些 ref 是供其他工具使用的稳定标识符：

1. 调用 `browser_snapshot` 查看页面结构
2. 找到要交互的元素
3. 将其 ref 与 `browser_type` 或 `browser_scroll` 等交互工具配合使用。

```text
// 1. Get snapshot
// Returns: [textbox @e4] Search... [link @e5] Home

// 2. Type in the search box
{ "tool": "browser_type", "input": { "ref": "@e4", "text": "mastra" } }

// 3. Navigate to home
{ "tool": "browser_goto", "input": { "url": "https://example.com" } }
```

## 相关内容

- [MastraBrowser](https://mastra.zisheng.pro/reference/browser/mastra-browser)：基类参考
- [StagehandBrowser](https://mastra.zisheng.pro/reference/browser/stagehand-browser)：AI 驱动的替代方案
- [Browser 概述](https://mastra.zisheng.pro/docs/browser/overview)：概念指南
- [agent-browser 指南](https://mastra.zisheng.pro/docs/browser/agent-browser)：用法指南