Agent

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

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

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

Research Preview: Agent はアーリーアクセス段階です。動作が荒削りな部分がありますが、今後大きく改善されていきます。

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

URL 不要: prompt パラメータで必要な内容を伝えるだけです。URL の指定は任意です
Deep Web Search: サイトの奥深くまで自律的に検索・移動して目的のデータを見つけ出します
信頼性と正確性: 幅広いクエリやユースケースに対応します
高速: 複数のソースを並列処理し、より早く結果を返します

Playground で試す

コードは不要で、インタラクティブな Playground 上でエージェントを試せます。

`/agent` の使用

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

from firecrawl import Firecrawl
from pydantic import BaseModel, Field
from typing import List, Optional

app = Firecrawl(api_key="fc-YOUR_API_KEY")

class Founder(BaseModel):
    name: str = Field(description="Full name of the founder")
    role: Optional[str] = Field(None, description="Role or position")
    background: Optional[str] = Field(None, description="Professional background")

class FoundersSchema(BaseModel):
    founders: List[Founder] = Field(description="List of founders")

result = app.agent(
    prompt="Find the founders of Firecrawl",
    schema=FoundersSchema,
    model="spark-2",
    max_credits=100
)

print(result.data)

import { Firecrawl } from 'firecrawl';
import { z } from 'zod';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

const result = await firecrawl.agent({
  prompt: "Find the founders of Firecrawl",
  schema: z.object({
    founders: z.array(z.object({
      name: z.string().describe("Full name of the founder"),
      role: z.string().describe("Role or position").optional(),
      background: z.string().describe("Professional background").optional()
    })).describe("List of founders")
  }),
  model: "spark-2",
  maxCredits: 100
});

console.log(result.data);

curl -X POST "https://api.firecrawl.dev/v2/agent" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find the founders of Firecrawl",
    "model": "spark-2",
    "maxCredits": 100,
    "schema": {
      "type": "object",
      "properties": {
        "founders": {
          "type": "array",
          "description": "List of founders",
          "items": {
            "type": "object",
            "properties": {
              "name": { "type": "string", "description": "Full name" },
              "role": { "type": "string", "description": "Role or position" },
              "background": { "type": "string", "description": "職歴" }
            },
            "required": ["name"]
          }
        }
      },
      "required": ["founders"]
    }
  }'

レスポンス

JSON

{
  "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 を指定する場合 (任意)

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

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

result = app.agent(
    urls=["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
    prompt="これらのページの機能と価格情報を比較してください"
)

print(result.data)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

const result = await firecrawl.agent({
  urls: ["https://docs.firecrawl.dev", "https://firecrawl.dev/pricing"],
  prompt: "Compare the features and pricing information from these pages"
});

console.log(result.data);

curl -X POST "https://api.firecrawl.dev/v2/agent" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://docs.firecrawl.dev",
      "https://firecrawl.dev/pricing"
    ],
    "prompt": "Compare the features and pricing information from these pages"
  }'

ジョブのステータスと完了

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

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

ジョブ結果は完了後 24 時間のあいだ API 経由で取得できます。この期間を過ぎても、activity logs から Agent の履歴と結果を参照できます。

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# エージェントジョブを開始する
agent_job = app.start_agent(
    prompt="Find the founders of Firecrawl"
)

# Check the status
status = app.get_agent_status(agent_job.id)

print(status)
# Example output:
# status='completed'
# success=True
# data={ ... }
# expires_at=datetime.datetime(...)
# credits_used=15

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

// エージェントジョブを開始
const started = await firecrawl.startAgent({
  prompt: "Find the founders of Firecrawl"
});

// 状態を確認
if (started.id) {
  const status = await firecrawl.getAgentStatus(started.id);
  console.log(status.status, status.data);
}

curl -X GET "https://api.firecrawl.dev/v2/agent/<jobId>" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

考えられるステータス

