跳至主要內容

FirecrawlBrowser 類別

FirecrawlBrowser 類別提供以 Firecrawl Browser Sandbox 為基礎的瀏覽器自動化功能。它會透過 Firecrawl API 佈建遠端瀏覽器 session，並使用 Chrome DevTools Protocol（CDP）連線。

FirecrawlBrowser 擴充 AgentBrowser，並公開相同的確定性 Tool 集合。需要託管的瀏覽器 session，而不想在本機安裝 Chromium 時，請使用此類別。本機自動化請參閱 AgentBrowser。若要使用自然語言進行 AI 驅動的互動，請參閱 StagehandBrowser。

使用範例
「使用範例」的直接連結

src/mastra/agents/index.ts
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 參數
「Constructor 參數」的直接連結

FirecrawlBrowser 接受所有 AgentBrowser constructor 參數，以及以下參數：

apiKey?:

string
Firecrawl API key。未提供時改用 FIRECRAWL_API_KEY 環境變數。如果兩者都未設定，constructor 會擲回例外。

apiUrl?:

string
自行託管 Firecrawl API 的 base URL。

firecrawl?:

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

ttl?:

number
session 的最長存續時間，以秒為單位。

activityTtl?:

number
Sandbox 回收 session 前的閒置逾時秒數。

streamWebView?:

boolean
設為 true 時，Firecrawl 可能會串流遠端 session 的 WebView frame。

profile?:

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

integration?:

string
Firecrawl analytics 與路由使用的 integration label。

origin?:

string
Firecrawl 瀏覽器 session 的 origin 提示。

Session 生命週期
「Session 生命週期」的直接連結

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

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

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

Tool
「Tool」的直接連結

FirecrawlBrowser 提供與 AgentBrowser 相同的 Tool 集合，包括 browser_goto、browser_snapshot、browser_click、browser_type 與 browser_screenshot。完整清單與 Tool 參數請參閱 AgentBrowser Tool 參考文件。

On this page