Agent 自主数据收集
Agent 自主数据收集
学习目标
- 理解
/v2/agent端点的代理架构 - 掌握双模型策略（Spark Mini vs Pro）的选择依据
- 了解信用额度管理与 Zero Data Retention 限制
前置知识
本章涉及 Web 数据收集 Agent 的通用架构，建议先阅读：
下文聚焦 Firecrawl 的具体实现。
项目实践
端点代理架构
/v2/agent 端点本身不执行 Agent 逻辑，而是作为代理层将请求转发到内部 Agent 服务（EXTRACT_V3_BETA_URL）：
/v2/agent Controller ↓认证 / 限流 / 信用检查 ↓请求参数校验 (agentRequestSchema) ↓内部转发到 Agent 服务 ↓返回 jobId (用于轮询状态)控制器代码简洁，核心职责是：
- 验证 API Key 和团队权限
- 消耗免费请求额度（或走付费通道）
- 将请求透传到内部 Agent 服务
- 返回异步任务 ID
信用额度管理
Agent 任务的信用管理采用预检查 + 分类路由：
maxCredits > 2500？ ↓ 是 ↓ 否直接走付费通道 检查免费额度（不消耗免费次数） ↓ 有免费额度？ ↓ 是 ↓ 否 消耗免费 走付费关键实现：agent_consume_free_request_if_left 是一个 Supabase RPC 函数，原子性地检查并消耗免费额度。这避免了并发请求导致超额消费。
双模型策略
Firecrawl 的 Agent 使用自研的 Spark 模型系列：
| 模型 | 成本 | 适用场景 |
|---|---|---|
spark-1-mini | 60% 更低 | 单网站数据提取、简单查询 |
spark-1-pro | 标准成本 | 跨网站对比、复杂导航、高准确率要求 |
用户在请求中通过 model 字段指定。默认使用 spark-1-mini。
官方建议的 Pro 使用场景：
- 跨多个网站对比数据
- 需要穿透复杂导航或认证的页面
- 需要探索多条路径的研究任务
- 关键数据场景（准确率优先）
Zero Data Retention 限制
Agent 端点明确不支持 ZDR 模式。在控制器中直接拦截：
if getScrapeZDR(flags) === "forced": return 400, "Your team has zero data retention enabled. This is not supported on extract."原因：Agent 需要在中间步骤暂存抓取结果和浏览器会话状态，多步骤任务需要上下文传递，与 ZDR 的”不保留任何中间数据”原则冲突。
问题与规避
1. 异步任务轮询
Agent 返回的是 jobId，需要轮询 /v2/agent/:jobId 获取结果。SDK 会自动处理轮询，但直接使用 REST API 时需要手动实现。
规避：使用官方 SDK（Python / Node.js），SDK 的 app.agent() 方法自动轮询直到完成。
2. 免费额度耗尽
每个团队有有限的免费 Agent 请求次数。额度耗尽后，请求自动走付费通道（按信用计费）。
规避：监控 /v2/team/credit-usage 端点了解剩余额度。
3. Agent 准确性不可控
Agent 自主决定搜索和导航策略，对于同一 prompt 可能返回不同结果。
规避：
- 使用
spark-1-pro模型提高准确性 - 提供
urls参数限定搜索范围 - 使用
schema参数约束输出格式
设计取舍
为什么用代理架构而非内联执行？
Agent 服务运行在独立的 EXTRACT_V3_BETA_URL 上，而非 API 进程内。好处：
- 资源隔离：Agent 任务可能长时间运行（30-60 秒），不阻塞 API 进程
- 独立扩缩容：Agent 服务可以根据需求独立扩展
- 故障隔离：Agent 服务崩溃不影响基础 API（Scrape/Crawl）
代价是增加了一层网络跳转和复杂度。
为什么 Agent 不支持 ZDR？
ZDR 模式要求不保留任何中间数据，但 Agent 的工作流涉及多个步骤，每个步骤都需要暂存中间结果（抓取页面、提取数据、分析比较）。完全不留存意味着每个步骤需要重新抓取，大幅增加成本和延迟。