ステータス	説明
`processing`	エージェントがリクエストを処理中です
`completed`	抽出が正常に完了しました
`failed`	抽出中にエラーが発生したか、ジョブがキャンセルされました (キャンセルされたジョブは、キャンセルのエラーメッセージとともに `failed` を報告します)

キャンセルは協調的に処理されます。 cancel エンドポイントを呼び出すと、リクエストはただちに受け付けられますが、すでに進行中のステップ (LLM の推論ステップ、ツール呼び出し、またはブラウザ操作) は、ジョブが停止する前に、正常に停止できる区切りまで実行されます。その短い間もクレジットが引き続き加算される可能性があるため、最終的な creditsUsed は、キャンセルをクリックした時点で表示されていた値より大きくなる場合があります。キャンセルされたジョブは、ポーリング時にステータス failed を報告し、agent.cancelled webhook イベントを発行します。

保留状態の例

JSON

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

完成例

JSON

{
  "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 メソッドは自動ページネーションを行わないため、どこまで遡るかを制御できます。

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# 直近のエージェント実行を一覧表示する
page = app.list_agents()

for run in page.agents:
    print(run.id, run.status, run.target_hint)

# `next` のカーソルを使って次のページを取得する
if page.next:
    before = int(page.next.split("before=")[-1])
    older = app.list_agents(before=before)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

// 直近のエージェント実行を一覧表示
const page = await firecrawl.listAgents();

for (const run of page.agents ?? []) {
  console.log(run.id, run.status, run.targetHint);
}

// `next` のカーソルを使って次のページを取得
if (page.next) {
  const before = Number(new URL(page.next).searchParams.get("before"));
  const older = await firecrawl.listAgents({ before });
}

curl -X GET "https://api.firecrawl.dev/v2/agent" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

# 次のページを取得（前のページの `next` URL に含まれる Unix ミリ秒タイムスタンプを指定）
curl -X GET "https://api.firecrawl.dev/v2/agent?before=1756600000000" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

実行中の実行を追跡する

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

サーフェス	得られるもの	最適な用途
トレースのポーリング	詳細情報: ツール呼び出し、推論の要約、進行フェーズ、artifact の変更など、実行がこれまでに出力したすべてのイベント	独自の進行状況 UI の構築や、実行が実際に何をしたかのデバッグ
webhook	プッシュ配信 (大まかな粒度) : 5 種類のエージェントライフサイクルイベント (`agent.started`、`agent.action`、`agent.completed`、`agent.failed`、`agent.cancelled`) 。webhook イベントを参照	ポーリングループを維持せずに、実行の完了に対応する
ライブビュー	人間が確認できるエージェントのブラウザビュー。`?liveView=true` を指定してトレースをリクエストすると、`activeBrowserSessions` の各エントリに `liveViewUrl` が含まれます	実行のナビゲーションをリアルタイムで確認する

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

import time
from collections import defaultdict

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

agent_job = app.start_agent(prompt="Find the founders of Firecrawl")
seen = set()
finished = False
quiet_polls = 0

while True:
    trace = app.get_agent_trace(agent_job.id)

    # producer_sequence は発行元の agent ごとに単調増加するため、先にグループ化する。
    by_agent = defaultdict(list)
    for event in trace.events or []:
        by_agent[event.agent.id].append(event)

    new_events = 0
    for agent_id, events in by_agent.items():
        for event in sorted(events, key=lambda e: e.producer_sequence):
            if event.event_id not in seen:
                seen.add(event.event_id)
                new_events += 1
                print(agent_id, event.producer_sequence, event.type)

    if not finished:
        finished = app.get_agent_status(agent_job.id).status != "processing"
    elif new_events:
        quiet_polls = 0
    else:
        # 終了後の猶予期間: 実行完了後もしばらくイベントが届くことがある。
        quiet_polls += 1
        if quiet_polls == 3:
            break

    time.sleep(5)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

const started = await firecrawl.startAgent({ prompt: "Find the founders of Firecrawl" });
const seen = new Set();
let finished = false;
let quietPolls = 0;

for (;;) {
  const trace = await firecrawl.getAgentTrace(started.id);

  // producerSequence は発行元エージェントごとに単調増加するため、まずエージェント単位でグループ化する。
  const byAgent = new Map();
  for (const event of trace.events ?? []) {
    const bucket = byAgent.get(event.agent.id) ?? [];
    bucket.push(event);
    byAgent.set(event.agent.id, bucket);
  }

  let newEvents = 0;
  for (const [agentId, events] of byAgent) {
    for (const event of events.sort((a, b) => a.producerSequence - b.producerSequence)) {
      if (seen.has(event.eventId)) continue;
      seen.add(event.eventId);
      newEvents++;
      console.log(agentId, event.producerSequence, event.type);
    }
  }

  if (!finished) {
    finished = (await firecrawl.getAgentStatus(started.id)).status !== "processing";
  } else if (newEvents) {
    quietPolls = 0;
  } else {
    // 終端ウィンドウ: 実行完了後もしばらくの間イベントが届くことがある。
    if (++quietPolls === 3) break;
  }

  await new Promise((resolve) => setTimeout(resolve, 5000));
}

# 未取得のイベントのみを出力し、実行完了後も短い猶予期間の間は
# ポーリングを継続する。
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
: > "$tmp/seen.txt"
finished=0
quiet=0

while [ "$quiet" -lt 3 ]; do
  curl -s "https://api.firecrawl.dev/v2/agent/JOB_ID/trace" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  | jq -r '.events | group_by(.agent.id)[] | sort_by(.producerSequence)[]
           | "\(.eventId) \(.agent.id) \(.producerSequence) \(.type)"' > "$tmp/poll.txt"

  new=$(grep -vxF -f "$tmp/seen.txt" "$tmp/poll.txt")
  [ -n "$new" ] && echo "$new"
  cp "$tmp/poll.txt" "$tmp/seen.txt"

  if [ "$finished" = 0 ]; then
    status=$(curl -s "https://api.firecrawl.dev/v2/agent/JOB_ID" \
      -H "Authorization: Bearer $FIRECRAWL_API_KEY" | jq -r '.status')
    [ "$status" = "processing" ] || finished=1
  elif [ -n "$new" ]; then
    quiet=0
  else
    quiet=$((quiet + 1))
  fi

  sleep 5
done

実行トレースとスナップショット

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

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# 実行のトレース: 時系列順のイベント（tool calls、推論、生成物）
trace = app.get_agent_trace("JOB_ID")

for event in trace.events or []:
    print(event.type)

# 実行中の場合は、現在アクティブなブラウザセッションも含める
live = app.get_agent_trace("JOB_ID", live_view=True)
for session in live.active_browser_sessions or []:
    print(session.live_view_url)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

// 実行のトレース: 時系列順のイベント（tool calls、推論、成果物）
const trace = await firecrawl.getAgentTrace("JOB_ID");

for (const event of trace.events ?? []) {
  console.log(event.type);
}

// 実行中の場合は、現在アクティブなブラウザセッションも含める
const live = await firecrawl.getAgentTrace("JOB_ID", { liveView: true });
console.log(live.activeBrowserSessions);

curl "https://api.firecrawl.dev/v2/agent/JOB_ID/trace" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

# 実行中の場合、現在アクティブなブラウザセッションも含める
curl "https://api.firecrawl.dev/v2/agent/JOB_ID/trace?liveView=true" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

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

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# artifact.updated トレースイベントは snapshotId でスナップショットの内容を参照します
snapshot = app.get_agent_snapshot("JOB_ID", "SNAPSHOT_ID")

print(snapshot.snapshot)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

// artifact.updated トレースイベントは、snapshotId によってスナップショットの内容を参照します
const snapshot = await firecrawl.getAgentSnapshot("JOB_ID", "SNAPSHOT_ID");

console.log(snapshot.snapshot);

curl "https://api.firecrawl.dev/v2/agent/JOB_ID/snapshots/SNAPSHOT_ID" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

トレースとスナップショットは、すべての新規実行で使用されるSpark 2で記録されます。廃止前にSpark 1モデルで開始されたジョブには、これらはありません。完全なイベントスキーマについては、trace および snapshot のAPIリファレンスを参照し、これらのエンドポイントが返す失敗については Agent errors カタログを参照してください。

agent のソースデータを取得する

実行は処理の進行に応じて作業中の出力をアーティファクトに書き込みます。実行のトレースを取得すれば、これらを取得できます。各 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 イベントを抽出してから、各スナップショットを取得します。

import json

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

trace = app.get_agent_trace("JOB_ID")

for event in trace.events or []:
    if event.type != "artifact.updated":
        continue

    kind = event.artifact.kind
    if kind not in ("markdown", "html", "json"):
        continue

    snapshot = app.get_agent_snapshot("JOB_ID", event.artifact.snapshot_id)

    # markdown、html、text の snapshot は content そのもの。
    # json の snapshot は JSON エンコードされているのでデコードする。
    content = json.loads(snapshot.snapshot) if kind == "json" else snapshot.snapshot

    print(kind, event.artifact.path, content)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

const trace = await firecrawl.getAgentTrace("JOB_ID");

for (const event of trace.events ?? []) {
  if (event.type !== "artifact.updated") continue;

  const kind = event.artifact.kind;
  if (!["markdown", "html", "json"].includes(kind)) continue;

  const snapshot = await firecrawl.getAgentSnapshot("JOB_ID", event.artifact.snapshotId);

  // markdown、html、text の snapshot はコンテンツそのもの。
  // json の snapshot は JSON エンコードされているのでデコードが必要。
  const content = kind === "json" ? JSON.parse(snapshot.snapshot) : snapshot.snapshot;

  console.log(kind, event.artifact.path, content);
}

# 実行で書き出された markdown、html、json のアーティファクトをすべて取得します。
curl -s "https://api.firecrawl.dev/v2/agent/JOB_ID/trace" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
| jq -r '.events[]
         | select(.type == "artifact.updated")
         | select(.artifact.kind == "markdown" or .artifact.kind == "html" or .artifact.kind == "json")
         | "\(.artifact.kind) \(.artifact.snapshotId)"' \
| while read -r kind snapshot_id; do
    body=$(curl -s "https://api.firecrawl.dev/v2/agent/JOB_ID/snapshots/$snapshot_id" \
      -H "Authorization: Bearer $FIRECRAWL_API_KEY")

    # markdown と html のスナップショットはコンテンツそのもの、json は JSON エンコードされています。
    if [ "$kind" = "json" ]; then
      printf '%s' "$body" | jq -r '.snapshot | fromjson'
    else
      printf '%s' "$body" | jq -r '.snapshot'
    fi
  done

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

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

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

モデルの選択

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

Spark 1 モデルは非推奨です。 Spark 1 のモデル名は後方互換性のため引き続き使用できますが、これらを指定したリクエストは spark-2 にルーティングされます。

Spark 2

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

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

モデルの指定

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

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# Spark 2がデフォルト — すべての実行はこのモデルで処理されます
result = app.agent(
    prompt="Find the pricing of Firecrawl",
    model="spark-2"
)

# 非推奨: Spark 1のモデル名も引き続き利用できますが、"spark-2"にルーティングされます。

print(result.data)

import { Firecrawl } from 'firecrawl';

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" });

// Spark 2がデフォルト — すべての実行はこのモデルで動作します
const result = await firecrawl.agent({
  prompt: "Find the pricing of Firecrawl",
  model: "spark-2"
});

// 非推奨: Spark 1のモデル名も引き続き指定できますが、"spark-2"にルーティングされます。

console.log(result.data);

# Spark 2 がデフォルト — すべての実行はこのモデルで処理されます
curl -X POST "https://api.firecrawl.dev/v2/agent" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Find the pricing of Firecrawl",
    "model": "spark-2"
  }'

