Agent

適切なツールの選び方。 URL がわからない場合や、Web 全体を自律的に移動しながらデータを収集する必要がある場合は、Agent が適しています。

• 単一の既知のURLに対しては、/scrape のJSONモード の方が低コストで、同期的に実行できます。
• 詳しい比較: Data Extractor の選び方。

Firecrawl の /agent は、検索・ナビゲーション・データ収集を自動で行い、最も幅広い種類の Web サイトからでも、通常はアクセスしづらい場所のデータを見つけ出し、他のどの API にもできない方法でデータを発見する魔法のような API です。人間なら何時間もかかるエンドツーエンドのデータ収集を、スクリプトや手作業なしで数分で完了させます。 単一のデータポイントが欲しい場合でも、大規模なデータセット全体が必要な場合でも、Firecrawl の /agent がデータ取得を代わりに行います。

/agent は、あらゆる場所にあるデータに対する「ディープリサーチ」と考えてください！

Agent は /extract の優れた点をすべて引き継ぎつつ、さらに強化しています:

• URL 不要: 必要な内容を prompt パラメータで記述するだけでよく、URL は任意です
• ディープ Web 検索: サイト内を自律的に検索・巡回し、必要なデータを深部まで探索
• 高い信頼性と正確性: 幅広い種類のクエリやユースケースで安定して動作
• 高速: 複数ソースを並列処理して結果を素早く取得

必須パラメータは prompt のみです。どのようなデータを抽出したいかを記述してください。構造化された出力を得るには、JSON スキーマを指定してください。各 SDK は、型安全なスキーマ定義のために Pydantic (Python) と Zod (Node) をサポートしています：

{  "success": true,  "status": "completed",  "data": {    "founders": [      {        "name": "Eric Ciarla",        "role": "Co-founder",        "background": "Previously at Mendable"      },      {        "name": "Nicolas Camara",        "role": "Co-founder",        "background": "Previously at Mendable"      },      {        "name": "Caleb Peffer",        "role": "Co-founder",        "background": "Previously at Mendable"      }    ]  },  "expiresAt": "2024-12-15T00:00:00.000Z",  "creditsUsed": 15}

エージェントの対象を特定のページに絞り込むために、任意で URL を指定できます。

Agent ジョブは非同期で実行されます。ジョブの実行を開始すると、ステータス確認に使える Job ID が返されます：

• デフォルトの方法: agent() が完了まで待機し、最終結果を返します
• 開始してポーリング: start_agent (Python) または startAgent (Node) で即座に Job ID を取得し、その後 get_agent_status / getAgentStatus でポーリングします
• ポーリングの代わりにプッシュ: ジョブの開始時に webhook を渡すと、実行の進行中から完了まで agent events を受信できます

{  "success": true,  "status": "processing",  "expiresAt": "2024-12-15T00:00:00.000Z"}

{  "success": true,  "status": "completed",  "data": {    "founders": [      {        "name": "Eric Ciarla",        "role": "Co-founder"      },      {        "name": "Nicolas Camara",        "role": "Co-founder"      },      {        "name": "Caleb Peffer",        "role": "Co-founder"      }    ]  },  "expiresAt": "2024-12-15T00:00:00.000Z",  "creditsUsed": 15}

GET /agent は、Playground または API から開始されたものを含む、チームのすべてのエージェント実行を新しい順に一覧表示します。各エントリには、実行 ID、作成時刻、ステータス、対象を示す簡単なヒント、開始時に指定されたオプションが含まれます。

結果は 20 件ずつ固定サイズでページネーションされます。次のページがある場合、レスポンスには next URL が含まれます。その before タイムスタンプを渡すと、次のページを取得できます。SDK メソッドは自動ページネーションを行わないため、どこまで遡るかを制御できます。

Agent はストリーミング接続を維持しません。Server-Sent Events のストリームも WebSocket もないため、トレースをポーリングするか、webhook を受信して 実行 を追跡します。

