跳至主要內容

Firecrawl

@mastra/browser-firecrawl 套件使用 Firecrawl Browser Sandbox 提供瀏覽器自動化。它透過 Firecrawl API 佈建遠端瀏覽器工作階段，並使用與 AgentBrowser 相同、具確定性且以無障礙功能為優先的 Tool 操作瀏覽器。

FirecrawlBrowser 擴充自 AgentBrowser，因此 Agent 可使用相同的 Tool 集合（browser_goto、browser_snapshot、browser_click 等），而瀏覽器本身則在 Firecrawl 的託管基礎架構中執行。不需要在本機安裝 Chromium。

適合使用 Firecrawl 的時機
「適合使用 Firecrawl 的時機」的直接連結

在需要以下功能時使用 Firecrawl：

  • 使用託管的瀏覽器工作階段，無須管理本機 Chromium 執行檔
  • 在無法啟動本機瀏覽器的環境中進行瀏覽器自動化
  • 每個 thread 各自隔離 Sandbox，並自動清理工作階段
  • 使用具名 Firecrawl profile，在不同工作階段之間保留 Cookie 和登入狀態

快速開始
「快速開始」的直接連結

安裝套件：

npm install @mastra/browser-firecrawl

設定 Firecrawl API 金鑰：

.env
FIRECRAWL_API_KEY=fc-...

建立瀏覽器執行個體，並將其指派給 Agent：

src/mastra/agents/firecrawl-agent.ts
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 使用與 AgentBrowser 相同的 scope 選項：

  • 'thread'（預設）：每個對話 thread 都會取得自己的 Firecrawl Sandbox 工作階段。當 thread 的瀏覽器關閉時，工作階段會一併刪除。
  • 'shared'：所有 thread 共用一個 Firecrawl Sandbox 工作階段，並在瀏覽器關閉時刪除。
const browser = new FirecrawlBrowser({
  scope: 'shared',
})

工作階段選項
「工作階段選項」的直接連結

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

const browser = new FirecrawlBrowser({
  firecrawl: {
    ttl: 600,
    activityTtl: 120,
    profile: {
      name: 'my-profile',
      saveChanges: true,
    },
  },
})
  • ttl：工作階段的最長存續時間（秒）。
  • activityTtl：Firecrawl 回收工作階段前的閒置逾時時間（秒）。
  • profile：具名 Firecrawl profile，可保留 Cookie 和登入狀態。設定 saveChanges: true，即可在工作階段結束時儲存 profile 變更。
備註

巢狀的 firecrawl.profile 選項是指儲存在 Firecrawl 基礎架構中的 profile。它不同於繼承自 AgentBrowser 的頂層 profile 選項，後者是本機 Playwright 使用者資料目錄的路徑。

自行託管 Firecrawl
「自行託管 Firecrawl」的直接連結

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

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