# 非推奨: Spark 1 のモデル名も引き続き指定できますが、"spark-2" にルーティングされます。

利用規約への同意が必要なデータプロバイダー

Agent は実行中に Alexandria のデータプロバイダーを呼び出せますが、対象となるのは Team がデータ利用規約に同意済みのプロバイダーのみです。規約に同意していないプロバイダーは、exchange.onTermsRequired の設定にかかわらず呼び出されません。実行は利用可能なプロバイダーで継続され、スキップされたプロバイダーはステータスのレスポンスで確認できます。自動同意モードはありません。プロバイダーの規約への同意には、必ず人による承諾が必要です。承諾はダッシュボードで行うか、ユーザーが明示的に同意した後にアプリケーションから terms/accept を呼び出して行います。Firecrawl 上にエージェントを構築する場合、そのエージェントは terms/accept を呼び出す前に必ずユーザーの確認を得る必要があります。データをリクエストしただけでは、プロバイダーの規約に同意したことにはなりません。

`onTermsRequired`	動作
`skip`(デフォルト)	実行は同意済みのプロバイダーのみを使って回答し、ブロックされることはありません。`exchange.skippedProviders` には、回答に役立った可能性がある、規約同意が必要なプロバイダーが一覧表示されます。
`ask`	`skip` と同じ動作に加え、実行は `exchange.requiresAction` と `kind: "terms"` の `pendingApproval` を返して終了します。これにより、ユーザーに確認して規約に同意したうえで、スレッドを続行できます。

