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

# FirecrawlBrowser 類別

`FirecrawlBrowser` 類別提供由 [Firecrawl Browser Sandbox](https://docs.firecrawl.dev/features/browser) 支援的瀏覽器自動化功能。它會透過 Firecrawl API 建立遠端瀏覽器工作階段，並使用 Chrome DevTools Protocol (CDP) 連線。

`FirecrawlBrowser` 擴充了 [`AgentBrowser`](https://mastra.zisheng.pro/zh-HK/reference/browser/agent-browser)，並提供相同的確定性 Tool 集。想使用託管瀏覽器工作階段，而非在本機安裝 Chromium 時，請使用它。如需本機自動化，請參閱 [`AgentBrowser`](https://mastra.zisheng.pro/zh-HK/reference/browser/agent-browser)。如需使用自然語言的 AI 互動，請參閱 [`StagehandBrowser`](https://mastra.zisheng.pro/zh-HK/reference/browser/stagehand-browser)。

## 使用範例

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

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

export const browserAgent = new Agent({
  id: 'browser-agent',
  name: 'Browser Agent',
  instructions: `You can browse the web. Use browser_snapshot to see the page structure,
then interact with elements using their refs (e.g., @e5).`,
  model: 'openai/gpt-5.6-sol',
  browser,
})
```

## 建構函數參數

`FirecrawlBrowser` 接受所有 [`AgentBrowser` 建構函數參數](https://mastra.zisheng.pro/zh-HK/reference/browser/agent-browser)，以及以下參數：

**apiKey** (`string`): Firecrawl API 金鑰。未有提供時，會改用 FIRECRAWL\_API\_KEY 環境變數。如兩者均未設定，建構函數便會拋出錯誤。

**apiUrl** (`string`): 自行託管 Firecrawl API 的基礎 URL。

**firecrawl** (`FirecrawlBrowserSessionOptions`): 建立 Sandbox 工作階段時，傳遞至 Firecrawl browser() API 的工作階段選項。

**firecrawl.ttl** (`number`): 工作階段的最長存續時間（秒）。

**firecrawl.activityTtl** (`number`): Sandbox 回收工作階段前的閒置逾時時間（秒）。

**firecrawl.streamWebView** (`boolean`): 設為 true 時，Firecrawl 可串流遠端工作階段的 WebView 畫面。

**firecrawl.profile** (`{ name: string; saveChanges?: boolean }`): 具名的 Firecrawl Sandbox 設定檔。設置 saveChanges: true，可在工作階段結束時保留 Cookie 和登入狀態；單純為設定檔命名並不會儲存變更。這與最上層的 AgentBrowser profile 選項不同，後者是本機 Playwright 使用者資料目錄的路徑。

**firecrawl.integration** (`string`): 供 Firecrawl 分析及路由使用的整合標籤。

**firecrawl.origin** (`string`): Firecrawl 瀏覽器工作階段的來源提示。

## 工作階段生命週期

工作階段的建立方式取決於從 `AgentBrowser` 繼承的 `scope` 選項：

- `'thread'`（預設）：每個對話執行緒都有自己的 Firecrawl Sandbox 工作階段。工作階段會在首次使用時建立，並在該執行緒的瀏覽器工作階段銷毀時刪除。
- `'shared'`：瀏覽器啟動時會建立一個 Firecrawl Sandbox 工作階段，供所有執行緒共用。瀏覽器關閉時，工作階段亦會刪除。

無論是哪種情況，瀏覽器關閉時，`FirecrawlBrowser` 都會刪除遠端 Firecrawl 工作階段；即使建立工作階段或連線期間發生失敗，亦會如此。

## Tool

`FirecrawlBrowser` 提供與 `AgentBrowser` 相同的 Tool 集，包括 `browser_goto`、`browser_snapshot`、`browser_click`、`browser_type` 及 `browser_screenshot`。如需完整清單及 Tool 參數，請參閱 [`AgentBrowser` Tool 參考](https://mastra.zisheng.pro/zh-HK/reference/browser/agent-browser)。

## 相關內容

- [Firecrawl 文檔](https://mastra.zisheng.pro/zh-HK/docs/browser/firecrawl)
- [`AgentBrowser` 參考](https://mastra.zisheng.pro/zh-HK/reference/browser/agent-browser)
- [瀏覽器概覽](https://mastra.zisheng.pro/zh-HK/docs/browser/overview)