トレースイベントを独自に並べ替える場合は、まず agent.id ごとにグループ化してください。producerSequence はイベントを出力するエージェントごとに単調増加するため、単一のグローバルソートではオーケストレーターのイベントとサブエージェントのイベントが誤って交互に並びます。また、終了イベント run.finished の後もしばらくイベントが到着することがあるため、最終状態を表示する前に短いテールウィンドウの間はポーリングを続けてください。

各実行では、ツール呼び出し、推論の要約、進行状況のアップデート、ブラウザセッション、出力アーティファクトの変更を含む、時系列順の正規実行トレースが記録されます。実行のデバッグや、ライブ進行状況UIの構築に利用できます。

artifact.updated トレースイベントは、snapshotId を通じてエージェントの作業中の出力を参照します。スナップショットの完全な内容は、snapshotsエンドポイントで取得できます。

実行 は処理の進行に応じて作業中の出力を アーティファクト に書き込みます。実行 の トレース を取得すれば、これらを取得できます。各 artifact.updated イベントは、1 つの アーティファクト に対する 1 つの変更を表します。artifact.kind は json、markdown、html、screenshot、または text、artifact.path は 実行 が保存した場所、artifact.snapshotId は GET /agent/{jobId}/snapshots/{snapshotId} でコンテンツを取得する際に使用するハンドルです。スナップショット endpoint は、そのコンテンツを string 型の snapshot フィールドで返します。json アーティファクト の場合、この string は JSON エンコードされているためデコードが必要です。一方、markdown、html、text アーティファクト の場合はコンテンツそのものです。

実行 が生成したページコンテンツを取得するには、トレース を取得し、必要な kind の artifact.updated イベントを抽出してから、各 スナップショット を取得します。

これを基に構築する前に、次の 2 点を押さえておいてください。

• アーティファクト は 実行 の出力であり、ページごとのアーカイブではありません。 実行 が アーティファクト に書き込む内容は、prompt をどのように処理するかによって異なります。そのため、アーティファクト セットは、開いたすべてのページの記録として保証されるものではなく、その特定の 実行 が生成した出力として扱ってください。
• 残りの情報は tool result に含まれます。 各 tool_call.finished イベントには、その tool が返した内容を保持する result フィールドが含まれます。アーティファクト にならなかったコンテンツはここに含まれます。

Agent playground から、エージェントの実行を直接共有できます。共有リンクは公開されるため、リンクを知っている人なら誰でも実行結果とアクティビティを閲覧できます。また、アクセスを取り消してリンクをいつでも無効にできます。共有ページは検索エンジンにインデックスされません。

Firecrawl Agent は Spark 2 で動作します。Spark 2 は、同等の精度を保ちながら、従来の Spark 1 モデルよりも低コストで高速です。これがデフォルトのモデルであり、model パラメータを設定したかどうかにかかわらず、すべての実行で spark-2 が使用されます。

spark-2 は、従来は Mini と Pro の選択が必要だった幅広いタスクに対応するため、精度とコストのトレードオフを考える必要はありません。

ハイライト:

• 実行あたりのコストを最小限に抑える
• 最速の実行時間
• 旧 Spark 1 フラッグシップに匹敵する精度
• 推論予算を備えた唯一のモデル: effort (low、medium、または high) を渡して、どの程度深く考えるかを制御できます

model パラメータは任意です。すべてのリクエストで spark-2 が実行されます。

• リサーチ: 「有望なAIスタートアップ上位5社とその資金調達額を調べる」
• 競合分析: 「SlackとMicrosoft Teamsの料金プランを比較する」
• データ収集: 「企業のWebサイトから連絡先情報を抽出する」
• コンテンツ要約: 「Webスクレイピングに関する最新のブログ記事を要約する」

Agent Playground は一括処理のための CSV アップロードに対応しています。CSV には 1 列以上の入力データを含めることができます。例えば、企業名だけの 1 列の CSV でもよいですし、企業名、プロダクト、Web サイトの URL など複数列を含めることもできます。各行は、エージェントが処理する 1 つのアイテムを表します。