スレッドの後続ターンで onTermsRequired を省略した場合、前のターンの値が引き継がれます。ターンが有料呼び出しの承認(requireApproval)で終了した場合、規約同意の提示は含まれません。

レスポンスフィールド

以下のフィールドは、GET /v2/agent/{id} の exchange オブジェクトに含まれます。

skippedProviders(全モード):利用できていれば役立ったはずの、利用規約への同意が必要なプロバイダーごとに 1 件ずつエントリが含まれます。各エントリには provider、name、capability、adds(追加されるはずだった内容)、reason: "terms_required"、version(利用規約のバージョン)、termsUrl(ダッシュボード上の同意ページ)が含まれます。
requiresAction(ask のみ):type: "accept_terms"、approvalId、providers リストが含まれます。approvalId は常に含まれ、スレッドを続行する際に回答する、保留中の terms 承認の ID を表します。各プロバイダーには、実行すべき show(terms/show)と accept(terms/accept)の呼び出し内容がそのまま含まれます。各プロバイダーの digest(および accept.options.digest)は常に含まれますが、値が null になる場合があります。これはカタログがダイジェストを公開していないことを示します。その場合は、まず terms/show を実行し、返されたダイジェストを送信してください。

{
  "status": "completed",
  "exchange": {
    "enabled": true,
    "onTermsRequired": "ask",
    "paidCalls": 0,
    "creditsUsed": null,
    "skippedProviders": [
      {
        "provider": "apollo",
        "name": "Apollo",
        "capability": "people/search",
        "adds": "verified work emails and direct phone numbers",
        "reason": "terms_required",
        "version": "F-1.0.0",
        "termsUrl": "https://www.firecrawl.dev/app/alexandria/apollo"
      }
    ],
    "requiresAction": {
      "type": "accept_terms",
      "approvalId": "0199aaaa-0000-7000-8000-000000000000",
      "providers": [
        {
          "provider": "apollo",
          "name": "Apollo",
          "capability": "people/search",
          "version": "F-1.0.0",
          "digest": "<sha256>",
          "url": "https://www.firecrawl.dev/app/alexandria/apollo",
          "show": { "provider": "firecrawl", "capability": "terms/show", "options": { "provider": "apollo" } },
          "accept": {
            "provider": "firecrawl",
            "capability": "terms/accept",
            "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "<sha256>", "confirmed": true }
          }
        }
      ]
    }
  },
  "pendingApproval": {
    "id": "0199aaaa-0000-7000-8000-000000000000",
    "kind": "terms",
    "reason": "Apollo could add verified work emails and direct phone numbers.",
    "calls": [],
    "terms": [{ "provider": "apollo", "name": "Apollo", "version": "F-1.0.0", "digest": "<sha256>", "url": "https://www.firecrawl.dev/app/alexandria/apollo" }],
    "resolution": null
  }
}

