メインコンテンツへ移動

Firecrawl

@mastra/browser-firecrawl パッケージは、Firecrawl Browser Sandbox を使用したブラウザ自動化を提供します。Firecrawl API を通じてリモートブラウザセッションをプロビジョニングし、AgentBrowser と同じ、決定的でアクセシビリティを優先した Tool で操作します。

FirecrawlBrowser は AgentBrowser を拡張しているため、ブラウザ自体を Firecrawl のホスト型インフラストラクチャで実行しながら、Agent は同じ Tool セット（browser_goto、browser_snapshot、browser_click など）を利用できます。ローカルへの Chromium のインストールは不要です。

Firecrawl を使用する場面
Firecrawl を使用する場面への直接リンク

次のような場合に Firecrawl を使用します。

  • ローカルの Chromium バイナリを管理せずにホスト型ブラウザセッションを利用したい
  • ローカルブラウザを起動できない環境でブラウザ自動化を行いたい
  • スレッドごとに Sandbox を分離し、セッションを自動でクリーンアップしたい
  • セッション間で Cookie とログイン状態を保持する名前付き Firecrawl プロファイルを利用したい

クイックスタート
クイックスタートへの直接リンク

パッケージをインストールします。

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'（デフォルト）: 会話スレッドごとに専用の Firecrawl Sandbox セッションを作成します。スレッドのブラウザを閉じると、セッションは削除されます。
  • 'shared': 1 つの Firecrawl Sandbox セッションをすべてのスレッドで共有し、ブラウザを閉じると削除します。
const browser = new FirecrawlBrowser({
  scope: 'shared',
})

セッションオプション
セッションオプションへの直接リンク

Firecrawl 固有のセッションオプションは firecrawl キーに渡します。これらは Firecrawl の browser() API に対応します。

const browser = new FirecrawlBrowser({
  firecrawl: {
    ttl: 600,
    activityTtl: 120,
    profile: {
      name: 'my-profile',
      saveChanges: true,
    },
  },
})
  • ttl: セッションの最大存続時間（秒）。
  • activityTtl: Firecrawl がセッションを再利用するまでのアイドルタイムアウト（秒）。
  • profile: Cookie とログイン状態を保持する名前付き Firecrawl プロファイル。セッション終了時にプロファイルの変更を保存するには、saveChanges: true を設定します。
注記

ネストされた firecrawl.profile オプションは、Firecrawl のインフラストラクチャに保存されたプロファイルを指します。AgentBrowser から継承する最上位の profile オプション（ローカルの Playwright ユーザーデータディレクトリのパス）とは異なります。

セルフホスト型 Firecrawl
セルフホスト型 Firecrawlへの直接リンク

セルフホスト型 Firecrawl API を使用するには、apiUrl を設定します。

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