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

# 瀏覽器概覽

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

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

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

## 何時使用瀏覽器

當你的 Agent 需要執行以下操作時，便應使用瀏覽器：

- 瀏覽網站並與頁面元素互動
- 填寫表格及提交數據
- 從網頁擷取結構化數據
- 自動執行多步驟網絡 Workflow
- 執行需要真實瀏覽器的操作（JavaScript 渲染、驗證流程）

## 運作方式

當你為 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,
})
```

將瀏覽器指派給 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/) 的瀏覽器服務。

## 畫面串流

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