同意してから続行する

ask モードの場合:

ユーザーに利用規約を提示します。alexandria を指定し、/v2/scrape 経由でプロバイダーの show 呼び出しを実行します。
ユーザーが明示的に同意した場合にのみ、同じ方法で accept 呼び出しを実行します。accept.options.digest が null の場合は、terms/show が返したダイジェストを使用します:

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alexandria": {
      "provider": "firecrawl",
      "capability": "terms/accept",
      "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "<sha256>", "confirmed": true }
    }
  }'

exchange.approve で同じスレッドを続行します。オファーは一括で承認され、callIds と always は無視されます。次のターンでは、すべてを再実行するのではなく、これらのプロバイダーを使って、前回の回答で指摘された不足部分を補います。

curl -X POST https://api.firecrawl.dev/v2/agent \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "<threadId from the previous run>",
    "prompt": "Continue with Apollo.",
    "exchange": {
      "approve": { "approvalId": "0199aaaa-0000-7000-8000-000000000000" }
    }
  }'

プロバイダーを使わずに先へ進める場合は、代わりに exchange.decline: { "approvalId": "..." } で続行します。この操作ではオファー全体が拒否され、そのオファーに含まれるプロバイダーは、以降そのスレッド内で再び提示されることはありません。 skip モードでは、応答すべき保留中の承認はありません。規約に同意した後、新しい実行 (またはスレッドの新しいターン) を開始すると、そのプロバイダーを利用できるようになります。

