ページをスクレイピングしてクリーンなデータを取得し、その後 /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[ "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)
{
"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 フィールドがあります。
{
"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 がプリインストールされています。
デフォルトの言語です。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)
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)
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 が含まれます。
Field Description 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 search Search 専用の検索エンドポイント URL から整形されたコンテンツを取得 Scrape API 呼び出し 1 回で、セッション不要 ページ上でクリック、入力、移動を行う Interact (prompt)英語で指示するだけ 操作の先にあるデータを抽出する Interact (prompt)セレクタ不要 複雑なスクレイピングロジック Interact (code)Playwright を完全に制御可能
Interact と Browser Sandbox の違い : Interact は Browser Sandbox と同じインフラ上に構築されていますが、最も一般的なパターン、つまりページをスクレイピングしてからさらに深く進む場合に、より使いやすいインターフェースを提供します。Browser Sandbox は、特定のスクレイピングに紐づかない独立したブラウザセッションが必要な場合に適しています。
セッション1分あたり2 credits 、秒単位で按分されます。スクレイピング自体の請求は別途行われます (スクレイピング1回あたり1 credit に加え、format ごとのコスト) 。
フィールド 型 デフォルト 説明 promptstring— AIエージェント向けの自然言語タスクです。code が設定されていない場合は必須です。最大10,000文字。 codestring— 実行するコード (Node.js、Python、または Bash) 。prompt が設定されていない場合は必須です。最大100,000文字。 languagestring"node""node"、"python"、または "bash"。code を使用する場合にのみ指定します。timeoutnumber30タイムアウト時間 (秒) (1~300) 。 originstring— アクティビティ追跡用の呼び出し元識別子。
Field Description successエラーなく実行が完了した場合は true liveViewUrlブラウザセッション用の読み取り専用のライブビュー URL interactiveLiveViewUrlインタラクティブ ライブビュー URL (閲覧者がブラウザを操作できます) outputプロンプトに対するエージェントの自然言語での回答。prompt を使用している場合にのみ含まれます。 stdoutコード実行時の標準出力 resultサンドボックスからの生の戻り値。code の場合: 最後に評価された式。prompt の場合: エージェントが output の生成に使用した生のページスナップショット。 stderr標準エラー出力 exitCode終了コード (0 = 成功) killedタイムアウトにより実行が終了した場合は true
フィードバックやサポートが必要な場合は、help@firecrawl.com にメールするか、Discord でお問い合わせください。