CSV をアップロードし、グリッドヘッダーの「+」ボタンを使って出力列を追加します。各列にはそれぞれ専用のプロンプトがあり、列ヘッダーをクリックして、その項目でエージェントに何を見つけさせるかを記述します (例: 「CEO または創業者の名前」「累計調達額」) 。Run をクリックすると、エージェントは各行を並列に処理し、結果を入力します。

エージェントのジョブが失敗したり、想定外の結果が返ってきたりする場合は、エージェントによるデバッグに Ask API を使用してください。問題を説明すると、そのまま適用できる修正用パラメータ付きの検証済みの回答を取得できます。

curl -X POST https://api.firecrawl.dev/v2/support/ask \  -H "Authorization: Bearer fc-YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "question": "my agent returned incomplete results"  }'

詳細や連携例については、Ask ドキュメントをご覧ください。

詳しくは、Agent API Reference を参照してください。

フィードバックやサポートが必要な場合は、help@firecrawl.com までメールでご連絡ください。

Firecrawl Agent は、データ抽出リクエストの複雑さに応じてスケールする ダイナミックな課金モデル を採用しています。実際に Agent が行った処理内容に基づいて支払う仕組みのため、単純なデータポイントの抽出でも、複数のソースからの複雑な構造化情報の抽出でも、公平な料金になります。

Research Preview期間中、Agentの料金は動的でクレジットベースです：

• シンプルな抽出 (1ページからの連絡先情報など) は、通常必要なクレジット数が少なく、コストも低くなります
• 複雑なリサーチタスク (複数ドメインにわたる競合分析など) は、より多くのクレジットを使用しますが、必要な総工数を反映します
• 透明な利用状況により、各リクエストで消費されたクレジット数を正確に確認できます
• クレジット変換により、Agentのクレジット使用量が自動的にクレジットへ変換され、請求処理が容易になります

Spark-1 Fast で複数のエージェントを並列実行する場合、料金はセルあたり 10 クレジットとなり、より料金の見通しが立てやすくなります。

すべてのユーザーは、Agent の機能を無料で試せるように、プレイグラウンドまたは API のいずれからでも利用できる1 日あたり 5 回の無料実行が付与されます。

それ以上の利用分は、クレジット消費量に応じて課金され、その分がクレジットに換算されます。

エージェント は高コストになることがありますが、コストを下げる方法がいくつかあります:

• 無料実行から始める: 毎日 5 回の無料リクエストを使って料金感をつかむ
• maxCredits パラメータを設定する: 消費してもよいクレジットの最大数を設定して支出を制限します。ダッシュボードでは上限は 2,500 クレジットです。より高い上限を設定するには、API 経由で maxCredits パラメータを直接使用してください (注: 2,500 を超える値は常に有料リクエストとして課金されます)
• プロンプトを最適化する: より具体的なプロンプトほど、使用するクレジットが少なくなることが多い
• 大きなタスクを小さな実行に分割する: 1 回の エージェント 実行では、構造化データが約 150〜200 行返されます。大規模な抽出ジョブでは、カテゴリ、地域、または URL バッチ (1 回の実行あたり 3〜5 URL) ごとに分割し、結果を結合してください。これにより、各実行を maxCredits の上限より十分低く保つこともできます。
• 利用状況を監視する: ダッシュボードを通じて消費量を追跡する
• 期待値を設定する: 複数ドメインにわたる複雑なリサーチは、単純な単一ページの抽出よりも多くのクレジットを使用します

Try Agent now at firecrawl.dev/app/agent で今すぐ エージェント を試して、あなたの具体的なユースケースでクレジット使用量がどのようにスケールするかを確認してください。

Firecrawl API キーが必要な AI エージェント ですか? 自動オンボーディング手順については firecrawl.dev/agent-onboarding/SKILL.md を参照してください。