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

AIプロンプト

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

コード実行

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

ライブビュー

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

動作の仕組み

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

# 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 (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 500500 ピクセル下にスクロール
get text @e1テキストコンテンツを取得
get url現在の URL を取得
wait @e1要素が表示されるまで待機
wait --load networkidleネットワークがアイドル状態になるまで待機
find text "X" clickテキストで要素を見つけてクリック
eval "js code"ページ内で JavaScript を実行

ライブビュー

すべての interact レスポンスには、ブラウザセッションをリアルタイムで表示するための URL が含まれます。
FieldDescription
liveViewUrl読み取り専用ストリーム — セッションを表示するために埋め込みます
interactiveLiveViewUrlインタラクティブストリーム — 閲覧者はクリック、入力、操作ができます
<!-- Read-only view -->
<iframe src="LIVE_VIEW_URL" width="100%" height="600" />

<!-- Interactive view — viewers can control the browser -->
<iframe src="INTERACTIVE_LIVE_VIEW_URL" width="100%" height="600" />
インタラクティブ ライブビューは、ログインフローや CAPTCHA への対応、ガイド付きワークフローなど、エンドユーザーがブラウザを見て操作する必要があるユーザー向け UI を構築する際に便利です。

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

作成

最初の 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["scrapeId"]

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["scrapeId"]

response = app.interact(scrape_id, prompt="Extract the dashboard data")
print(response.output)
app.stop_interaction(scrape_id)
パラメータデフォルト説明
name永続プロファイルの名前です。同じ名前のスクレイピングはブラウザの状態を共有します。
saveChangestruetrue の場合、interact セッションの停止時にブラウザの状態がプロファイルに保存されます。既存のデータを読み込むだけで書き込みは行わないようにするには、false に設定します。これは、複数の同時リーダーが必要な場合に便利です。
一度にプロファイルへ保存できるセッションは 1 つだけです。別のセッションがすでに保存中の場合は、409 エラーが返されます。saveChanges: false で同じプロファイルを開くことはできますし、後でもう一度試すこともできます。
ブラウザの状態は、interact セッションが停止したときに保存されます。プロファイルを再利用できるよう、完了したら必ずセッションを停止してください。

使い分けの目安

ユースケース推奨理由
Web searchSearch専用の検索エンドポイント
URL から整形されたコンテンツを取得ScrapeAPI 呼び出し 1 回で、セッション不要
ページ上でクリック、入力、移動を行うInteract (prompt)英語で指示するだけ
操作の先にあるデータを抽出するInteract (prompt)セレクタ不要
複雑なスクレイピングロジックInteract (code)Playwright を完全に制御可能
Interact と Browser Sandbox の違い: Interact は Browser Sandbox と同じインフラ上に構築されていますが、最も一般的なパターン、つまりページをスクレイピングしてからさらに深く進む場合に、より使いやすいインターフェースを提供します。Browser Sandbox は、特定のスクレイピングに紐づかない独立したブラウザセッションが必要な場合に適しています。

料金

セッション1分あたり2 credits、秒単位で按分されます。スクレイピング自体の請求は別途行われます (スクレイピング1回あたり1 credit に加え、format ごとのコスト) 。

API リファレンス

リクエスト本文 (POST)

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

レスポンス

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

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