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

# FirecrawlBrowser 類別

`FirecrawlBrowser` 類別提供以 [Firecrawl Browser Sandbox](https://docs.firecrawl.dev/features/browser) 為基礎的瀏覽器自動化功能。它會透過 Firecrawl API 佈建遠端瀏覽器 session，並使用 Chrome DevTools Protocol（CDP）連線。

`FirecrawlBrowser` 擴充 [`AgentBrowser`](https://mastra.zisheng.pro/zh-TW/reference/browser/agent-browser)，並公開相同的確定性 Tool 集合。需要託管的瀏覽器 session，而不想在本機安裝 Chromium 時，請使用此類別。本機自動化請參閱 [`AgentBrowser`](https://mastra.zisheng.pro/zh-TW/reference/browser/agent-browser)。若要使用自然語言進行 AI 驅動的互動，請參閱 [`StagehandBrowser`](https://mastra.zisheng.pro/zh-TW/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,
})
```

## Constructor 參數

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

**apiKey** (`string`): Firecrawl API key。未提供時改用 FIRECRAWL\_API\_KEY 環境變數。如果兩者都未設定，constructor 會擲回例外。

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

**firecrawl** (`FirecrawlBrowserSessionOptions`): 建立 Sandbox session 時，傳給 Firecrawl browser() API 的 session 選項。

**firecrawl.ttl** (`number`): session 的最長存續時間，以秒為單位。

**firecrawl.activityTtl** (`number`): Sandbox 回收 session 前的閒置逾時秒數。

**firecrawl.streamWebView** (`boolean`): 設為 true 時，Firecrawl 可能會串流遠端 session 的 WebView frame。

**firecrawl.profile** (`{ name: string; saveChanges?: boolean }`): 具名 Firecrawl Sandbox profile。設定 saveChanges: true，可在 session 結束時保留 cookie 與登入 state；只有命名 profile 不會儲存變更。這與頂層 AgentBrowser profile 選項不同，後者是本機 Playwright user-data 目錄路徑。

**firecrawl.integration** (`string`): Firecrawl analytics 與路由使用的 integration label。

**firecrawl.origin** (`string`): Firecrawl 瀏覽器 session 的 origin 提示。

## Session 生命週期

Session 佈建取決於繼承自 `AgentBrowser` 的 `scope` 選項：

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

無論使用何者，瀏覽器關閉時 `FirecrawlBrowser` 都會刪除遠端 Firecrawl session，包括 session 建立或連線途中失敗的情況。

## Tool

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

## 相關內容

- [Firecrawl 文件](https://mastra.zisheng.pro/zh-TW/docs/browser/firecrawl)
- [`AgentBrowser` 參考文件](https://mastra.zisheng.pro/zh-TW/reference/browser/agent-browser)
- [Browser 概觀](https://mastra.zisheng.pro/zh-TW/docs/browser/overview)