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

# AgentBrowser class

`AgentBrowser` class 使用 [agent-browser](https://github.com/vercel-labs/agent-browser) library 提供確定性瀏覽器自動化。它運用 accessibility tree snapshot 及元素 ref（例如 `@e5`），實現精準且可重現的互動。

如需要可靠且具確定性的瀏覽器自動化，請使用 `AgentBrowser`。如要透過自然語言進行 AI 互動，請參閱 [`StagehandBrowser`](https://mastra.zisheng.pro/zh-HK/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,
})
```

## Constructor 參數

**headless** (`boolean`): 是否以 headless 模式執行瀏覽器（不顯示 UI）。 (Default: `true`)

**viewport** (`{ width: number; height: number } | 'window'`): 瀏覽器 viewport 尺寸；亦可設為 'window'，以配合實際瀏覽器視窗，而非使用固定尺寸。 (Default: `{ width: 1280, height: 720 }`)

**timeout** (`number`): 瀏覽器操作的預設逾時時間（毫秒）。 (Default: `30000`)

**cdpUrl** (`string | (() => string | Promise<string>)`): 用於連線至現有瀏覽器的 CDP WebSocket URL，適合配合雲端瀏覽器 Provider 使用。

**scope** (`'shared' | 'thread'`): 瀏覽器 instance scope。'shared' 讓所有 thread 共用一個瀏覽器；'thread' 則讓每個 thread 都有自己的瀏覽器。 (Default: `'thread' (or 'shared' when cdpUrl is provided)`)

**onLaunch** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): 瀏覽器準備就緒後呼叫的 callback。

**onClose** (`(args: { browser: MastraBrowser }) => void | Promise<void>`): 關閉瀏覽器前呼叫的 callback。

**screencast** (`ScreencastOptions`): 將瀏覽器 frame 串流至 Studio 的設定。

**recording** (`BrowserRecordingOptions`): 用於加入瀏覽器錄影 Tool 的 Alpha 選項。提供 outputDir，即可將 browser\_record 及 browser\_record\_caption 加入 Tool set。你亦可設定 maxDurationMs、maxWidth 及 maxHeight，作為每次錄影的預設值。

**excludeTools** (`BrowserToolName[]`): 要從瀏覽器 Tool set 排除的 Tool 名稱。如模型不支援 vision 等特定功能，可使用此選項停用相應 Tool。

## Tools

`AgentBrowser` 提供 16 個用於瀏覽器自動化的確定性 Tool。所有與元素互動的 Tool，都會使用 accessibility tree snapshot 中的 ref。

設定 `recording` 後，`AgentBrowser` 亦會加入 Alpha 版 `browser_record` 及 `browser_record_caption` Tool。請參閱[瀏覽器錄影（Alpha）](https://mastra.zisheng.pro/zh-HK/docs/browser/recording)。

### 核心 Tool

| Tool                 | 說明                                                        |
| -------------------- | --------------------------------------------------------- |
| `browser_goto`       | 前往 URL                                                    |
| `browser_snapshot`   | 取得包含元素 ref 的 accessibility tree snapshot                  |
| `browser_click`      | 按 ref 點擊元素                                                |
| `browser_type`       | 在元素中輸入文字                                                  |
| `browser_press`      | 按下鍵盤按鍵                                                    |
| `browser_select`     | 從下拉式選單選取選項                                                |
| `browser_scroll`     | 捲動頁面或元素                                                   |
| `browser_screenshot` | 擷取 PNG 螢幕截圖（預設只擷取 viewport；如要擷取完整頁面，請設為 `fullPage: true`） |
| `browser_close`      | 關閉瀏覽器                                                     |

### 擴充 Tool

| Tool               | 說明                                 |
| ------------------ | ---------------------------------- |
| `browser_hover`    | 將游標停留在元素上                          |
| `browser_back`     | 返回瀏覽器上一頁                           |
| `browser_dialog`   | 處理瀏覽器 dialog（alert、confirm、prompt） |
| `browser_wait`     | 等待元素狀態變更                           |
| `browser_tabs`     | 管理瀏覽器分頁（列出、建立、切換、關閉）               |
| `browser_drag`     | 拖放元素                               |
| `browser_evaluate` | 在頁面中執行 JavaScript（應急方法）            |

如要排除特定 Tool，請在 constructor 傳入 `excludeTools`：

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

## Tool 參考

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

取得頁面的 accessibility tree snapshot。傳回 `@e5` 等元素 ref，供其他 Tool 使用。

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

| 參數                | 類型        | 說明             |
| ----------------- | --------- | -------------- |
| `interactiveOnly` | `boolean` | 只包括可互動元素（可選）   |
| `maxDepth`        | `number`  | Tree 的最大深度（可選） |

**輸出範例：**

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

### `browser_click`

使用 snapshot 中的 ref 點擊元素。

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

| 參數           | 類型                              | 說明                    |
| ------------ | ------------------------------- | --------------------- |
| `ref`        | `string`                        | Snapshot 中的元素 ref（必填） |
| `button`     | `"left" \| "right" \| "middle"` | 滑鼠按鈕（可選）              |
| `clickCount` | `number`                        | 啟動次數；設為 2 即代表連按兩下（可選） |
| `modifiers`  | `string[]`                      | Modifier key（可選）      |

### `browser_type`

在 input 元素中輸入文字。

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

| 參數      | 類型        | 說明                    |
| ------- | --------- | --------------------- |
| `ref`   | `string`  | Snapshot 中的元素 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[]` | Modifier key（可選）                                |

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

