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

# Browser 概觀

Browser 支援讓 Agent 能夠瀏覽網站、與頁面元素互動、填寫表單及擷取資料。Mastra 透過封裝瀏覽器自動化程式庫的 SDK Provider，以及供 Agent 透過命令列 Tool 操作瀏覽器的 CLI Provider，提供瀏覽器功能。

Mastra 支援三種 SDK Provider 和一種 CLI Provider：

- [**AgentBrowser**](https://mastra.zisheng.pro/zh-TW/docs/browser/agent-browser)：以 Playwright 為基礎，並以無障礙功能為優先來定位元素的 Provider。最適合一般網頁自動化和資料擷取。
- [**Stagehand**](https://mastra.zisheng.pro/zh-TW/docs/browser/stagehand)：具備 AI 元素偵測功能的 Browserbase Provider。最適合受益於自然語言選擇器的複雜互動。
- [**FirecrawlBrowser**](https://mastra.zisheng.pro/zh-TW/docs/browser/firecrawl)：Firecrawl Browser Sandbox Provider，可對託管的瀏覽器工作階段執行 AgentBrowser Tool。最適合在不管理本機瀏覽器基礎架構的情況下，於託管瀏覽器工作階段執行自動化。
- [**BrowserViewer**](https://mastra.zisheng.pro/zh-TW/docs/browser/browser-viewer)：CLI Provider，會啟動 Chrome，並將 CDP URL 注入 agent-browser、browser-use 和 browse 等 CLI Tool。最適合透過 shell 命令操作瀏覽器的 Workspace Agent。
- [**瀏覽器錄製（alpha）**](https://mastra.zisheng.pro/zh-TW/docs/browser/recording)：可選擇啟用的 Tool 層，能將瀏覽器工作階段儲存為 Motion-JPEG AVI 影片，並可加入字幕。

## 適合使用 Browser 的時機

當 Agent 需要執行以下操作時，請使用 Browser：

- 瀏覽網站並與頁面元素互動
- 填寫表單並提交資料
- 從網頁擷取結構化資料
- 自動執行多步驟網頁工作流程
- 執行需要真實瀏覽器的操作（JavaScript 轉譯、驗證流程）

## 運作方式

將 Browser 指派給 Agent 後，Mastra 會把 Provider 的 Tool 加入 Agent 的 Tool 集合。Agent 會使用這些 Tool 控制瀏覽器，包括前往 URL、選取元素、輸入文字及讀取頁面內容。

每個 Provider 都提供針對其作法最佳化的不同 Tool 集合。

## 快速開始

安裝所選的 Provider；此範例使用 AgentBrowser Provider。

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

建立新的瀏覽器執行個體：

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

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

將 Browser 指派給 Agent：

```typescript
import { Agent } from '@mastra/core/agent'
import { browser } from '../browsers'

export const webAgent = new Agent({
  id: 'web-agent',
  name: 'Web Agent',
  description: 'A web automation assistant that can navigate websites and complete tasks.',
  model: 'openai/gpt-5.6-sol',
  browser,
  instructions:
    'You are a web automation assistant. Use browser tools to navigate websites and complete tasks.',
})
```

Agent 會自動取得 Provider 提供的所有瀏覽器 Tool。

## 雲端 Provider

所有 SDK Provider 都支援連線至雲端瀏覽器服務，不必啟動本機瀏覽器。

### Firecrawl Browser Sandbox（FirecrawlBrowser 原生整合）

FirecrawlBrowser 透過 Firecrawl API 佈建託管的工作階段：

```typescript
import { FirecrawlBrowser } from '@mastra/browser-firecrawl'

const browser = new FirecrawlBrowser({
  apiKey: process.env.FIRECRAWL_API_KEY,
})
```

### Browserbase（Stagehand 原生整合）

Stagehand 原生整合 Browserbase：

```typescript
import { StagehandBrowser } from '@mastra/stagehand'

const browser = new StagehandBrowser({
  env: 'BROWSERBASE',
  apiKey: process.env.BROWSERBASE_API_KEY,
  projectId: process.env.BROWSERBASE_PROJECT_ID,
})
```

### CDP URL（任何 Provider）

連線至任何公開 Chrome DevTools Protocol（CDP）端點的瀏覽器：

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

const browser = new AgentBrowser({
  cdpUrl: process.env.BROWSER_CDP_URL,
  headless: true,
})
```

這適用於任何[相容 CDP](https://chromedevtools.github.io/devtools-protocol/) 的瀏覽器服務。

## 螢幕串流

Browser Provider 會將瀏覽器的即時影像串流傳送至 Mastra Studio UI，讓你可以即時觀看 Agent 與頁面互動。

螢幕串流需要 WebSocket 支援。請在專案中安裝以下套件：

**npm**:

```bash
npm install ws @hono/node-ws
```

**pnpm**:

```bash
pnpm add ws @hono/node-ws
```

**Yarn**:

```bash
yarn add ws @hono/node-ws
```

**Bun**:

```bash
bun add ws @hono/node-ws
```

> **備註:** 這些套件預設不會納入，因為它們與 Cloudflare Workers 等無伺服器環境不相容。若未安裝，螢幕串流會停用，但其他所有瀏覽器功能仍可正常運作。

螢幕串流預設為啟用，並可進行設定：

```typescript
const browser = new AgentBrowser({
  screencast: {
    enabled: true,
    format: 'jpeg',
    quality: 80,
    maxWidth: 1280,
    maxHeight: 720,
  },
})
```

## 後續步驟

- [AgentBrowser](https://mastra.zisheng.pro/zh-TW/docs/browser/agent-browser)
- [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)
- [BrowserViewer](https://mastra.zisheng.pro/zh-TW/docs/browser/browser-viewer)
- [MastraBrowser 參考文件](https://mastra.zisheng.pro/zh-TW/reference/browser/mastra-browser)
- 📹 [Mastra Browser 功能工作坊](https://www.youtube.com/watch?v=E9KFsZEnQO8\&t=5s)