操作 | Firecrawl

ページをスクレイピングしてクリーンなデータを取得し、その後 /interact を呼び出して、そのページ上でアクションを開始します。ボタンのクリック、フォームへの入力、動的コンテンツの抽出、さらに深いページへの移動が可能です。やりたいことを記述するだけでもよく、完全に制御したい場合はコードを書くこともできます。

AIプロンプト

ページ上で実行したいアクションを記述します

コード実行

Playwright や agent-browser を使って、安全にコード実行で操作できます

ライブビュー

埋め込み可能なストリームを通じて、ブラウザーをリアルタイムで確認したり操作したりできます

動作の仕組み

POST /v2/scrape で URL をスクレイピングします。レスポンスには data.metadata.scrapeId に scrapeId が含まれます。必要に応じて profile を渡すと、セッションをまたいでブラウザの状態を保持できます。
prompt または Playwright の code を指定して POST /v2/scrape/{scrapeId}/interact を呼び出し、操作します。最初の呼び出しでは、スクレイピングしたセッションが再開され、ページの操作を開始できます。
完了したら、DELETE /v2/scrape/{scrapeId}/interact でセッションを停止します。

クイックスタート

ページをスクレイピングし、操作し、セッションを停止します:

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

# 1. Amazonのホームページをスクレイピング
result = app.scrape("https://www.amazon.com", formats=["markdown"])
scrape_id = result.metadata.scrape_id

# 2. インタラクト — 商品を検索して価格を取得
app.interact(scrape_id, prompt="Search for iPhone 16 Pro Max")
response = app.interact(scrape_id, prompt="Click on the first result and tell me the price")
print(response.output)

# 3. セッションを停止
app.stop_interaction(scrape_id)

Response

{
  "success": true,
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "output": "The iPhone 16 Pro Max (256GB) is priced at $1,199.00.",
  "exitCode": 0,
  "killed": false
}

プロンプトで操作する

ページを操作する最も簡単な方法です。やりたいことを自然言語で記述するだけで、自動的にクリック、入力、スクロール、データの抽出を行います。

response = app.interact(scrape_id, prompt="What are the customer reviews saying about battery life?")
print(response.output)

レスポンスには、エージェントの回答が含まれる output フィールドがあります。

Response

{
  "success": true,
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "output": "Customers are generally positive about battery life. Most reviewers report 8-10 hours of use on a single charge. A few noted it drains faster with heavy multitasking.",
  "stdout": "...",
  "result": "...",
  "stderr": "",
  "exitCode": 0,
  "killed": false
}

プロンプトは小さく、焦点を絞る

プロンプトは、それぞれが単一の明確なタスクであるときに最も効果を発揮します。エージェントに複雑な複数ステップのワークフローを一度に実行させるのではなく、個別の interact 呼び出しに分けてください。各呼び出しは同じブラウザセッションを再利用するため、それまでの状態が引き継がれます。

コードの実行

より細かく制御したい場合は、ブラウザサンドボックスでコードを直接実行できます。page 変数 (Playwright の Page オブジェクト) は Node.js と Python で利用できます。Bash モードには agent-browser がプリインストールされています。セッション内でスクリーンショットを撮ることもできます — Node.js では (await page.screenshot()).toString("base64")、Python では await page.screenshot(path="/tmp/screenshot.png")、Bash では agent-browser screenshot を使用してください。

Node.js (Playwright)

デフォルトの言語です。Playwright のコードを直接記述できます — page はすでにブラウザに接続されています。

response = app.interact(scrape_id, code="""
// ボタンをクリックしてナビゲーションを待機
await page.click('#next-page');
await page.waitForLoadState('networkidle');

// 新しいページからコンテンツを取得
const title = await page.title();
const content = await page.$eval('.article-body', el => el.textContent);
JSON.stringify({ title, content });
""")
print(response.result)

Python

Playwright の Python API を使う場合は、language を "python" に設定します。

response = app.interact(
    scrape_id,
    code="""
import json

await page.click('#load-more')
await page.wait_for_load_state('networkidle')

items = await page.query_selector_all('.item')
data = []
for item in items:
    text = await item.text_content()
    data.append(text.strip())

print(json.dumps(data))
""",
    language="python",
)
print(response.stdout)

Bash (agent-browser)

agent-browser は、60 以上のコマンドがプリインストールされたサンドボックス内の CLI です。要素参照 (@e1, @e2, …) 付きのアクセシビリティツリーを提供し、LLM による自動化に最適です。

# インタラクティブな要素を確認するためにスナップショットを取得する
snapshot = app.interact(
    scrape_id,
    code="agent-browser snapshot -i",
    language="bash",
)
print(snapshot.stdout)
# 出力:
# [document]
#   @e1 [input type="text"] "Search..."
#   @e2 [button] "Search"
#   @e3 [link] "About"