將游標停留在元素上，以觸發 hover 效果。

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

### `browser_back`

在瀏覽器歷史記錄中返回上一頁。

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

```

### `browser_dialog`

處理瀏覽器 dialog（alert、confirm、prompt）。點擊會觸發 dialog 的元素，然後處理該 dialog。

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

| 參數           | 類型                      | 說明                       |
| ------------ | ----------------------- | ------------------------ |
| `triggerRef` | `string`                | 會觸發 dialog 的元素（必填）       |
| `action`     | `"accept" \| "dismiss"` | 處理 dialog 的方式（必填）        |
| `text`       | `string`                | 用於 prompt dialog 的文字（可選） |

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

在頁面 context 中執行 JavaScript。當其他 Tool 未能涵蓋你的使用情境時，可將此方法作為應急方案。

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

| 參數            | 類型        | 說明                  |
| ------------- | --------- | ------------------- |
| `script`      | `string`  | 要執行的 JavaScript（必填） |
| `returnValue` | `boolean` | 是否傳回結果（可選）          |

### `browser_screenshot`

將目前頁面擷取成 PNG 螢幕截圖（預設只擷取 viewport；設定 `fullPage: true` 可擷取完整頁面）。此 Tool 會傳回具 vision 功能的模型可直接理解的影像內容。如果只需要文字或結構化資料，請使用 `browser_snapshot`。

```text
// Viewport only (default)

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

| 參數         | 類型        | 說明                                    |
| ---------- | --------- | ------------------------------------- |
| `fullPage` | `boolean` | 擷取整個可捲動頁面，而非只擷取 viewport（可選，預設：false） |

### `browser_close`

關閉瀏覽器並清理資源。

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

```

## Ref 的運作方式

`browser_snapshot` Tool 會傳回 accessibility tree，其中包含 `@e1`、`@e2` 等元素 ref。這些 ref 是可配合其他 Tool 使用的穩定識別碼：

1. 呼叫 `browser_snapshot` 查看頁面結構
2. 找出你想互動的元素
3. 將其 ref 配合 `browser_type` 或 `browser_scroll` 等互動 Tool 使用。

```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/zh-HK/reference/browser/mastra-browser)：基底 class 參考
- [StagehandBrowser](https://mastra.zisheng.pro/zh-HK/reference/browser/stagehand-browser)：AI 替代方案
- [瀏覽器概覽](https://mastra.zisheng.pro/zh-HK/docs/browser/overview)：概念指南
- [agent-browser 指南](https://mastra.zisheng.pro/zh-HK/docs/browser/agent-browser)：使用指南