代理

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

• 对于单个已知 URL，/scrape 的 JSON 模式成本更低，而且是同步的。
• 完整对比见：选择数据提取器。

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

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

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

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

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

{  "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，让 agent 专注于特定页面：

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

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

{  "success": true,  "status": "processing",  "expiresAt": "2024-12-15T00:00:00.000Z"}

{  "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}

GET /agent 会列出团队创建的所有代理运行记录，按最新优先排序——包括通过 playground 或 API 启动的运行记录。每条记录包含运行 ID、创建时间、状态、简短的目标提示，以及启动时使用的选项。

结果按固定每页 20 条运行记录分页。当有更多页面时，响应中会包含 next URL；传入其中的 before 时间戳即可获取下一页。SDK 方法不会自动分页，因此你可以自行控制要追溯到多早的记录。

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

如果要自行排序执行追踪事件，请先按 agent.id 分组：producerSequence 对每个发出事件的代理而言都是单调递增的，因此全局排序会错误地交错编排器及其子代理的事件。终止事件 run.finished 发出后，事件仍可能在短时间内到达，因此在渲染最终状态前，请在短暂的尾部窗口内继续轮询。

每次运行都会记录一份规范的执行追踪，其中按顺序包含工具调用、推理摘要、进度更新、浏览器会话和输出工件变更等事件。可获取该执行追踪以调试运行，或为实时进度 UI 提供数据：

artifact.updated 执行追踪事件通过 snapshotId 引用代理的工作输出。使用快照端点可获取快照的完整内容：

运行会在执行过程中持续将工作输出写入工件。获取该运行的执行追踪后，即可检索这些工件。每个 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 事件，然后获取每个快照：

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

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

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

Firecrawl 代理使用 Spark 2，相比早期的 Spark 1 模型成本更低、速度更快，准确率相当。它是默认值：无论是否设置 model 参数，每次运行都会使用 spark-2。

spark-2 覆盖了此前需要在 Mini 和 Pro 之间取舍的全部任务，因此无需再权衡准确率与成本。

亮点：

• 单次运行成本最低
• 运行时间最快
• 准确率可媲美之前的 Spark 1 旗舰模型
• 唯一支持推理预算的模型：传入 effort (low、medium 或 high) 以控制其思考深度

model 参数可选——每个请求都会运行 spark-2：

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

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

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

如果你的代理任务失败或返回了异常结果，请使用 Ask API 进行代理式调试。描述问题，即可获取经过验证的答案以及可直接应用的修复参数：

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 文档，了解完整详情和集成示例。

请参阅 Agent API Reference 以了解更多详情。

有反馈或需要帮助？请发送邮件至 help@firecrawl.com。

Firecrawl Agent 使用 动态计费 模式，费用会随你的数据提取请求复杂度而变化。你根据 Agent 实际完成的工作量付费，无论是提取简单的数据点，还是从多个来源获取复杂的结构化信息，都能享受公平的定价。

在 Research Preview 阶段，Agent 的计费是动态的、基于 credit 的：

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

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

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

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

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

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

现在访问 firecrawl.dev/app/agent 试用代理，看看在你的具体用例下额度的使用如何随规模变化。

你是需要 Firecrawl API 密钥的 AI 代理吗？请参阅 firecrawl.dev/agent-onboarding/SKILL.md 了解自动化引导说明。