パラメータ

パラメータ	Type	Required	Description
`prompt`	string	Yes	抽出したいデータを自然言語で記述した文字列 (最大 10,000 文字)
`model`	string	No	すべての実行で使用されるモデル `spark-2` がデフォルトです。Spark 1 モデルは非推奨であり、`spark-2` にルーティングされます
`effort`	string	No	推論予算: `low`、`medium`、または `high`。すべての実行は `spark-2` で行われるため、`effort` は `model` の有無にかかわらず送信できます
`urls`	array	No	抽出対象を絞り込むための任意の URL リスト
`schema`	object	No	構造化された出力のための任意の JSON スキーマ
`strictConstrainToURLs`	boolean	No	`true` の場合、エージェントは `urls` 配列で指定された URL のみを訪問します
`webhook`	object	No	エージェントのライフサイクルイベント (`agent.started`、`agent.action`、`agent.completed`、`agent.failed`、`agent.cancelled`) を受信する webhook。webhook ペイロードを参照してください
`maxCredits`	number	No	このエージェントタスクで使用するクレジットの最大数。設定しない場合、デフォルトは 2,500 です。ダッシュボードでは 2,500 までの値をサポートしています。これを超える上限を設定するには、API 経由で `maxCredits` を指定してください (2,500 を超える値は常に有料リクエストとして扱われます)。上限に達するとジョブは失敗し、データは一切返されません。失敗した実行には課金されません。AI の推論に使用されたクレジットは失敗時には請求されず、実行中のツール呼び出し (`scraping`、`search`、`mapping` など) に使用されたクレジットは返還され、レスポンスには `creditsUsed: 0` が記録されます。
`exchange.onTermsRequired`	string	No	エージェントが使用する Alexandria データプロバイダーが、Team でまだ同意していない利用規約への同意を必要とする場合の動作: `skip` (デフォルト) または `ask`。利用規約への同意が必要なデータプロバイダーを参照してください

Agent と Extract：何が改善されたか

項目	Agent (新)	Extract
URL の指定	不要	必要
速度	高速	標準
コスト	低コスト	標準
信頼性	高い	標準
クエリの柔軟性	高い	中程度

利用例

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

