> ## Documentation Index
> Fetch the complete documentation index at: https://firecrawl-fix-js-response-syntax-highlighting.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 选择数据提取工具

> 对比 /agent、/extract 和 /scrape（JSON 模式），为结构化数据提取选择合适的工具

Firecrawl 提供三种从网页提取结构化数据的方式。它们分别适用于不同的使用场景，在自动化程度和可控性上各不相同。

<div id="quick-comparison">
  ## 快速对比
</div>

| 功能              | `/agent`            | `/extract`                   | `/scrape` (JSON 模式)                |
| --------------- | ------------------- | ---------------------------- | ---------------------------------- |
| **状态**          | 已启用                 | 请改用 `/agent`                 | 已启用                                |
| **是否需要 URL**    | 否 (可选)              | 是 (支持通配符)                    | 是 (单一 URL)                         |
| **范围**          | 全网范围发现              | 多页面/多域名                      | 单页面                                |
| **URL 发现**      | 自动进行全网搜索            | 从给定 URL 进行爬取                 | 无                                  |
| **处理方式**        | 异步                  | 异步                           | 同步                                 |
| **是否需要 Schema** | 否 (prompt 或 schema) | 否 (prompt 或 schema)          | 否 (prompt 或 schema)                |
| **计费**          | 动态计费 (每天 5 次免费运行)   | 基于 token (1 额度 = 15 个 token) | 5 额度/页 (1 额度基础费用 + JSON 模式额外 4 额度) |
| **最适合**         | 调研、发现、复杂信息收集        | 多页面抽取 (在已知 URL 的情况下)         | 已知单页面抽取                            |

<div id="1-agent-endpoint">
  ## 1. `/agent` 端点
</div>

`/agent` 端点是 Firecrawl 最先进的功能，是 `/extract` 的后继者。它使用 AI 代理自主在全网进行搜索、导航和数据采集。

<div id="key-characteristics">
  ### 关键特性
</div>

* **URL 可选**：只需通过 `prompt` 描述你的需求；URL 完全可选
* **自主导航**：代理会自动搜索并深入浏览站点来找到你的数据
* **深度网页搜索**：自主在多个域名和页面间发现所需信息
* **并行处理**：同时处理多个数据源以提升返回速度
* **可用模型**：`spark-1-mini` (默认，成本低 60%) 和 `spark-1-pro` (精度更高)

<div id="example">
  ### 示例
</div>

<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="专业背景")

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

<div id="best-use-case-autonomous-research-discovery">
  ### 最佳用例：自主研究与探索
</div>

**场景**：你需要查找关于获得 A 轮融资的 AI 初创公司的信息，包括其创始人及融资金额。

**为什么用 `/agent`**：你不知道从哪些网站可以获取这些信息。`agent` 会自主在网上搜索，访问相关来源 (Crunchbase、新闻网站、公司页面) ，并为你整理结构化数据。

更多详情请参见 [Agent 文档](/zh/features/agent)。

***

<div id="2-extract-endpoint">
  ## 2. `/extract` 端点
</div>

<Note>
  **请改用 `/agent`**：我们建议迁移到 [`/agent`](/zh/features/agent)——它更快、更可靠、无需提供 URL，并且能覆盖所有 `/extract` 的用例并支持更多场景。
</Note>

`/extract` 端点使用基于 LLM 的提取能力，从指定的 URL 或整个域名中收集结构化数据。

<div id="key-characteristics">
  ### 关键特性
</div>

* **通常需要提供 URL**：至少提供一个 URL (支持通配符，如 `example.com/*`)
* **域级爬取**：可以爬取并解析在某个域名下发现的所有 URL
* **网页搜索增强**：可选参数 `enableWebSearch`，用于跟踪指定域名之外的链接
* **可选 Schema**：同时支持严格的 JSON schema 或自然语言提示词
* **异步处理**：返回用于状态查询的任务 ID

<div id="the-url-limitation">
  ### URL 限制
</div>

`/extract` 的核心问题在于，你通常需要提前知道 URL：

1. **发现缺口**：对于类似“找出 YC W24 公司”这样的任务，你并不知道哪些 URL 包含所需数据。你需要在调用 `/extract` 之前先单独执行一次搜索。
2. **笨拙的网页搜索**：虽然有 `enableWebSearch`，但它只能从你提供的 URL 开始——对于以发现为主的任务来说，这个流程非常别扭。
3. **`/agent` 被创建的原因**：`/extract` 很擅长从已知位置抽取数据，但在“先发现数据在哪里”这方面就没那么有效。

<div id="example">
  ### 示例
</div>

