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

# AgentBrowser

`@mastra/agent-browser` 依賴套件使用 Playwright 提供瀏覽器自動化功能，並以無障礙優先的方式定位元素。元素透過頁面無障礙樹中的 refs 識別，令互動在不同頁面佈局下仍然可靠。

## 何時使用 AgentBrowser

當你需要以下功能時，請使用 AgentBrowser：

- 透過無障礙 refs 可靠地定位元素
- 精細控制瀏覽器操作
- Playwright 可靠的自動化功能
- 支援鍵盤快捷鍵及複雜互動

## 快速開始

安裝依賴套件：

**npm**:

```bash
npm install @mastra/agent-browser
```

**pnpm**:

```bash
pnpm add @mastra/agent-browser
```

**Yarn**:

```bash
yarn add @mastra/agent-browser
```

**Bun**:

```bash
bun add @mastra/agent-browser
```

建立瀏覽器實例，並將其指派給 Agent：

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

const browser = new AgentBrowser({
  headless: false,
})

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions: `You are a web automation assistant.

When interacting with pages:
1. Use browser_snapshot to get the current page state and element refs
2. Use the refs (like @e1, @e2) to target elements for clicks and typing
3. After actions, take another snapshot to verify the result`,
})
```

> **備註:** 在本機啟動時（預設方式），AgentBrowser 需要透過 Playwright 安裝 Chromium 二進制檔案。安裝 `@mastra/agent-browser` 時，系統通常會自動下載該檔案。如果啟動瀏覽器時出現 `"browser executable is missing"` 錯誤，請執行 `npx playwright install chromium`。如果你使用 [`cdpUrl`](https://mastra.zisheng.pro/zh-HK/reference/browser/agent-browser) 選項連接遙距瀏覽器，Chromium 將由該遙距瀏覽器提供。

## 螢幕截圖

當 Agent 使用 `browser_screenshot` Tool 時，它會擷取目前頁面的 PNG 圖像，並以支援視覺功能的模型可直接解讀的圖像內容形式傳回。

需要以視覺方式檢視頁面（例如評估圖像、佈局或顏色）時，請使用螢幕截圖。若要處理文字或結構化數據，則應使用 `browser_snapshot`。

如要為不支援視覺功能的模型停用螢幕截圖 Tool，請使用 `excludeTools`：

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

## 元素 refs

AgentBrowser 使用無障礙樹 refs 識別元素。當 Agent 呼叫 `browser_snapshot` 時，它會收到頁面的文字表示，其中包含 `@e1`、`@e2` 等 refs。然後，Agent 會配合其他 Tool 使用這些 refs 與元素互動。

## 錄製

AgentBrowser 可選擇啟用 alpha 階段的瀏覽器錄製 Tool：

```typescript
const browser = new AgentBrowser({
  headless: false,
  recording: {
    outputDir: './browser-recordings',
  },
})
```

這會將 `browser_record` 及 `browser_record_caption` 加入 Agent 的 Tool 組合。詳情請參閱[瀏覽器錄製（alpha）](https://mastra.zisheng.pro/zh-HK/docs/browser/recording)。如要了解所有配置選項及 Tool 詳情，請參閱 [AgentBrowser 參考資料](https://mastra.zisheng.pro/zh-HK/reference/browser/agent-browser)。

## 相關內容

- [瀏覽器概覽](https://mastra.zisheng.pro/zh-HK/docs/browser/overview)
- [Stagehand](https://mastra.zisheng.pro/zh-HK/docs/browser/stagehand)
- [Firecrawl](https://mastra.zisheng.pro/zh-HK/docs/browser/firecrawl)
- [瀏覽器錄製（alpha）](https://mastra.zisheng.pro/zh-HK/docs/browser/recording)
- [AgentBrowser 參考資料](https://mastra.zisheng.pro/zh-HK/reference/browser/agent-browser)