> ## Documentation Index > Fetch the complete documentation index at: https://docs.firecrawl.dev/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` は、あらゆる場所にあるデータに対する「ディープリサーチ」と考えてください！** **Research Preview **: Agent はアーリーアクセス段階です。動作が荒削りな部分がありますが、今後大きく改善されていきます。[フィードバックを共有する →](mailto:product@firecrawl.com) Agent は `/extract` の優れた点をすべて引き継ぎつつ、さらに強化しています: * **URL 不要**: 必要な内容を `prompt` パラメータで記述するだけでよく、URL は任意です * **ディープ Web 検索**: サイト内を自律的に検索・巡回し、必要なデータを深部まで探索 * **高い信頼性と正確性**: 幅広い種類のクエリやユースケースで安定して動作 * **高速**: 複数ソースを並列処理して結果を素早く取得 コードは不要で、インタラクティブな Playground 上でエージェントを試せます。
## `/agent` の使用
必須パラメータは `prompt` のみです。どのようなデータを抽出したいかを記述してください。構造化された出力を得るには、JSON スキーマを指定してください。各 SDK は、型安全なスキーマ定義のために Pydantic (Python) と Zod (Node) をサポートしています： ```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-1-mini", 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-1-mini", 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-1-mini", "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 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 } ```
## URL を指定する場合 (任意)
エージェントの対象を特定のページに絞り込むために、任意で URL を指定できます。 ```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" }' ```
## ジョブのステータスと完了
Agent ジョブは非同期で実行されます。ジョブの実行を開始すると、ステータス確認に使える Job ID が返されます： * **デフォルトの方法**: `agent()` が完了まで待機し、最終結果を返します * **開始してポーリング**: `start_agent` (Python) または `startAgent` (Node) で即座に Job ID を取得し、その後 `get_agent_status` / `getAgentStatus` でポーリングします ジョブ結果は完了後 24 時間のあいだ API 経由で取得できます。この期間を過ぎても、[activity logs](https://www.firecrawl.dev/app/logs) から Agent の履歴と結果を参照できます。 ```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/" \ -H "Authorization: Bearer $FIRECRAWL_API_KEY" ```
### 考えられるステータス
| ステータス | 説明 | | ------------ | ---------------------- | | `processing` | エージェントがリクエストを処理中です | | `completed` | 抽出が正常に完了しました | | `failed` | 抽出中にエラーが発生しました | | `cancelled` | ジョブはユーザーによってキャンセルされました | **キャンセルは協調的に処理されます。** cancel エンドポイントを呼び出すと、リクエストはただちに受け付けられますが、すでに進行中のステップ (LLM の推論ステップ、ツール呼び出し、またはブラウザ操作) は、ジョブが `cancelled` に移行する前に、正常に停止できる区切りまで実行されます。その短い間もクレジットが引き続き加算される可能性があるため、最終的な `creditsUsed` は、キャンセルをクリックした時点で表示されていた値より大きくなる場合があります。
#### 保留状態の例
```json JSON theme={null} { "success": true, "status": "processing", "expiresAt": "2024-12-15T00:00:00.000Z" } ```
#### 完成例
```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 } ```
## エージェントの実行を共有する
Agent playground から、エージェントの実行を直接共有できます。共有リンクは公開されるため、リンクを知っている人なら誰でも実行結果とアクティビティを閲覧できます。また、アクセスを取り消してリンクをいつでも無効にできます。共有ページは検索エンジンにインデックスされません。
## モデルの選択
Firecrawl Agent では 2 種類のモデルが利用できます。**Spark 1 Mini はコストが 60% 低く**、デフォルトモデルです。ほとんどのユースケースに最適です。複雑なタスクで最高レベルの精度が必要な場合は Spark 1 Pro にアップグレードしてください。 | Model | Cost | Accuracy | Best For | | -------------- | ---------- | -------- | ---------------- | | `spark-1-mini` | **60% 安価** | 標準 | ほとんどのタスク (デフォルト) | | `spark-1-pro` | 標準 | より高い | 複雑なリサーチ、重要度の高い抽出 | **まずは Spark 1 Mini** (デフォルト) から始めてください。抽出タスクの大半を、コストを 60% 削減しながら問題なく処理できます。複数ドメインにまたがる複雑なリサーチや、精度が極めて重要な場合にのみ Pro に切り替えてください。
### Spark 1 Mini (デフォルト)
`spark-1-mini` は効率的なモデルで、シンプルなデータ抽出タスクに最適です。 **Mini を使うのに適したケース:** * 単純なデータ項目 (連絡先情報、価格情報など) を抽出するとき * 構造が整理された Web サイトを扱うとき * コスト効率を重視するとき * 大量の抽出ジョブを実行するとき
### Spark 1 Pro
`spark-1-pro` は、複雑な抽出タスクで最大限の精度を発揮するよう設計された、当社のフラッグシップモデルです。 **次のような場合は Pro を使用してください:** * 複雑な競合分析を行う場合 * 深い推論が必要なデータを抽出する場合 * 精度がユースケースにおいて極めて重要な場合 * あいまい、または取得が難しいデータを扱う場合
### モデルの指定
使用するモデルは、`model` パラメーターで指定します。 ```python Python theme={null} from firecrawl import Firecrawl app = Firecrawl(api_key="fc-YOUR_API_KEY") # Spark 1 Miniを使用(デフォルト - 省略可) result = app.agent( prompt="Find the pricing of Firecrawl", model="spark-1-mini" ) # Using Spark 1 Pro for complex tasks result = app.agent( prompt="Compare all enterprise features and pricing across Firecrawl, Apify, and ScrapingBee", model="spark-1-pro" ) print(result.data) ``` ```js Node theme={null} import { Firecrawl } from 'firecrawl'; const firecrawl = new Firecrawl({ apiKey: "fc-YOUR_API_KEY" }); // Spark 1 Miniを使用(デフォルト - 省略可) const result = await firecrawl.agent({ prompt: "Find the pricing of Firecrawl", model: "spark-1-mini" }); // 複雑なタスクにSpark 1 Proを使用 const resultPro = await firecrawl.agent({ prompt: "Compare all enterprise features and pricing across Firecrawl, Apify, and ScrapingBee", model: "spark-1-pro" }); console.log(result.data); ``` ```bash cURL theme={null} # Using Spark 1 Mini (default) 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-1-mini" }' # 複雑なタスクに Spark 1 Pro を使用 curl -X POST "https://api.firecrawl.dev/v2/agent" \ -H "Authorization: Bearer $FIRECRAWL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "prompt": "Compare all enterprise features and pricing across Firecrawl, Apify, and ScrapingBee", "model": "spark-1-pro" }' ```
## パラメータ
| Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `prompt` | string | **Yes** | 抽出したいデータを自然言語で記述した文字列 (最大 10,000 文字) | | `model` | string | No | 使用するモデル: `spark-1-mini` (デフォルト) または `spark-1-pro` | | `urls` | array | No | 抽出対象を絞り込むための任意の URL リスト | | `schema` | object | No | 構造化された出力のための任意の JSON スキーマ | | `maxCredits` | number | No | このエージェントタスクで使用するクレジットの最大数。設定しない場合、デフォルトは **2,500** です。ダッシュボードでは **2,500** までの値をサポートしています。これを超える上限を設定するには、API 経由で `maxCredits` を指定してください (2,500 を超える値は常に有料リクエストとして扱われます)。上限に達するとジョブは失敗し、**データは一切返されません**。失敗した実行には課金されません。AI の推論に使用されたクレジットは失敗時には請求されず、実行中のツール呼び出し (`scraping`、`search`、`mapping` など) に使用されたクレジットは返還され、レスポンスには `creditsUsed: 0` が記録されます。 |
## Agent と Extract：何が改善されたか
| 項目 | Agent (新) | Extract | | ------- | --------- | ------- | | URL の指定 | 不要 | 必要 | | 速度 | 高速 | 標準 | | コスト | 低コスト | 標準 | | 信頼性 | 高い | 標準 | | クエリの柔軟性 | 高い | 中程度 |
## 利用例
* **リサーチ**: 「有望なAIスタートアップ上位5社とその資金調達額を調べる」 * **競合分析**: 「SlackとMicrosoft Teamsの料金プランを比較する」 * **データ収集**: 「企業のWebサイトから連絡先情報を抽出する」 * **コンテンツ要約**: 「Webスクレイピングに関する最新のブログ記事を要約する」
## Agent Playground での CSV アップロード
[Agent Playground](https://www.firecrawl.dev/app/agent) は一括処理のための CSV アップロードに対応しています。CSV には 1 列以上の入力データを含めることができます。例えば、企業名だけの 1 列の CSV でもよいですし、企業名、プロダクト、Web サイトの URL など複数列を含めることもできます。各行は、エージェントが処理する 1 つのアイテムを表します。 CSV をアップロードし、グリッドヘッダーの「+」ボタンを使って出力列を追加します。各列にはそれぞれ専用のプロンプトがあり、列ヘッダーをクリックして、その項目でエージェントに何を見つけさせるかを記述します (例: 「CEO または創業者の名前」「累計調達額」) 。Run をクリックすると、エージェントは各行を並列に処理し、結果を入力します。
## Ask を使ったトラブルシューティング
エージェントのジョブが失敗したり、想定外の結果が返ってきたりする場合は、エージェントによるデバッグに [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)をご覧ください。
## APIリファレンス
詳しくは、[Agent API Reference](/ja/api-reference/endpoint/agent) を参照してください。 フィードバックやサポートが必要な場合は、[help@firecrawl.com](mailto: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](https://www.firecrawl.dev/app/agent) で今すぐ エージェント を試して、あなたの具体的なユースケースでクレジット使用量がどのようにスケールするかを確認してください。 料金は Research Preview から一般提供へ移行する際に変更される可能性があります。現在のユーザーには、料金変更がある場合は事前に通知されます。 > Firecrawl API キーが必要な AI エージェント ですか? 自動オンボーディング手順については [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) を参照してください。