<CodeGroup>
  ```python Python theme={null}
  from firecrawl import Firecrawl

  firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

  schema = {
      "type": "object",
      "properties": {"description": {"type": "string"}},
      "required": ["description"],
  }

  res = firecrawl.extract(
      urls=["https://docs.firecrawl.dev"],
      prompt="提取该页面的描述",
      schema=schema,
  )

  print(res.data["description"])
  ```

  ```js Node theme={null}
  import { Firecrawl } from 'firecrawl';

  const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

  const schema = {
    type: 'object',
    properties: {
      title: { type: 'string' }
    },
    required: ['title']
  };

  const res = await firecrawl.extract({
    urls: ['https://docs.firecrawl.dev'],
    prompt: 'Extract the page title',
    schema,
    scrapeOptions: { formats: [{ type: 'json', prompt: 'Extract', schema }] }
  });

  console.log(res.status || res.success, res.data);
  ```

  ```bash cURL theme={null}
  curl -s -X POST "https://api.firecrawl.dev/v2/extract" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "urls": ["https://docs.firecrawl.dev"],
      "prompt": "提取页面标题",
      "schema": {
        "type": "object",
        "properties": {"title": {"type": "string"}},
        "required": ["title"]
      },
      "scrapeOptions": {
        "formats": [{"type": "json", "prompt": "提取", "schema": {"type": "object"}}]
      }
    }'
  ```
</CodeGroup>

<div id="best-use-case-targeted-multi-page-extraction">
  ### 最佳使用场景：有针对性的多页面提取
</div>

**场景**：你有竞争对手的文档 URL，想从 `docs.competitor.com/*` 中提取出他们所有的 API 端点。

**为什么这里使用 `/extract` 很合适**：你已经知道确切的域名。但即便如此，如今在提供 URL 的前提下，`/agent` 通常会得到更好的效果。

更多详情，请参阅 [Extract 文档](/zh/features/extract)。

***

<div id="3-scrape-endpoint-with-json-mode">
  ## 3. 使用 JSON 模式的 `/scrape` 端点
</div>

使用 JSON 模式的 `/scrape` 端点是可控性最高的方案——它使用 LLM 将页面内容解析为你指定的 schema，从单个已知 URL 中提取结构化数据。

<div id="key-characteristics">
  ### 关键特性
</div>

* **仅支持单个 URL**：用于一次仅从一个特定页面提取数据
* **必须提供精确 URL**：必须明确包含数据的精确 URL
* **Schema 可选**：可以使用 JSON schema，或仅提供 prompt (由 LLM 决定结构)
* **同步**：立即返回数据 (无需轮询任务状态)
* **额外 formats**：可以在一次请求中同时获取 JSON 抽取结果以及 markdown、HTML、截图等

<div id="example">
  ### 示例
</div>

<CodeGroup>
  ```python Python theme={null}
  from firecrawl import Firecrawl
  from pydantic import BaseModel

  app = Firecrawl(api_key="fc-YOUR-API-KEY")

  class CompanyInfo(BaseModel):
      company_mission: str
      supports_sso: bool
      is_open_source: bool
      is_in_yc: bool

  result = app.scrape(
      'https://firecrawl.dev',
      formats=[{
        "type": "json",
        "schema": CompanyInfo.model_json_schema()
      }],
      only_main_content=False,
      timeout=120000
  )

  print(result)
  ```

  ```js Node theme={null}
  import { Firecrawl } from "firecrawl";
  import { z } from "zod";

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

  // 定义用于提取内容的模式
  const schema = z.object({
    company_mission: z.string(),
    supports_sso: z.boolean(),
    is_open_source: z.boolean(),
    is_in_yc: z.boolean()
  });

  const result = await app.scrape("https://firecrawl.dev", {
    formats: [{
      type: "json",
      schema: schema
    }],
  });

  console.log(result);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.firecrawl.dev/v2/scrape \
      -H 'Content-Type: application/json' \
      -H 'Authorization: Bearer YOUR_API_KEY' \
      -d '{
        "url": "https://firecrawl.dev",
        "formats": [ {
          "type": "json",
          "schema": {
            "type": "object",
            "properties": {
              "company_mission": {
                        "type": "string"
              },
              "supports_sso": {
                        "type": "boolean"
              },
              "is_open_source": {
                        "type": "boolean"
              },
              "is_in_yc": {
                        "type": "boolean"
              }
            },
            "required": [
              "company_mission",
              "supports_sso",
              "is_open_source",
              "is_in_yc"
            ]
          }
        } ]
      }'
  ```
</CodeGroup>

<div id="best-use-case-single-page-precision-extraction">
  ### 最佳适用场景：单页精确抽取
