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

# AgentBrowser 類別

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

需要可靠、確定性的瀏覽器自動化時，請使用 `AgentBrowser`。若要使用自然語言進行 AI 驅動的互動，請參閱 [`StagehandBrowser`](https://mastra.zisheng.pro/zh-TW/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 集合。也可設定 maxDurationMs、maxWidth 與 maxHeight，作為每次錄製的預設值。

**excludeTools** (`BrowserToolName[]`): 要從瀏覽器 Tool 集合排除的 Tool 名稱。可用於停用模型不支援的特定能力，例如 vision。

## Tool

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

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

### 核心 Tool

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

### 擴充 Tool

| Tool               | 說明                                 |
| ------------------ | ---------------------------------- |
| `browser_hover`    | 將游標移至 element 上方                   |
| `browser_back`     | 回到瀏覽器上一頁                           |
| `browser_dialog`   | 處理瀏覽器 dialog（alert、confirm、prompt） |
| `browser_wait`     | 等待 element state 改變                |
| `browser_tabs`     | 管理瀏覽器分頁（列出、新增、切換、關閉）               |
| `browser_drag`     | 拖放 element                         |
| `browser_evaluate` | 在頁面中執行 JavaScript（例外處理機制）          |

若要排除特定 Tool，請將 `excludeTools` 傳給 constructor：

```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` 等 element ref，供其他 Tool 使用。

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

| 參數                | 型別        | 說明                 |
| ----------------- | --------- | ------------------ |
| `interactiveOnly` | `boolean` | 只包含互動式 element（選填） |
| `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 點擊 element。

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

| 參數           | 型別                              | 說明                          |
| ------------ | ------------------------------- | --------------------------- |
| `ref`        | `string`                        | snapshot 中的 element ref（必填） |
| `button`     | `"left" \| "right" \| "middle"` | 滑鼠按鈕（選填）                    |
| `clickCount` | `number`                        | 啟用次數；2 表示按兩下（選填）            |
| `modifiers`  | `string[]`                      | modifier key（選填）            |

### `browser_type`

在輸入 element 中輸入文字。

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

| 參數      | 型別        | 說明                          |
| ------- | --------- | --------------------------- |
| `ref`   | `string`  | snapshot 中的 element 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`

捲動頁面或特定 element。

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

| 參數          | 型別                                    | 說明                       |
| ----------- | ------------------------------------- | ------------------------ |
| `direction` | `"up" \| "down" \| "left" \| "right"` | 捲動方向（必填）                 |
| `amount`    | `number`                              | 捲動的像素數，預設 300（選填）        |
| `ref`       | `string`                              | 要捲動的 element；省略時捲動頁面（選填） |

### `browser_hover`

將游標移至 element 上方，以觸發 hover 效果。

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

### `browser_back`

回到瀏覽器上一頁。

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

```

### `browser_dialog`

處理瀏覽器 dialog（alert、confirm、prompt）。點擊會觸發 dialog 的 element，並加以處理。

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

| 參數           | 型別                      | 說明                      |
| ------------ | ----------------------- | ----------------------- |
| `triggerRef` | `string`                | 觸發 dialog 的 element（必填） |
| `action`     | `"accept" \| "dismiss"` | dialog 的處理方式（必填）        |
| `text`       | `string`                | prompt dialog 的文字（選填）   |

### `browser_wait`

等待 element 進入特定 state。

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

| 參數        | 型別                                                  | 說明                   |
| --------- | --------------------------------------------------- | -------------------- |
| `ref`     | `string`                                            | 要等待的 element ref（選填） |
| `state`   | `"visible" \| "hidden" \| "attached" \| "detached"` | 要等待的 state（選填）       |
| `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`

將 element 拖曳至目標位置。

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

| 參數          | 型別       | 說明               |
| ----------- | -------- | ---------------- |
| `sourceRef` | `string` | 要拖曳的 element（必填） |
| `targetRef` | `string` | 放置目標 element（必填） |

### `browser_evaluate`

在頁面 context 中執行 JavaScript。其他 Tool 無法涵蓋使用情境時，可作為例外處理機制。

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

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

### `browser_screenshot`

將目前頁面擷取為 PNG 螢幕截圖（預設為 viewport；設定 `fullPage: true` 可擷取完整頁面）。傳回的圖片內容可由具備 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 會傳回含有 `@e1`、`@e2` 等 element ref 的 accessibility tree。這些 ref 是供其他 Tool 使用的穩定識別碼：

1. 呼叫 `browser_snapshot` 查看頁面結構
2. 找出要互動的 element
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-TW/reference/browser/mastra-browser)：基底類別參考文件
- [StagehandBrowser](https://mastra.zisheng.pro/zh-TW/reference/browser/stagehand-browser)：AI 驅動的替代方案
- [Browser 概觀](https://mastra.zisheng.pro/zh-TW/docs/browser/overview)：概念指南
- [agent-browser 指南](https://mastra.zisheng.pro/zh-TW/docs/browser/agent-browser)：使用指南