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

# Firecrawl

`@mastra/browser-firecrawl` 依賴套件使用 [Firecrawl Browser Sandbox](https://docs.firecrawl.dev/features/browser) 提供瀏覽器自動化功能。它透過 Firecrawl API 建立遠端瀏覽器工作階段，並使用與 [AgentBrowser](https://mastra.zisheng.pro/zh-HK/docs/browser/agent-browser) 相同、結果可預測且以無障礙為先的 Tool 來操控瀏覽器。

`FirecrawlBrowser` 擴充自 `AgentBrowser`，因此 Agent 可使用相同的 Tool 組合（`browser_goto`、`browser_snapshot`、`browser_click` 等），而瀏覽器本身則在 Firecrawl 的託管基礎設施上執行，毋須在本機安裝 Chromium。

## 適合使用 Firecrawl 的情況

如有以下需要，可使用 Firecrawl：

- 使用託管瀏覽器工作階段，而毋須管理本機 Chromium 二進制檔案
- 在無法啟動本機瀏覽器的環境中進行瀏覽器自動化
- 為每個對話執行緒隔離 Sandbox，並自動清理工作階段
- 使用具名 Firecrawl 設定檔，在不同工作階段之間保留 Cookie 和登入狀態

## 快速開始

安裝依賴套件：

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

設定 Firecrawl API 金鑰：

```bash
FIRECRAWL_API_KEY=fc-...
```

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

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

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

export const firecrawlAgent = new Agent({
  id: 'firecrawl-agent',
  name: 'Firecrawl 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`,
})
```

如省略 `apiKey`，Provider 會從環境讀取 `FIRECRAWL_API_KEY`。

## 工作階段範圍

`FirecrawlBrowser` 的 `scope` 選項與 `AgentBrowser` 相同：

- `'thread'`（預設）：每個對話執行緒各自使用一個 Firecrawl Sandbox 工作階段。當該執行緒的瀏覽器關閉時，工作階段便會刪除。
- `'shared'`：所有執行緒共用一個 Firecrawl Sandbox 工作階段，並在瀏覽器關閉時將其刪除。

```typescript
const browser = new FirecrawlBrowser({
  scope: 'shared',
})
```

## 工作階段選項

在 `firecrawl` 鍵下傳入 Firecrawl 專用的工作階段選項。這些選項會對應至 Firecrawl `browser()` API：

```typescript
const browser = new FirecrawlBrowser({
  firecrawl: {
    ttl: 600,
    activityTtl: 120,
    profile: {
      name: 'my-profile',
      saveChanges: true,
    },
  },
})
```

- `ttl`：工作階段的最長存續時間（秒）。
- `activityTtl`：Firecrawl 回收工作階段前的閒置逾時時間（秒）。
- `profile`：具名 Firecrawl 設定檔，用於保留 Cookie 和登入狀態。設定 `saveChanges: true`，即可在工作階段結束時儲存設定檔變更。

> **備註:** 巢狀的 `firecrawl.profile` 選項指儲存在 Firecrawl 基礎設施中的設定檔。此選項有別於頂層 `profile` 選項；後者繼承自 `AgentBrowser`，是本機 Playwright 使用者資料目錄的路徑。

## 自行託管 Firecrawl

如要使用自行託管的 Firecrawl API，請設定 `apiUrl`：

```typescript
const browser = new FirecrawlBrowser({
  apiUrl: 'https://firecrawl.internal.example.com',
})
```

## 相關內容

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