ブラウザサンドボックス
エージェントが Web とやり取りできる安全なブラウザサンドボックス。
エージェントワークフローには Interact を使用してください。Interact はサポート対象の CLI/MCP パスであり、スクレイピング後にプロンプトまたはコードで操作できます。MCP では URL から直接開くこともサポートしています。
| 対象 | 用途 | エントリーポイント | エージェント向けインターフェース |
|---|---|---|---|
| ブラウザサンドボックス | サンドボックス、CDP URL、ライブビュー、または永続的なセッションライフサイクルを必要とする API/SDK ユーザー向けのスタンドアロンのブラウザセッション | POST /v2/interact | API と SDKs。非表示の CLI browser コマンドはレガシーです |
| Interact | スクレイピングしたページ上での操作。MCP は firecrawl_interact の URL モードで URL から開くこともできます | POST /v2/scrape/{scrapeId}/interact、スクレイピング後の CLI interact、または MCP firecrawl_interact | CLI/MCP のエージェントワークフローに推奨 |
Firecrawl ブラウザサンドボックス は、API および SDK のユーザーに、エージェントが Web とやり取りできる安全なブラウザ環境を提供します。フォームへの入力、ボタンのクリック、認証などを実行できます。 ローカルでのセットアップは不要で、Chromium のインストールやドライバーの互換性の問題もありません。agent browser と playwright はプリインストール済みです。
API、Node SDK、Python SDK、および Vercel AI SDK 経由で利用できます。非表示の firecrawl browser CLI コマンドはレガシーです。CLI と MCP のエージェントフローでは、代わりに scrape + interact を使用してください。
AI コーディングエージェント (Claude Code、Codex、Open Code、Cursor など) に Interact 対応を追加するには、Firecrawl スキルをインストールします。
npx -y firecrawl-cli@latest init --all --browser各セッションは、インフラを管理することなくスケールする、分離された使い捨てまたは永続的なサンドボックス内で実行されます。
セッションを作成し、コードを実行して終了します。
// npm install firecrawl
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
// 1. Launch a session
const session = await firecrawl.browser();
console.log(session.cdpUrl); // wss://cdp-proxy.firecrawl.dev/cdp/...
// 2. Execute code
const result = await firecrawl.browserExecute(session.id, {
code: `
await page.goto("https://news.ycombinator.com");
const title = await page.title();
console.log(title);
`,
language: "node",
});
console.log(result.result); // "Hacker News"
// 3. Close
await firecrawl.deleteBrowser(session.id);- ドライバーのインストール不要 - Chromium バイナリ不要、
playwright install不要、ドライバー互換性の問題なし - Python、JavaScript、Bash 対応 - API、CLI、または SDK 経由でコードを送信して結果を取得。3 つの言語すべてがサンドボックス環境上でリモート実行されます
- agent-browser - 60 以上のコマンドがプリインストール済みの CLI。AI エージェントは Playwright コードではなくシンプルな bash コマンドを書くことで操作できます
- Playwright ロード済み - サンドボックス環境には Playwright がプリインストール済み。必要であればエージェントは Playwright コードを記述することもできます
- CDP へのアクセス - 完全な制御が必要なときは、独自の Playwright インスタンスを WebSocket 経由で接続可能
- ライブビュー - 埋め込み可能なストリーム URL を使って、セッションをリアルタイムで監視可能
- インタラクティブ ライブビュー - 埋め込み可能なインタラクティブなストリームを通じて、ユーザーがブラウザを直接操作できるようにします
セッションID、CDP URL、ライブビューのURLを返します。
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const session = await firecrawl.browser({
ttl: 120,
activityTtl: 60,
});
console.log(session.id);
console.log(session.cdpUrl); // wss://cdp-proxy.firecrawl.dev/cdp/...
console.log(session.liveViewUrl); // https://liveview.firecrawl.dev/...{
"success": true,
"id": "550e8400-e29b-41d4-a716-446655440000",
"cdpUrl": "wss://browser.firecrawl.dev/cdp/550e8400...?token=abc123...",
"liveViewUrl": "https://liveview.firecrawl.dev/...",
"interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
"expiresAt": "2025-01-15T10:40:00Z"
}セッション内で Python、JavaScript、または bash のコードを実行します。Output は stdout 経由で返されます。Node.js では、最後の式の値も result として利用できます。
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const result = await firecrawl.browserExecute("YOUR_SESSION_ID", {
code: 'await page.goto("https://example.com"); const title = await page.title(); console.log(title);',
language: "node",
});
console.log(result);{
"success": true,
"stdout": "",
"result": "Example Domain",
"stderr": "",
"exitCode": 0,
"killed": false
}セッション内でダウンロードされたファイルはキャプチャして、base64 として返すことができます。execute エンドポイントから Playwright の download API を使用します。
import base64
async with page.expect_download() as download_info:
await page.click('a#download-link') # ダウンロードをトリガーする要素をクリック
download = download_info.value
path = await download.path()
# 必要に応じて既知のパスに保存
# await download.save_as('/tmp/myfile.pdf')
# ファイル内容を読み取り、base64 として出力
with open(path, "rb") as f:
content = base64.b64encode(f.read()).decode()
print(content)サンドボックスのファイルシステムは一時的なものです。ダウンロードしたファイルはセッションの終了時に失われます。ファイルを永続化するには、セッション内で内容を読み取り、独自のストレージに保存してください。永続プロファイルではブラウザーの状態 (cookie、localStorage) は保持されますが、ディスク上のファイルは保持されません。
agent-browser は、すべてのサンドボックスにプリインストールされているヘッドレスブラウザ CLI です。Playwright のコードを書く代わりに、エージェントはシンプルな bash コマンドを送信します。CLI は自動的に --cdp フラグを付与し、agent-browser がアクティブなセッションに自動で接続できるようにします。
以下の firecrawl browser CLI の例は、レガシーなブラウザサンドボックス セッション向けです。CLI/MCP のエージェント ワークフローでは、firecrawl interact または MCP の firecrawl_interact ツールを優先して使用してください。
browser コマンドを使う最速の方法です。省略記法も execute も、どちらも自動的に agent-browser にコマンドを送信します。省略記法は単に execute を省略し、必要に応じてセッションを自動的に開始します。
firecrawl browser "open https://example.com"
firecrawl browser "snapshot"
firecrawl browser "click @e5"明示的な形では execute を使用します。コマンドは自動的に agent-browser に送信されるので、agent-browser と入力したり、--bash を付けたりする必要はありません。
firecrawl browser execute "open https://example.com"
firecrawl browser execute "snapshot"API または SDK を使って agent-browser コマンドを実行するには、language: "bash" を指定します：
curl -X POST "https://api.firecrawl.dev/v2/interact/YOUR_SESSION_ID/execute" \
-H "Authorization: Bearer $FIRECRAWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"code": "agent-browser snapshot",
"language": "bash"
}'デフォルトでは、各ブラウザセッションは常にまっさらな状態から始まります。profile を使うと、セッション間でブラウザの状態を保存し再利用できます。ログイン状態の維持や設定の保持に役立ちます。
プロファイルを保存または選択するには、セッション作成時に profile パラメータを使用します。
const session = await firecrawl.browser({
ttl: 600,
profile: {
name: "my-profile",
saveChanges: true,
},
});| パラメータ | デフォルト | 説明 |
|---|---|---|
name | — | 永続プロファイルの名前です。同じ名前のセッションはストレージを共有します。 |
saveChanges | true | true の場合、ブラウザの状態は終了時にプロファイルへ保存されます。false に設定すると、既存データを読み込むだけで書き込みは行いません — 複数の同時読み取りが必要な場合に便利です。 |
一度に 1 つのセッションだけがプロファイルへ保存できます。ほかのセッションがすでに保存中の場合、409 エラーが返されます。同じプロファイルを saveChanges: false で開くことはできますが、そうでなければ時間をおいて再試行してください。
ブラウザセッションの状態は、セッションがクローズされたときにのみ保存されます。そのため、再利用できるよう、使い終わったらブラウザセッションをクローズすることを推奨します。セッションがクローズされると、そのセッション ID は無効になり、再利用できなくなります。代わりに、同じプロファイル名で新しいセッションを作成し、レスポンスで返される新しいセッション ID を使用してください。保存してクローズするには:
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
await firecrawl.deleteBrowser("YOUR_SESSION_ID");import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const { sessions } = await firecrawl.listBrowsers();
console.log(sessions);
// ステータスでフィルター
const { sessions: active } = await firecrawl.listBrowsers({ status: "active" });
console.log(active);{
"success": true,
"sessions": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "active",
"cdpUrl": "wss://browser.firecrawl.dev/cdp/550e8400...?token=abc123...",
"liveViewUrl": "https://liveview.firecrawl.dev/...",
"interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
"createdAt": "2025-01-15T10:30:00Z",
"lastActivity": "2025-01-15T10:35:00Z"
}
]
}セッションには 2 種類の TTL 設定があります:
| Parameter | Default | Description |
|---|---|---|
ttl | 600s (10 min) | セッションの最大存続時間 (30-3600s) |
activityTtl | 300s (5 min) | 非アクティブ時の自動クローズまでの時間 (10-3600s) |
import { Firecrawl } from 'firecrawl';
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
await firecrawl.deleteBrowser("YOUR_SESSION_ID");各セッションのレスポンスには liveViewUrl が含まれており、これを埋め込むことでブラウザーの状態をリアルタイムで確認できます。デバッグ、デモ、ブラウザー駆動型 UI の構築などに便利です。
{
"success": true,
"id": "550e8400-e29b-41d4-a716-446655440000",
"cdpUrl": "wss://browser.firecrawl.dev/cdp/550e8400...?token=abc123...",
"liveViewUrl": "https://liveview.firecrawl.dev/...",
"interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
"expiresAt": "2025-01-15T10:40:00Z"
}<iframe src="LIVE_VIEW_URL" width="100%" height="600" />レスポンスには interactiveLiveViewUrl も含まれます。閲覧専用の標準的な Live View と異なり、インタラクティブ Live View では、埋め込みストリームを通じてユーザーがブラウザセッションを直接操作できます (クリックや文字入力など) 。これは、ユーザー向けのブラウザ UI の構築、共同でのデバッグ、あるいは閲覧者がブラウザを操作する必要があるあらゆるシナリオに有用です。
<iframe src="INTERACTIVE_LIVE_VIEW_URL" width="100%" height="600" />すべてのセッションは CDP WebSocket URL を提供します。execute API と --bash フラグでほとんどのユースケースはカバーできますが、完全にローカルで制御したい場合は、直接接続することもできます。
import { Firecrawl } from 'firecrawl';
import { chromium } from "playwright-core";
const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });
const session = await firecrawl.browser();
const browser = await chromium.connectOverCDP(session.cdpUrl);
const context = browser.contexts()[0];
const page = context.pages()[0] || (await context.newPage());
await page.goto("https://example.com");
console.log(await page.title());
await browser.close();
await firecrawl.deleteBrowser(session.id);| ユースケース | 適切なツール |
|---|---|
| 既知の URL からコンテンツを抽出する | Scrape |
| Web を検索して結果を取得する | Search |
| ページネーションの操作、フォーム入力、クリックを伴うフローの操作 | Browser |
| インタラクションを伴うマルチステップのワークフロー | Browser |
| 複数のサイトを並列にブラウジングする | Browser (各セッションは分離されている) |
- 競合分析 - 競合サイトを閲覧し、検索フォームやフィルターを操作して、価格や機能を構造化データとして抽出する
- ナレッジベースの取り込み - クリック操作、ページネーション、認証が必要なヘルプセンター、ドキュメント、サポートポータルを辿る
- 市場調査 - 複数のブラウザーセッションを並列で起動し、求人サイト、不動産リスティング、法的データベースなどからデータセットを構築する
料金体系はシンプルで、ブラウザの稼働1分あたり2クレジットです。無料プランでは最大5時間まで無料で利用できます。
初期リリースでは、すべてのプランで最大 20 個のブラウザーセッションを同時に稼働させることができます。
ご意見やご不明な点がありましたら、[email protected] までメールいただくか、Discord でご連絡ください。
Firecrawl API key が必要な AI agent の方は、firecrawl.dev/agent-onboarding/SKILL.md の自動オンボーディング手順をご覧ください。