</div>

**场景**：你在构建一个价格监控工具，需要从已知 URL 的特定产品页面中抽取价格、库存状态和产品详情。

**为什么使用 `/scrape` 搭配 JSON 模式**：你确切知道哪个页面包含所需数据，需要对单页进行精确抽取，并且希望同步返回结果，而不想处理任务管理的开销。

更多详情请参阅 [JSON 模式文档](/zh/features/llm-extract)。

***

<div id="decision-guide">
  ## 决策指南
</div>

**您是否知道包含数据的确切 URL?**

* **否** → 使用 `/agent`(自主网页发现)
* **是**
  * **单个页面?** → 使用 `/scrape` 配合 JSON 模式
  * **多个页面?** → 使用 `/agent` 配合 URL (或使用 `/scrape` 配合批量处理)

<div id="recommendations-by-scenario">
  ### 按场景推荐
</div>

| 场景                         | 推荐使用的 Endpoint      |
| -------------------------- | ------------------- |
| 「查找所有 AI 初创公司及其融资情况」       | `/agent`            |
| 「从这个特定的产品页面中提取数据」          | `/scrape` (JSON 模式) |
| 「获取 competitor.com 上的所有博文」 | `/agent` 配合 URL     |
| 「监控多个已知 URL 的价格变化」         | `/scrape` 配合批量处理    |
| 「调研某一特定行业的公司」              | `/agent`            |
| 「从 50 个已知公司页面中提取联系信息」      | `/scrape` 配合批量处理    |

***

<div id="pricing">
  ## 价格
</div>

| 端点                  | 费用                                | 备注                 |
| ------------------- | --------------------------------- | ------------------ |
| `/scrape` (JSON 模式) | 5 额度/页 (1 基础 + 4 个 JSON 模式)       | 固定且可预测             |
| `/extract`          | 按 Token 计费 (1 credit = 15 tokens) | 随内容变化              |
| `/agent`            | 动态计费                              | 每天可免费运行 5 次；视复杂度而定 |

<div id="example-find-the-founders-of-firecrawl">
  ### 示例：“查找 Firecrawl 的创始人”
</div>

| Endpoint   | 工作方式                              | 消耗积分            |
| ---------- | --------------------------------- | --------------- |
| `/scrape`  | 你先手动找到 URL，然后抓取 1 个页面             | 约 1 个积分         |
| `/extract` | 你提供一个或多个 URL，即可抽取结构化数据            | 可变 (按 token 计费) |
| `/agent`   | 只需发送提示词 (prompt) ——agent 会自动发现并抽取 | 约 100–500 个积分   |

**取舍**：`/scrape` 成本最低，但需要你事先知道 URL。`/agent` 成本更高，但会自动完成网址发现。

有关详细定价，请参见 [Firecrawl Pricing](https://firecrawl.dev/pricing)。

***

<div id="migration-extract-agent">
  ## 迁移：`/extract` → `/agent`
</div>

如果你当前正在使用 `/extract` 接口，迁移过程非常简单：

**迁移前 (使用 `/extract`) ：**

```python theme={null}
result = app.extract(
    urls=["https://example.com/*"],
    prompt="提取产品信息",
    schema=schema
)
```

**之后 (使用 Agent) ：**

```python theme={null}
result = app.agent(
    urls=["https://example.com"],  # 可选 - 可完全省略
    prompt="Extract product information from example.com",
    schema=schema,
    model="spark-1-mini"  # 或使用 "spark-1-pro" 获得更高准确度
)
```

关键优势在于：使用 `/agent` 时，你甚至可以省略 URL，只需描述你的需求。

***

<div id="key-takeaways">
  ## 关键要点
</div>

1. **已经知道精确 URL？** 使用 `/scrape` 搭配 JSON 模式——这是最便宜 (5 额度/页面) 、最快 (同步) 、且最可预测的选项。

2. **需要自动化调研？** 使用 `/agent`——它会自动完成信息发现，每天有 5 次免费运行，之后根据复杂度动态计费。

3. **将 `/extract` 迁移** 到用于新项目的 `/agent`——`/agent` 是功能更强的继任方案。

4. **成本与便利性的权衡**：当你已经知道 URL 时，`/scrape` 性价比最高；`/agent` 成本更高，但免去了手动发现 URL 的工作。

***

<div id="further-reading">
  ## 延伸阅读
</div>

* [Agent 文档](/zh/features/agent)
* [Agent 模型](/zh/features/models)
* [JSON 模式文档](/zh/features/llm-extract)
* [Extract 文档](/zh/features/extract)
* [批量抓取](/zh/features/batch-scrape)