# @refs を使用して要素を操作する
app.interact(
    scrape_id,
    code='agent-browser fill @e1 "firecrawl" && agent-browser click @e2',
    language="bash",
)

一般的な agent-browser コマンド:

コマンド	説明
`snapshot`	要素参照付きの完全なアクセシビリティツリー
`snapshot -i`	インタラクティブな要素のみ
`click @e1`	参照で要素をクリック
`fill @e1 "text"`	フィールドをクリアしてテキストを入力
`type @e1 "text"`	クリアせずにテキストを入力
`press Enter`	キーボードのキーを押す
`scroll down 500`	500 ピクセル下にスクロール
`get text @e1`	テキストコンテンツを取得
`get url`	現在の URL を取得
`wait @e1`	要素が表示されるまで待機
`wait --load networkidle`	ネットワークがアイドル状態になるまで待機
`find text "X" click`	テキストで要素を見つけてクリック
`screenshot`	現在のページのスクリーンショットを撮る
`eval "js code"`	ページ内で JavaScript を実行

ライブビュー

すべての Interact レスポンスでは、埋め込んでブラウザをリアルタイムで確認できる liveViewUrl が返されます。デバッグやデモ、ブラウザ駆動の UI の構築に便利です。

Response

{
  "success": true,
  "liveViewUrl": "https://liveview.firecrawl.dev/...",
  "interactiveLiveViewUrl": "https://liveview.firecrawl.dev/...",
  "stdout": "",
  "result": "...",
  "exitCode": 0
}

<iframe src="LIVE_VIEW_URL" width="100%" height="600" />

インタラクティブライブビュー

レスポンスには interactiveLiveViewUrl も含まれます。閲覧専用の標準ライブビューとは異なり、インタラクティブライブビューでは、埋め込みストリームを通じてユーザーがブラウザセッションを直接クリック、入力、操作できます。これは、ログインフローや、エンドユーザーがブラウザを操作する必要があるガイド付きワークフローなど、ユーザー向けのブラウザUIを構築する場合に役立ちます。

<iframe src="INTERACTIVE_LIVE_VIEW_URL" width="100%" height="600" />

セッションのライフサイクル

作成

最初の POST /v2/scrape/{scrapeId}/interact 呼び出しで、スクレイピングセッションが継続され、インタラクションが開始されます。

再利用

同じscrapeIdに対する後続のinteract呼び出しでは、既存のセッションが再利用されます。browserは開いたままで、呼び出し間でも状態が維持されるため、複数のインタラクションを連続して実行できます。

# 最初の呼び出し — タブをクリック
app.interact(scrape_id, code="await page.click('#tab-2')")

# 2回目の呼び出し — タブは引き続き選択されたままで、その内容を抽出
result = app.interact(scrape_id, code="await page.$eval('#tab-2-content', el => el.textContent)")
print(result.result)

クリーンアップ

使用が終わったら、明示的にセッションを停止してください:

app.stop_interaction(scrape_id)

セッションは、TTL (default: 10分) または非アクティブ timeout (default: 5分) に基づいて自動的に期限切れになります。

不要な課金を避けるため、使用後は必ずセッションを停止してください。Credits は秒単位で按分されます。

永続プロファイル

デフォルトでは、各スクレイピング + interact セッションはクリーンなブラウザで開始されます。profile を使うと、スクレイピング間でブラウザの状態 (cookies、localStorage、sessions) を保存して再利用できます。これは、ログイン状態を維持したり、設定を保持したりするのに便利です。 scrape を呼び出すときに profile パラメータを渡します。同じプロファイル名を持つセッションは状態を共有します。

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR-API-KEY")

# セッション1: プロファイルでスクレイピングし、ログインしてから停止（状態は保存される）
result = app.scrape(
    "https://app.example.com/login",
    formats=["markdown"],
    profile={"name": "my-app", "save_changes": True},
)
scrape_id = result.metadata.scrape_id

app.interact(scrape_id, prompt="Fill in user@example.com and password, then click Login")
app.stop_interaction(scrape_id)

# セッション2: 同じプロファイルでスクレイピング — すでにログイン済み
result = app.scrape(
    "https://app.example.com/dashboard",
    formats=["markdown"],
    profile={"name": "my-app", "save_changes": True},
)
scrape_id = result.metadata.scrape_id

response = app.interact(scrape_id, prompt="Extract the dashboard data")
print(response.output)
app.stop_interaction(scrape_id)

パラメータ	デフォルト	説明
`name`	—	永続プロファイルの名前です。同じ名前のスクレイピングはブラウザの状態を共有します。
`saveChanges`	`true`	`true` の場合、interact セッションの停止時にブラウザの状態がプロファイルに保存されます。既存のデータを読み込むだけで書き込みは行わないようにするには、`false` に設定します。これは、複数の同時リーダーが必要な場合に便利です。

