# 代理

> 从网络上的任意位置获取数据。

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

**选择合适的工具。** 当你**不知道 URL**，或需要在网页上进行自主导航时，代理就是正确的选择。

<ChooseDataExtractor />

Firecrawl `/agent` 是一个魔法般的 API，它可以在最广泛的网站范围内进行搜索、导航并收集数据，在难以触及的角落中找到数据，并以其他任何 API 都无法做到的方式发掘信息。它可以在几分钟内完成原本需要人类耗费数小时的工作——从端到端的数据采集，全程无需脚本或人工操作。
无论你只需要一个数据点，还是需要大规模的完整数据集，Firecrawl `/agent` 都能为你获取这些数据。

**把 `/agent` 想象成：无论数据藏在哪里，它都能替你做深度调研！**

<Info>
  **Research Preview**：代理目前处于早期访问阶段。可能会有不完善之处，但它会随着时间显著变好。
</Info>

<AgentFeedbackCTA src="docs-agent" />

代理构建于 `/extract` 的全部优势之上，并在此基础上更进一步：

* **无需提供 URL**：只需通过 `prompt` 参数描述你的需求，URL 是可选的。
* **深度网页搜索**：自主搜索并深入浏览站点以找到所需数据
* **可靠且准确**：适用于多种类型的查询和使用场景
* **更快**：并行处理多个数据源以更快返回结果

<PlaygroundCTA />

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

唯一必需的参数是 `prompt`。只需描述你想要提取的数据。要获得结构化输出，请提供一个 JSON schema。SDK 支持使用 Pydantic (Python) 和 Zod (Node) 来定义类型安全的 schema：

<CodeGroup>
  <AgentWithSchemaPython />

  <AgentWithSchemaJS />

  <AgentWithSchemaCURL />
</CodeGroup>

<div id="response">
  ### 响应
</div>

<AgentWithSchemaOutput />

<div id="providing-urls-optional">
  ## 提供 URL (可选) 
</div>

你可以选择提供 URL，让 agent 专注于特定页面：

<CodeGroup>
  <AgentWithURLsPython />

  <AgentWithURLsJS />

  <AgentWithURLsCURL />
</CodeGroup>

<div id="job-status-and-completion">
  ## 任务状态与完成
</div>

代理任务以异步方式运行。提交任务后，你会收到一个 Job ID，用于检查任务状态：