Agent Playground での CSV アップロード

Agent Playground は一括処理のための CSV アップロードに対応しています。CSV には 1 列以上の入力データを含めることができます。例えば、企業名だけの 1 列の CSV でもよいですし、企業名、プロダクト、Web サイトの URL など複数列を含めることもできます。各行は、エージェントが処理する 1 つのアイテムを表します。 CSV をアップロードし、グリッドヘッダーの「+」ボタンを使って出力列を追加します。各列にはそれぞれ専用のプロンプトがあり、列ヘッダーをクリックして、その項目でエージェントに何を見つけさせるかを記述します (例: 「CEO または創業者の名前」「累計調達額」) 。Run をクリックすると、エージェントは各行を並列に処理し、結果を入力します。

Ask を使ったトラブルシューティング

エージェントのジョブが失敗したり、想定外の結果が返ってきたりする場合は、エージェントによるデバッグに 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 ドキュメントをご覧ください。

APIリファレンス

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

料金

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

Agentの料金の仕組み

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

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

クレジット使用量は、プロンプトの複雑さ、処理されるデータ量、および要求された出力構造に応じて変動します。目安として、ほとんどのAgent実行では数百クレジットが消費されますが、よりシンプルな単一ページのタスクでは少なく、複数ドメインにまたがる複雑なリサーチでは多くなる場合があります。

Parallel Agents の料金

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 で今すぐエージェントを試して、あなたの具体的なユースケースでクレジット使用量がどのようにスケールするかを確認してください。

料金は Research Preview から一般提供へ移行する際に変更される可能性があります。現在のユーザーには、料金変更がある場合は事前に通知されます。

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

はじめに

主要エンドポイント

その他

クイックスタート

開発者ガイド

webhook

ユースケース

その他

貢献

Playground で試す

`/agent` の使用

レスポンス

URL を指定する場合 (任意)

ジョブのステータスと完了

考えられるステータス

保留状態の例

完成例

エージェント実行の一覧取得

実行中の実行を追跡する

実行トレースとスナップショット

agent のソースデータを取得する

モデルの選択

Spark 2

モデルの指定

利用規約への同意が必要なデータプロバイダー

レスポンスフィールド

同意してから続行する

パラメータ

Agent と Extract：何が改善されたか

利用例

Agent Playground での CSV アップロード

Ask を使ったトラブルシューティング

APIリファレンス

料金

Agentの料金の仕組み

Parallel Agents の料金

はじめに

コスト管理

Playground で試す

​/agent の使用

​レスポンス

​URL を指定する場合 (任意)

​ジョブのステータスと完了

​考えられるステータス

​保留状態の例

​完成例

​エージェント実行の一覧取得

​実行中の 実行 を追跡する

​実行トレースとスナップショット

​agent のソースデータを取得する

​エージェントの実行を共有する

​モデルの選択

​Spark 2

​モデルの指定

​利用規約への同意が必要なデータプロバイダー

​レスポンスフィールド

​同意してから続行する

​パラメータ

​Agent と Extract：何が改善されたか

​利用例

​Agent Playground での CSV アップロード

​Ask を使ったトラブルシューティング

​APIリファレンス

​料金

​Agentの料金の仕組み

​Parallel Agents の料金

​はじめに

​コスト管理

`/agent` の使用

レスポンス

URL を指定する場合 (任意)

ジョブのステータスと完了

考えられるステータス

保留状態の例

完成例

エージェント実行の一覧取得

実行中の実行を追跡する

実行トレースとスナップショット

agent のソースデータを取得する

エージェントの実行を共有する

モデルの選択

Spark 2

モデルの指定

利用規約への同意が必要なデータプロバイダー

レスポンスフィールド

同意してから続行する

パラメータ

Agent と Extract：何が改善されたか

利用例

Agent Playground での CSV アップロード

Ask を使ったトラブルシューティング

APIリファレンス

料金

Agentの料金の仕組み

Parallel Agents の料金

はじめに

コスト管理