# Agent

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

import AgentPython from "/snippets/ja/v2/agent/base/python.mdx";
import AgentJS from "/snippets/ja/v2/agent/base/js.mdx";
import AgentCURL from "/snippets/ja/v2/agent/base/curl.mdx";
import AgentOutput from "/snippets/ja/v2/agent/base/output.mdx";
import AgentWithSchemaPython from "/snippets/ja/v2/agent/with-schema/python.mdx";
import AgentWithSchemaJS from "/snippets/ja/v2/agent/with-schema/js.mdx";
import AgentWithSchemaCURL from "/snippets/ja/v2/agent/with-schema/curl.mdx";
import AgentWithSchemaOutput from "/snippets/ja/v2/agent/with-schema/output.mdx";
import AgentWithURLsPython from "/snippets/ja/v2/agent/with-urls/python.mdx";
import AgentWithURLsJS from "/snippets/ja/v2/agent/with-urls/js.mdx";
import AgentWithURLsCURL from "/snippets/ja/v2/agent/with-urls/curl.mdx";
import AgentStatusPython from "/snippets/ja/v2/agent/status/python.mdx";
import AgentStatusJS from "/snippets/ja/v2/agent/status/js.mdx";
import AgentStatusCURL from "/snippets/ja/v2/agent/status/curl.mdx";
import AgentListPython from "/snippets/ja/v2/agent/list/python.mdx";
import AgentListJS from "/snippets/ja/v2/agent/list/js.mdx";
import AgentListCURL from "/snippets/ja/v2/agent/list/curl.mdx";
import AgentStatusPending from "/snippets/ja/v2/agent/status/pending.mdx";
import AgentStatusCompleted from "/snippets/ja/v2/agent/status/completed.mdx";
import AgentWithModelPython from "/snippets/ja/v2/agent/with-model/python.mdx";
import AgentWithModelJS from "/snippets/ja/v2/agent/with-model/js.mdx";
import AgentWithModelCURL from "/snippets/ja/v2/agent/with-model/curl.mdx";
import AgentTracePython from "/snippets/ja/v2/agent/trace/python.mdx";
import AgentTraceJS from "/snippets/ja/v2/agent/trace/js.mdx";
import AgentTraceCURL from "/snippets/ja/v2/agent/trace/curl.mdx";
import AgentSnapshotPython from "/snippets/ja/v2/agent/snapshot/python.mdx";
import AgentSnapshotJS from "/snippets/ja/v2/agent/snapshot/js.mdx";
import AgentSnapshotCURL from "/snippets/ja/v2/agent/snapshot/curl.mdx";
import AgentTracePollPython from "/snippets/ja/v2/agent/trace/poll/python.mdx";
import AgentTracePollJS from "/snippets/ja/v2/agent/trace/poll/js.mdx";
import AgentTracePollCURL from "/snippets/ja/v2/agent/trace/poll/curl.mdx";
import AgentArtifactsPython from "/snippets/ja/v2/agent/artifacts/python.mdx";
import AgentArtifactsJS from "/snippets/ja/v2/agent/artifacts/js.mdx";
import AgentArtifactsCURL from "/snippets/ja/v2/agent/artifacts/curl.mdx";
import PlaygroundCTA from "/snippets/ja/shared/playground-cta-agent.mdx";
import ChooseDataExtractor from "/snippets/ja/shared/choose-data-extractor/from-agent.mdx";
import AgentFeedbackCTA from "/snippets/ja/agent-feedback-cta.mdx";

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

<ChooseDataExtractor />

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

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

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

<AgentFeedbackCTA src="docs-agent" />

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

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

<PlaygroundCTA />

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

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

<CodeGroup>
  <AgentWithSchemaPython />

  <AgentWithSchemaJS />

  <AgentWithSchemaCURL />
</CodeGroup>

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

<AgentWithSchemaOutput />

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

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

<CodeGroup>
  <AgentWithURLsPython />

  <AgentWithURLsJS />

  <AgentWithURLsCURL />
</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>
  <AgentStatusPython />

  <AgentStatusJS />

  <AgentStatusCURL />
</CodeGroup>

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

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

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

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

<AgentStatusPending />

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

<AgentStatusCompleted />

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

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

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

<CodeGroup>
  <AgentListPython />

  <AgentListJS />

  <AgentListCURL />
</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>
  <AgentTracePollPython />

  <AgentTracePollJS />

  <AgentTracePollCURL />
</CodeGroup>

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

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

<CodeGroup>
  <AgentTracePython />

  <AgentTraceJS />

  <AgentTraceCURL />
</CodeGroup>

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

<CodeGroup>
  <AgentSnapshotPython />

  <AgentSnapshotJS />

  <AgentSnapshotCURL />
</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>
  <AgentArtifactsPython />

  <AgentArtifactsJS />

  <AgentArtifactsCURL />
</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>
  <AgentWithModelPython />

  <AgentWithModelJS />

  <AgentWithModelCURL />
</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
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) を参照してください。