* **默认方式**：`agent()` 会阻塞等待，并返回最终结果
* **先启动再轮询**：使用 `start_agent` (Python) 或 `startAgent` (Node) 立即获取 Job ID，然后通过 `get_agent_status` / `getAgentStatus` 进行轮询
* **推送而非轮询**：启动任务时传入 `webhook`，即可在运行过程中及完成时接收[代理事件](/zh/webhooks/events#agent-events)

<Note>任务结果在完成后可通过 API 获取，保留 24 小时。在此之后，你仍然可以在 [activity logs](https://www.firecrawl.dev/app/logs) 中查看你的代理历史记录和结果。</Note>

<CodeGroup>
  <AgentStatusPython />

  <AgentStatusJS />

  <AgentStatusCURL />
</CodeGroup>

<div id="possible-states">
  ### 可能的状态
</div>

| 状态           | 描述                                               |
| ------------ | ------------------------------------------------ |
| `processing` | 代理仍在处理你的请求                                       |
| `completed`  | 提取已成功完成                                          |
| `failed`     | 提取过程中发生错误，或任务被取消 (被取消的任务会报告 `failed`，并附带取消错误消息)  |

<Note>
  **取消是协作式的。** 当你调用取消端点时，请求会立即登记，但任何已经在进行中的步骤 (如 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>

代理不会维持流式连接。既没有服务器发送事件流，也没有 WebSocket，因此你可以通过轮询执行追踪或接收 Webhook 来跟踪运行。

| 工具集     | 可获取内容                                                                                                                                            | 最适合                       |
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- |
| 执行追踪轮询  | 完整详情：截至目前运行发出的所有事件，包括工具调用、推理摘要、进度阶段和工件变更                                                                                                         | 构建自定义进度 UI，或调试运行实际执行了什么操作 |
| Webhook | 推送交付，粒度较粗：五个代理生命周期事件 (`agent.started`、`agent.action`、`agent.completed`、`agent.failed`、`agent.cancelled`) 。请参见 [webhook events](/zh/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` 引用代理的工作输出。使用快照端点可获取快照的完整内容：

<CodeGroup>
  <AgentSnapshotPython />

  <AgentSnapshotJS />

  <AgentSnapshotCURL />
</CodeGroup>

<Note>Spark 2 运行会记录执行追踪和快照，也就是说所有新运行都会记录；在 Spark 1 模型退役前启动的任务则不包含这些记录。有关完整的事件 schema，请参见[执行追踪](/zh/api-reference/endpoint/agent-trace)和[快照](/zh/api-reference/endpoint/agent-snapshot) API 参考；有关这些端点返回的失败情况，请参见 [代理错误](/zh/api-reference/errors#agent)目录。</Note>

<div id="getting-the-agents-source-data">
  ## 获取代理的源数据
</div>

运行会在执行过程中持续将工作输出写入工件。获取该运行的执行追踪后，即可检索这些工件。每个 `artifact.updated` 事件描述某个工件的一次变更：`artifact.kind` 可以是 `json`、`markdown`、`html`、`screenshot` 或 `text`，`artifact.path` 表示运行将其写入的位置，而 `artifact.snapshotId` 则是用于通过 `GET /agent/{jobId}/snapshots/{snapshotId}` 获取其内容的句柄。快照端点会在 `snapshot` 字段中以字符串形式返回该内容：对于 `json` 工件，该字符串经过 JSON 编码，需要解码；而 `markdown`、`html` 和 `text` 工件则直接返回内容本身。

要获取运行生成的页面内容，请先获取执行追踪，保留所需 `kind` 的 `artifact.updated` 事件，然后获取每个快照：

<CodeGroup>
  <AgentArtifactsPython />

  <AgentArtifactsJS />

  <AgentArtifactsCURL />
</CodeGroup>

在此基础上进行开发前，有两点需要了解：

* **工件是运行的输出，并非逐页存档。** 运行写入工件的内容取决于它如何处理你的 prompt，因此应将工件集视为该次运行生成的内容，而不是其打开的每个页面的完整记录。
* **其余内容位于工具结果中。** 每个 `tool_call.finished` 事件都包含一个 `result` 字段，其中保存该工具返回的内容；未成为工件的内容会出现在这里。

<div id="share-agent-runs">
  ## 分享代理运行记录
</div>

你可以直接在 Agent playground 中分享代理运行记录。共享链接是公开的，任何拥有链接的人都可以查看运行输出和活动；你也可以随时撤销访问权限以停用该链接。共享页面不会被搜索引擎收录。

<div id="model-selection">
  ## 模型选择
</div>

Firecrawl 代理使用 **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>

| 参数                      | 类型      | 必填    | 描述                                                                                                                                                                                                                                                         |
| ----------------------- | ------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `prompt`                | string  | **是** | 用自然语言描述你想要提取的数据 (最多 10,000 个字符)                                                                                                                                                                                                                            |
| `model`                 | string  | 否     | 默认使用 `spark-2`，所有运行均使用该模型。Spark 1 模型已弃用，并会路由至 `spark-2`                                                                                                                                                                                                    |
| `effort`                | string  | 否     | 推理预算：`low`、`medium` 或 `high`。所有运行均使用 `spark-2`，因此无论是否指定 `model`，都可以传入 `effort`                                                                                                                                                                             |
| `urls`                  | array   | 否     | 可选的 URL 列表，用于聚焦提取                                                                                                                                                                                                                                          |
| `schema`                | object  | 否     | 用于结构化输出的可选 JSON schema                                                                                                                                                                                                                                     |
| `strictConstrainToURLs` | boolean | 否     | 如果为 `true`，代理仅访问 `urls` array 中提供的 URL                                                                                                                                                                                                                     |
| `webhook`               | object  | 否     | 用于接收代理生命周期事件 (`agent.started`、`agent.action`、`agent.completed`、`agent.failed`、`agent.cancelled`) 的 Webhook。请参见 [webhook payloads](/zh/api-reference/endpoint/webhook-agent-started)                                                                           |
| `maxCredits`            | number  | 否     | 此代理任务中可花费的最大额度数。如果未设置，默认值为 **2,500**。Dashboard 最高支持 **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>

* **调研**: &quot;找出前 5 家 AI 初创公司及其融资金额&quot;
* **竞品分析**: &quot;比较 Slack 和 Microsoft Teams 的定价方案&quot;
* **数据收集**: &quot;从公司网站中提取联系方式&quot;
* **内容摘要**: &quot;总结关于网页抓取的最新博客文章&quot;

<div id="csv-upload-in-agent-playground">
  ## 在 Agent Playground 中上传 CSV
</div>

[Agent Playground](https://www.firecrawl.dev/app/agent) 支持通过上传 CSV 进行批量处理。你的 CSV 可以包含一列或多列输入数据。例如：一列公司名称，或者多列数据，如公司名称、产品和网站 URL。每一行都代表一个需要由 Agent 处理的条目。

上传你的 CSV，然后使用表头中的 &quot;+&quot; 按钮添加输出列。每一列都有自己的 prompt——点击列表头，描述 Agent 应为该字段查找什么内容 (例如，“CEO 或创始人姓名”、“融资总额”) 。点击 Run，Agent 会并行处理每一行并填充结果。

<div id="troubleshooting-with-ask">
  ## 使用 Ask 排查问题
</div>

如果你的代理任务失败或返回了异常结果，请使用 [Ask API](/zh/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 文档](/zh/features/ask)，了解完整详情和集成示例。

<div id="api-reference">
  ## API 参考
</div>

请参阅 [Agent API Reference](/zh/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 的计费是**动态的、基于 credit 的**：

* **简单抽取任务** (例如从单个页面提取联系方式) 通常消耗更少的 credits，成本更低
* **复杂研究任务** (例如对多个域名进行竞品分析) 会消耗更多 credits，但更能体现整体投入的工作量
* **用量透明**会清楚展示每个请求具体消耗了多少 credits
* **Credit 换算**会自动将 Agent 的 credit 使用量换算为 credits，便于计费

<Info>
  Credit 使用量会因 prompt 的复杂度、处理的数据量以及期望输出的结构而有所不同。大致来说，大多数 Agent 运行会消耗**数百个 credits**，更简单的单页任务可能会用得更少，而复杂的多域名研究可能会用得更多。
</Info>

<div id="parallel-agents-pricing">
  ### 并行 Agent 计费
</div>

如果你使用 Spark-1 Fast 并行运行多个 agent，费用会更加可预测：每个 cell 消耗 10 个积分。

<div id="getting-started">
  ### 入门
</div>

**所有用户**每天都会获得**5 次免费运行**，可以通过 playground 或 API 使用，用于在无需付费的情况下体验 Agent 的功能。

额外用量会根据 credit 消耗计费，并换算为 credits。

<div id="managing-costs">
  ### 成本管理
</div>

代理可能会比较昂贵，但有一些方法可以降低成本：

* **从免费运行开始**：利用你每天 5 次免费请求来了解定价
* **设置 `maxCredits` 参数**：通过设置你愿意花费的最大额度数来限制支出。Dashboard 将此上限设为 2,500 额度；若要设置更高的上限，请直接通过 API 使用 `maxCredits` 参数 (注意：高于 2,500 的值始终按付费请求计费)
* **优化 prompt**：更具体的 prompt 通常会消耗更少的额度
* **将大型任务拆分为更小的运行**：单次代理运行大约会返回 150-200 行结构化数据。对于大型提取任务，可按类别、地区或 URL 批次 (每次运行 3-5 个 URL) 进行拆分，再合并结果。这也能让每次运行都保持在 `maxCredits` 限制之下。
* **监控用量**：通过 Dashboard 追踪你的使用情况
* **设定预期**：跨多个站点/领域的复杂研究会比简单的单页提取消耗更多额度

现在访问 [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) 了解自动化引导说明。