> ## Documentation Index
> Fetch the complete documentation index at: https://student-213fb9fc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent

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

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

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

<Info>
  **Research Preview（研究プレビュー）**: Agent はアーリーアクセス段階です。動作が荒削りな部分がありますが、今後大きく改善されていきます。[フィードバックを共有する →](mailto:product@firecrawl.com)
</Info>

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-1-mini",
      maxCredits=100
  )

  print(result.data)
  ```

  ```js Node theme={null}
  import Firecrawl from '@mendable/firecrawl-js';
  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,
    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"]
      }
    }'
  ```
</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 '@mendable/firecrawl-js';

  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` でポーリングします

<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 '@mendable/firecrawl-js';

  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`     | 抽出中にエラーが発生しました     |

<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="model-selection">
  ## モデルの選択
</div>

Firecrawl Agent では 2 種類のモデルが利用できます。**Spark 1 Mini はコストが 60% 低く**、デフォルトモデルです。ほとんどのユースケースに最適です。複雑なタスクで最高レベルの精度が必要な場合は Spark 1 Pro にアップグレードしてください。

| Model          | Cost       | Accuracy | Best For         |
| -------------- | ---------- | -------- | ---------------- |
| `spark-1-mini` | **60% 安価** | 標準       | ほとんどのタスク（デフォルト）  |
| `spark-1-pro`  | 標準         | より高い     | 複雑なリサーチ、重要度の高い抽出 |

<Tip>
  **まずは Spark 1 Mini**（デフォルト）から始めてください。抽出タスクの大半を、コストを 60% 削減しながら問題なく処理できます。複数ドメインにまたがる複雑なリサーチや、精度が極めて重要な場合にのみ Pro に切り替えてください。
</Tip>

<div id="spark-1-mini-default">
  ### Spark 1 Mini（デフォルト）
</div>

`spark-1-mini` は効率的なモデルで、シンプルなデータ抽出タスクに最適です。

**Mini を使うのに適したケース:**

* 単純なデータ項目（連絡先情報、価格情報など）を抽出するとき
* 構造が整理された Web サイトを扱うとき
* コスト効率を重視するとき
* 大量の抽出ジョブを実行するとき

<div id="spark-1-pro">
  ### Spark 1 Pro
</div>

`spark-1-pro` は、複雑な抽出タスクで最大限の精度を発揮するよう設計された、当社のフラッグシップモデルです。

**次のような場合は Pro を使用してください:**

* 複雑な競合分析を行う場合
* 深い推論が必要なデータを抽出する場合
* 精度がユースケースにおいて極めて重要な場合
* あいまい、または取得が難しいデータを扱う場合

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

使用するモデルは、`model` パラメーターで指定します。

<CodeGroup>
  ```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 '@mendable/firecrawl-js';

  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"
    }'
  ```
</CodeGroup>

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

| パラメータ        | 型      | 必須      | 説明                                                                                                                   |
| ------------ | ------ | ------- | -------------------------------------------------------------------------------------------------------------------- |
| `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** になります。上限に達するとジョブは失敗し、**データは一切返されません** が、これまでの処理で消費されたクレジットは請求されます。 |

<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 アップロードに対応しています。入力データ（例: 企業名、URL、その他任意のエンティティ）を含む CSV をアップロードし、各行ごとにエージェントにどのようなデータを取得させたいかを説明するプロンプトを作成し、出力フィールドを定義して実行します。エージェントは各行を並列に処理し、結果を自動で入力します。

<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>

Agent の利用コストは高くなり得ますが、抑えるための方法がいくつかあります:

* **無料実行から始める**: 毎日 5 回の無料リクエストを使って料金イメージをつかむ
* **`maxCredits` パラメータを設定する**: 消費するクレジット数の上限を設定してコストを制限する
* **プロンプトを最適化する**: 具体的なプロンプトほど必要なクレジットが少なくなることが多い
* **利用状況を確認する**: ダッシュボードで利用量を追跡する
* **期待値を調整する**: 複数ドメインにまたがる複雑なリサーチは、単純な単一ページの抽出より多くのクレジットを使用する

[firecrawl.dev/app/agent](https://www.firecrawl.dev/app/agent) で今すぐ Agent を試して、あなたの具体的なユースケースでクレジット使用量がどのようにスケールするかを確認してください。

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