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

# Firecrawl

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

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

## Firecrawl を使用する場面

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

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

## クイックスタート

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

**npm**:

```bash
npm install @mastra/browser-firecrawl
```

**pnpm**:

```bash
pnpm add @mastra/browser-firecrawl
```

**Yarn**:

```bash
yarn add @mastra/browser-firecrawl
```

**Bun**:

```bash
bun add @mastra/browser-firecrawl
```

Firecrawl API キーを設定します。

```bash
FIRECRAWL_API_KEY=fc-...
```

ブラウザインスタンスを作成し、Agent に割り当てます。

```typescript
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 セッションをすべてのスレッドで共有し、ブラウザを閉じると削除します。

```typescript
const browser = new FirecrawlBrowser({
  scope: 'shared',
})
```

## セッションオプション

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

```typescript
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 API を使用するには、`apiUrl` を設定します。

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

## 関連情報

- [Browser の概要](https://mastra.zisheng.pro/ja/docs/browser/overview)
- [AgentBrowser](https://mastra.zisheng.pro/ja/docs/browser/agent-browser)
- [ブラウザ録画（アルファ版）](https://mastra.zisheng.pro/ja/docs/browser/recording)
- [FirecrawlBrowser リファレンス](https://mastra.zisheng.pro/ja/reference/browser/firecrawl-browser)