一度にプロファイルへ保存できるセッションは 1 つだけです。別のセッションがすでに保存中の場合は、409 エラーが返されます。saveChanges: false で同じプロファイルを開くことはできますし、後でもう一度試すこともできます。

ブラウザの状態は、interact セッションが停止したときに保存されます。プロファイルを再利用できるよう、完了したら必ずセッションを停止してください。

使い分けの目安

ユースケース	推奨	理由
Web search	Search	専用の検索エンドポイント
URL から整形されたコンテンツを取得	Scrape	API 呼び出し 1 回で、セッション不要
ページ上でクリック、入力、移動を行う	Interact (prompt)	英語で指示するだけ
操作の先にあるデータを抽出する	Interact (prompt)	セレクタ不要
複雑なスクレイピングロジック	Interact (code)	Playwright を完全に制御可能

Interact と Browser Sandbox の違い: Interact は Browser Sandbox と同じインフラ上に構築されていますが、最も一般的なパターン、つまりページをスクレイピングしてからさらに深く進む場合に、より使いやすいインターフェースを提供します。Browser Sandbox は、特定のスクレイピングに紐づかない独立したブラウザセッションが必要な場合に適しています。

料金

コードのみ (prompt なし) — セッション1分あたり2 credits
AI プロンプトあり — セッション1分あたり7 credits
スクレイピング — スクレイピング自体の請求は別途行われます (スクレイピング1回あたり1 credit に加え、format ごとのコスト) 。

API リファレンス

Execute Interact — POST /v2/scrape/{scrapeId}/interact
Stop Interact — DELETE /v2/scrape/{scrapeId}/interact

リクエスト本文 (POST)

フィールド	型	デフォルト	説明
`prompt`	`string`	—	AIエージェント向けの自然言語タスクです。`code` が設定されていない場合は必須です。最大10,000文字。
`code`	`string`	—	実行するコード (Node.js、Python、または Bash) 。`prompt` が設定されていない場合は必須です。最大100,000文字。
`language`	`string`	`"node"`	`"node"`、`"python"`、または `"bash"`。`code` を使用する場合にのみ指定します。
`timeout`	`number`	`30`	タイムアウト時間 (秒) (1～300) 。
`origin`	`string`	—	アクティビティ追跡用の呼び出し元識別子。

レスポンス

Field	Description
`success`	エラーなく実行が完了した場合は `true`
`liveViewUrl`	ブラウザセッション用の読み取り専用のライブビュー URL
`interactiveLiveViewUrl`	インタラクティブライブビュー URL (閲覧者がブラウザを操作できます)
`output`	プロンプトに対するエージェントの自然言語での回答。`prompt` を使用している場合にのみ含まれます。
`stdout`	コード実行時の標準出力
`result`	サンドボックスからの生の戻り値。`code` の場合: 最後に評価された式。`prompt` の場合: エージェントが `output` の生成に使用した生のページスナップショット。
`stderr`	標準エラー出力
`exitCode`	終了コード (`0` = 成功)
`killed`	タイムアウトにより実行が終了した場合は `true`

フィードバックやサポートが必要な場合は、help@firecrawl.com にメールするか、Discord でお問い合わせください。

はじめに

主要エンドポイント

その他

クイックスタート

開発者ガイド

webhook

ユースケース

ダッシュボード

コントリビューション

スクレイピング後にページを操作

AIプロンプト

コード実行

ライブビュー

動作の仕組み

クイックスタート

プロンプトで操作する

プロンプトは小さく、焦点を絞る

コードの実行

Node.js (Playwright)

Python

Bash (agent-browser)

ライブビュー

インタラクティブライブビュー

セッションのライフサイクル

作成

再利用

クリーンアップ

永続プロファイル

使い分けの目安

料金

API リファレンス

リクエスト本文 (POST)

レスポンス

はじめに

主要エンドポイント

その他

クイックスタート

開発者ガイド

webhook

ユースケース

ダッシュボード

コントリビューション

Documentation Index

AIプロンプト

コード実行

ライブビュー

​動作の仕組み

​クイックスタート

​プロンプトで操作する

​プロンプトは小さく、焦点を絞る

​コードの実行

​Node.js (Playwright)

​Python

​Bash (agent-browser)

​ライブビュー

​インタラクティブ ライブビュー

​セッションのライフサイクル

​作成

​再利用

​クリーンアップ

​永続プロファイル

​使い分けの目安

​料金

​API リファレンス

​リクエスト本文 (POST)

​レスポンス

動作の仕組み

クイックスタート

プロンプトで操作する

プロンプトは小さく、焦点を絞る

コードの実行

Node.js (Playwright)

Python

Bash (agent-browser)

ライブビュー

インタラクティブライブビュー

セッションのライフサイクル

作成

再利用

クリーンアップ

永続プロファイル

使い分けの目安

料金

API リファレンス

リクエスト本文 (POST)

レスポンス