> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-claude-eager-dijkstra-lr4978.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent

> Web 上のあらゆる場所に存在するデータを収集します。

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

* **単一の既知のURL**に対しては、[`/scrape` のJSONモード](/ja/features/llm-extract) の方が低コストで、同期的に実行できます。
* 詳しい比較: [Data Extractor の選び方](/ja/developer-guides/usage-guides/choosing-the-data-extractor)。

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

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

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

<div className="firecrawl-cta-box">
  <div style={{ display: "flex", alignItems: "flex-start", gap: "8px", marginBottom: "8px" }}>
    <Icon icon="sack-dollar" color="#ff4d00" size={22} />

    <div className="firecrawl-cta-title" style={{ margin: 0 }}>
      <span style={{ color: "#ff4d00" }}>報奨金：5,000クレジット</span>
      <span style={{ fontWeight: 400 }}> — /agentに関する有益なフィードバックに対して</span>
    </div>
  </div>

  <p className="firecrawl-cta-description">
    対象となるには、Firecrawl Feedback Assistantとの内容の濃いインタビュー (よく考えられた具体的なユースケースなど) を完了してください。所要時間は数分で、いつでも中断でき、人間にもエージェントにも対応しています (リンクをエージェント用harnessに貼り付けるだけです！) 。/agentを使ったことがない方のご意見も歓迎します。
  </p>

  <a href="https://www.firecrawl.dev/survey/7pjb4?src=docs-agent" className="firecrawl-cta-btn-primary firecrawl-cta-btn-inline">
    インタビューを開始
  </a>

  <p className="firecrawl-cta-description" style={{ fontSize: "12px", fontStyle: "italic", margin: "12px 0 0 0" }}>
    報奨の対象となるにはメールアドレスを入力してください。インタビューは毎週末に品質を確認します。
  </p>
</div>

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

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

<Card title="Playground で試す" icon="play" href="https://www.firecrawl.dev/agent">
  コードは不要で、インタラクティブな Playground 上でエージェントを試せます。
</Card>

<div id="using-agent">
  ## `/agent` の使用
</div>

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```js Node theme={null}
  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);
  ```

  ```bash cURL theme={null}
  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"]
      }
    }'
  ```
</CodeGroup>

<div id="response">
  ### レスポンス
</div>

```json JSON theme={null}
{
  "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
}
```

<div id="providing-urls-optional">
  ## URL を指定する場合 (任意)
</div>

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```js Node theme={null}
  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);
  ```

  ```bash cURL theme={null}
  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"
    }'
  ```
</CodeGroup>

<div id="job-status-and-completion">
  ## ジョブのステータスと完了
</div>

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

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

<Note>ジョブ結果は完了後 24 時間のあいだ API 経由で取得できます。この期間を過ぎても、[activity logs](https://www.firecrawl.dev/app/logs) から Agent の履歴と結果を参照できます。</Note>

<CodeGroup>
  ```python Python theme={null}
  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
  ```

  ```js Node theme={null}
  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);
  }
  ```

  ```bash cURL theme={null}
  curl -X GET "https://api.firecrawl.dev/v2/agent/<jobId>" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY"
  ```
</CodeGroup>

<div id="possible-states">
  ### 考えられるステータス
</div>

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

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

<div id="pending-example">
  #### 保留状態の例
</div>

```json JSON theme={null}
{
  "success": true,
  "status": "processing",
  "expiresAt": "2024-12-15T00:00:00.000Z"
}
```

<div id="completed-example">
  #### 完成例
</div>

```json JSON theme={null}
{
  "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
}
```

<div id="listing-agent-runs">
  ## エージェント実行の一覧取得
</div>

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

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```js Node theme={null}
  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 });
  }
  ```

  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

<div id="following-a-run-in-progress">
  ## 実行中の 実行 を追跡する
</div>

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

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

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```js Node theme={null}
  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));
  }
  ```

  ```bash cURL theme={null}
  # 未取得のイベントのみを出力し、実行完了後も短い猶予期間の間は
  # ポーリングを継続する。
  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
  ```
</CodeGroup>

<div id="execution-traces-and-snapshots">
  ## 実行トレースとスナップショット
</div>

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```js Node theme={null}
  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);
  ```

  ```bash cURL theme={null}
  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"
  ```
</CodeGroup>

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```js Node theme={null}
  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);
  ```

  ```bash cURL theme={null}
  curl "https://api.firecrawl.dev/v2/agent/JOB_ID/snapshots/SNAPSHOT_ID" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY"
  ```
</CodeGroup>

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

<div id="getting-the-agents-source-data">
  ## agent のソースデータを取得する
</div>

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```js Node theme={null}
  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);
  }
  ```

  ```bash cURL theme={null}
  # 実行で書き出された 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
  ```
</CodeGroup>

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

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

<div id="share-agent-runs">
  ## エージェントの実行を共有する
</div>

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

<div id="model-selection">
  ## モデルの選択
</div>

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

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

<div id="spark-2">
  ### Spark 2
</div>

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

**ハイライト:**

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

<div id="specifying-a-model">
  ### モデルの指定
</div>

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

  ```js Node theme={null}
  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);
  ```

  ```bash cURL theme={null}
  # 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" にルーティングされます。
  ```
</CodeGroup>

<div id="parameters">
  ## パラメータ
</div>

| パラメータ                   | 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 ペイロード](/ja/api-reference/endpoint/webhook-agent-started)を参照してください                                                                                                                                                        |
| `maxCredits`            | number  | No       | このエージェントタスクで使用するクレジットの最大数。設定しない場合、デフォルトは **2,500** です。ダッシュボードでは **2,500** までの値をサポートしています。これを超える上限を設定するには、API 経由で `maxCredits` を指定してください (2,500 を超える値は常に有料リクエストとして扱われます)。上限に達するとジョブは失敗し、**データは一切返されません**。失敗した実行には課金されません。AI の推論に使用されたクレジットは失敗時には請求されず、実行中のツール呼び出し (`scraping`、`search`、`mapping` など) に使用されたクレジットは返還され、レスポンスには `creditsUsed: 0` が記録されます。 |

<div id="agent-vs-extract-whats-improved">
  ## Agent と Extract：何が改善されたか
</div>

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

<div id="example-use-cases">
  ## 利用例
</div>

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

<div id="csv-upload-in-agent-playground">
  ## Agent Playground での CSV アップロード
</div>

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

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

<div id="troubleshooting-with-ask">
  ## Ask を使ったトラブルシューティング
</div>

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

```bash theme={null}
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 ドキュメント](/ja/features/ask)をご覧ください。

<div id="api-reference">
  ## APIリファレンス
</div>

詳しくは、[Agent API Reference](/ja/api-reference/endpoint/agent) を参照してください。

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

<div id="pricing">
  ## 料金
</div>

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

<div id="how-agent-pricing-works">
  ### Agentの料金の仕組み
</div>

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

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

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

<div id="parallel-agents-pricing">
  ### Parallel Agents の料金
</div>

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

<div id="getting-started">
  ### はじめに
</div>

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

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

<div id="managing-costs">
  ### コスト管理
</div>

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

* **無料実行から始める**: 毎日 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](https://www.firecrawl.dev/app/agent) で今すぐ エージェント を試して、あなたの具体的なユースケースでクレジット使用量がどのようにスケールするかを確認してください。

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

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