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

# AgentBrowser

`@mastra/agent-browser` 套件使用 Playwright 提供瀏覽器自動化，並以無障礙功能為優先來定位元素。系統會利用頁面無障礙樹中的 ref 識別元素，讓互動在不同頁面版面中都能可靠運作。

## 適合使用 AgentBrowser 的時機

在需要以下功能時使用 AgentBrowser：

- 透過無障礙 ref 可靠地定位元素
- 精細控制瀏覽器操作
- 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-TW/reference/browser/agent-browser) 選項連線至遠端瀏覽器，Chromium 則由遠端瀏覽器提供。

## 螢幕截圖

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

需要以視覺方式檢查頁面時（例如評估圖片、版面或色彩），請使用螢幕截圖。若要取得文字或結構化資料，請改用 `browser_snapshot`。

若模型不支援視覺功能，可使用 `excludeTools` 停用螢幕截圖 Tool：

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

## 元素 ref

AgentBrowser 使用無障礙樹 ref 識別元素。當 Agent 呼叫 `browser_snapshot` 時，會收到頁面的文字表示，其中包含 `@e1`、`@e2` 等 ref。接著，Agent 會將這些 ref 搭配其他 Tool 使用，以便與元素互動。

## 錄製

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-TW/docs/browser/recording)。所有設定選項和 Tool 詳情請參閱 [AgentBrowser 參考文件](https://mastra.zisheng.pro/zh-TW/reference/browser/agent-browser)。

## 相關資源

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