代理 | Firecrawl

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

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

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

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

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

无需 URL：只需通过 prompt 参数描述你的需求即可，URL 是可选的
深度网页搜索：自主搜索并深入站点内部，找到你所需的数据
可靠且准确：适用于各种各样的查询与用例
更快速：并行处理多个来源，更快得到结果

在 Playground 中体验

在交互式 Playground 中测试该 Agent，无需编写代码。

使用 `/agent`

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

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-2",
    max_credits=100
)

print(result.data)

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-2",
  maxCredits: 100
});

console.log(result.data);

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-2",
    "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"]
    }
  }'

响应

JSON

{
  "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 (可选)

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

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)

import { Firecrawl } from 'firecrawl';

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

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

任务状态与完成

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

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

任务结果在完成后可通过 API 获取，保留 24 小时。在此之后，你仍然可以在 activity logs 中查看你的代理历史记录和结果。

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# 启动一个 Agent 任务
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

import { Firecrawl } from 'firecrawl';

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

// 启动一个 Agent 任务
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);
}

curl -X GET "https://api.firecrawl.dev/v2/agent/<jobId>" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

可能的状态

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

取消是协作式的。 当你调用取消端点时，请求会立即登记，但任何已经在进行中的步骤 (如 LLM 推理步骤、工具调用或浏览器操作) 都会先运行到可安全停止的节点，然后任务才会停止。在这段短暂时间内，额度仍可能继续累积，因此最终的 creditsUsed 可能高于你点击取消时显示的数值。被取消的任务在轮询时会报告状态 failed，并触发 agent.cancelled Webhook 事件。

等待中示例

JSON

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

已完成示例

JSON

{
  "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 方法不会自动分页，因此你可以自行控制要追溯到多早的记录。

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# 列出最近的代理运行记录
page = app.list_agents()

for run in page.agents:
    print(run.id, run.status, run.target_hint)

# 使用 `next` 中的游标获取下一页
if page.next:
    before = int(page.next.split("before=")[-1])
    older = app.list_agents(before=before)

import { Firecrawl } from 'firecrawl';

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

// 列出最近的代理运行记录
const page = await firecrawl.listAgents();

for (const run of page.agents ?? []) {
  console.log(run.id, run.status, run.targetHint);
}

// 使用 `next` 中的游标获取下一页
if (page.next) {
  const before = Number(new URL(page.next).searchParams.get("before"));
  const older = await firecrawl.listAgents({ before });
}

curl -X GET "https://api.firecrawl.dev/v2/agent" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

# 获取下一页（取上一页 `next` URL 中的 Unix 毫秒时间戳）
curl -X GET "https://api.firecrawl.dev/v2/agent?before=1756600000000" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

跟踪正在进行的运行

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

工具集	可获取内容	最适合
执行追踪轮询	完整详情：截至目前运行发出的所有事件，包括工具调用、推理摘要、进度阶段和工件变更	构建自定义进度 UI，或调试运行实际执行了什么操作
Webhook	推送交付，粒度较粗：五个代理生命周期事件 (`agent.started`、`agent.action`、`agent.completed`、`agent.failed`、`agent.cancelled`) 。请参见 webhook events	无需持续运行轮询循环即可响应运行完成
实时视图	可供人工查看的代理浏览器视图。请求执行追踪时添加 `?liveView=true`，`activeBrowserSessions` 中的每个条目都会包含 `liveViewUrl`	实时观察运行的导航过程

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

import time
from collections import defaultdict

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

agent_job = app.start_agent(prompt="Find the founders of Firecrawl")
seen = set()
finished = False
quiet_polls = 0

while True:
    trace = app.get_agent_trace(agent_job.id)

    # producer_sequence 仅在同一个发出事件的代理内单调递增，因此先按代理分组。
    by_agent = defaultdict(list)
    for event in trace.events or []:
        by_agent[event.agent.id].append(event)

    new_events = 0
    for agent_id, events in by_agent.items():
        for event in sorted(events, key=lambda e: e.producer_sequence):
            if event.event_id not in seen:
                seen.add(event.event_id)
                new_events += 1
                print(agent_id, event.producer_sequence, event.type)

    if not finished:
        finished = app.get_agent_status(agent_job.id).status != "processing"
    elif new_events:
        quiet_polls = 0
    else:
        # 尾部窗口：运行结束后的短时间内仍可能有事件到达。
        quiet_polls += 1
        if quiet_polls == 3:
            break

    time.sleep(5)

import { Firecrawl } from 'firecrawl';

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

const started = await firecrawl.startAgent({ prompt: "Find the founders of Firecrawl" });
const seen = new Set();
let finished = false;
let quietPolls = 0;

for (;;) {
  const trace = await firecrawl.getAgentTrace(started.id);

  // producerSequence 仅在同一个发出事件的代理内单调递增，因此先按代理分组。
  const byAgent = new Map();
  for (const event of trace.events ?? []) {
    const bucket = byAgent.get(event.agent.id) ?? [];
    bucket.push(event);
    byAgent.set(event.agent.id, bucket);
  }

  let newEvents = 0;
  for (const [agentId, events] of byAgent) {
    for (const event of events.sort((a, b) => a.producerSequence - b.producerSequence)) {
      if (seen.has(event.eventId)) continue;
      seen.add(event.eventId);
      newEvents++;
      console.log(agentId, event.producerSequence, event.type);
    }
  }

  if (!finished) {
    finished = (await firecrawl.getAgentStatus(started.id)).status !== "processing";
  } else if (newEvents) {
    quietPolls = 0;
  } else {
    // 收尾窗口：运行结束后的短时间内仍可能有事件到达。
    if (++quietPolls === 3) break;
  }

  await new Promise((resolve) => setTimeout(resolve, 5000));
}

# 仅打印尚未见过的事件，并在运行结束后继续轮询一小段
# 收尾时间窗口。
tmp=$(mktemp -d)
trap 'rm -rf "$tmp"' EXIT
: > "$tmp/seen.txt"
finished=0
quiet=0

while [ "$quiet" -lt 3 ]; do
  curl -s "https://api.firecrawl.dev/v2/agent/JOB_ID/trace" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  | jq -r '.events | group_by(.agent.id)[] | sort_by(.producerSequence)[]
           | "\(.eventId) \(.agent.id) \(.producerSequence) \(.type)"' > "$tmp/poll.txt"

  new=$(grep -vxF -f "$tmp/seen.txt" "$tmp/poll.txt")
  [ -n "$new" ] && echo "$new"
  cp "$tmp/poll.txt" "$tmp/seen.txt"

  if [ "$finished" = 0 ]; then
    status=$(curl -s "https://api.firecrawl.dev/v2/agent/JOB_ID" \
      -H "Authorization: Bearer $FIRECRAWL_API_KEY" | jq -r '.status')
    [ "$status" = "processing" ] || finished=1
  elif [ -n "$new" ]; then
    quiet=0
  else
    quiet=$((quiet + 1))
  fi

  sleep 5
done

执行追踪和快照

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

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# 单次运行的执行轨迹：有序事件（tool calls、推理、产物）
trace = app.get_agent_trace("JOB_ID")

for event in trace.events or []:
    print(event.type)

# 运行进行中时，一并返回当前活跃的浏览器会话
live = app.get_agent_trace("JOB_ID", live_view=True)
for session in live.active_browser_sessions or []:
    print(session.live_view_url)

import { Firecrawl } from 'firecrawl';

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

// 某次运行的执行轨迹：按顺序排列的事件（tool calls、推理、产物）
const trace = await firecrawl.getAgentTrace("JOB_ID");

for (const event of trace.events ?? []) {
  console.log(event.type);
}

// 运行进行中时，一并返回当前活跃的浏览器会话
const live = await firecrawl.getAgentTrace("JOB_ID", { liveView: true });
console.log(live.activeBrowserSessions);

curl "https://api.firecrawl.dev/v2/agent/JOB_ID/trace" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

# 在运行进行中时，包含当前活跃的浏览器会话
curl "https://api.firecrawl.dev/v2/agent/JOB_ID/trace?liveView=true" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

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

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# artifact.updated 追踪事件通过 snapshotId 引用快照内容
snapshot = app.get_agent_snapshot("JOB_ID", "SNAPSHOT_ID")

print(snapshot.snapshot)

import { Firecrawl } from 'firecrawl';

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

// artifact.updated 跟踪事件通过 snapshotId 引用快照内容
const snapshot = await firecrawl.getAgentSnapshot("JOB_ID", "SNAPSHOT_ID");

console.log(snapshot.snapshot);

curl "https://api.firecrawl.dev/v2/agent/JOB_ID/snapshots/SNAPSHOT_ID" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY"

Spark 2 运行会记录执行追踪和快照，也就是说所有新运行都会记录；在 Spark 1 模型退役前启动的任务则不包含这些记录。有关完整的事件 schema，请参见执行追踪和快照 API 参考；有关这些端点返回的失败情况，请参见代理错误目录。

获取代理的源数据

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

import json

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

trace = app.get_agent_trace("JOB_ID")

for event in trace.events or []:
    if event.type != "artifact.updated":
        continue

    kind = event.artifact.kind
    if kind not in ("markdown", "html", "json"):
        continue

    snapshot = app.get_agent_snapshot("JOB_ID", event.artifact.snapshot_id)

    # markdown、html 和 text 快照本身就是内容。
    # json 快照经过 JSON 编码，需要先解码。
    content = json.loads(snapshot.snapshot) if kind == "json" else snapshot.snapshot

    print(kind, event.artifact.path, content)

import { Firecrawl } from 'firecrawl';

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

const trace = await firecrawl.getAgentTrace("JOB_ID");

for (const event of trace.events ?? []) {
  if (event.type !== "artifact.updated") continue;

  const kind = event.artifact.kind;
  if (!["markdown", "html", "json"].includes(kind)) continue;

  const snapshot = await firecrawl.getAgentSnapshot("JOB_ID", event.artifact.snapshotId);

  // markdown、html 和 text 快照本身就是内容。
  // json 快照是 JSON 编码的，需要解码。
  const content = kind === "json" ? JSON.parse(snapshot.snapshot) : snapshot.snapshot;

  console.log(kind, event.artifact.path, content);
}

# 获取本次运行写入的所有 markdown、html 或 json 工件。
curl -s "https://api.firecrawl.dev/v2/agent/JOB_ID/trace" \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
| jq -r '.events[]
         | select(.type == "artifact.updated")
         | select(.artifact.kind == "markdown" or .artifact.kind == "html" or .artifact.kind == "json")
         | "\(.artifact.kind) \(.artifact.snapshotId)"' \
| while read -r kind snapshot_id; do
    body=$(curl -s "https://api.firecrawl.dev/v2/agent/JOB_ID/snapshots/$snapshot_id" \
      -H "Authorization: Bearer $FIRECRAWL_API_KEY")

    # markdown 和 html 快照本身就是内容；json 则经过 JSON 编码。
    if [ "$kind" = "json" ]; then
      printf '%s' "$body" | jq -r '.snapshot | fromjson'
    else
      printf '%s' "$body" | jq -r '.snapshot'
    fi
  done

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

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

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

模型选择

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

Spark 1 模型已弃用。 为保持向后兼容，仍接受 Spark 1 模型名称，但使用这些名称的请求会被路由到 spark-2。

Spark 2

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

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

指定模型

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

from firecrawl import Firecrawl

app = Firecrawl(api_key="fc-YOUR_API_KEY")

# Spark 2 是默认值 —— 每次运行都使用它
result = app.agent(
    prompt="Find the pricing of Firecrawl",
    model="spark-2"
)

# 已弃用:仍可使用 Spark 1 的模型名称,但会被路由到 "spark-2"。

print(result.data)

import { Firecrawl } from 'firecrawl';

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

// Spark 2 为默认值 — 每次运行都会使用它
const result = await firecrawl.agent({
  prompt: "Find the pricing of Firecrawl",
  model: "spark-2"
});

// 已弃用：仍接受 Spark 1 的模型名称，但会路由到 "spark-2"。

console.log(result.data);

# Spark 2 为默认模型——所有运行均使用它执行
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-2"
  }'

# 已弃用：仍可传入 Spark 1 的模型名称，但会路由到 "spark-2"。

需要接受条款的数据提供商

代理在运行期间可以调用 Alexandria 数据提供商，但仅限于你的团队已接受其数据条款的提供商。对于尚未接受条款的提供商，无论 exchange.onTermsRequired 如何设置，都不会被调用。运行会继续使用可用的提供商，状态响应中会列出被跳过的提供商。不支持自动接受模式。接受提供商的条款必须由人来确认：可以在 Dashboard 中操作，也可以由你的应用在用户明确同意后调用 terms/accept。如果你基于 Firecrawl 构建代理，该代理必须先征得用户同意，再调用 terms/accept。请求数据并不代表同意提供商的条款。

`onTermsRequired`	行为
`skip` (默认值)	运行仅使用已接受条款的提供商作答，且不会阻塞。`exchange.skippedProviders` 会列出本可派上用场、但受条款限制的提供商。
`ask`	与 `skip` 相同。此外，运行结束时会返回 `exchange.requiresAction` 以及一个 `kind: "terms"` 的 `pendingApproval`，便于你征询用户、接受条款，然后继续该会话。

如果在会话的后续轮次中省略 onTermsRequired，该轮次将沿用上一轮的值。如果某一轮次因需要审批付费调用 (requireApproval) 而结束，则该轮次不会提示接受条款。

响应字段

以下字段位于 GET /v2/agent/{id} 的 exchange 对象中：

skippedProviders (任意模式) ：每个本可派上用场、但因条款限制而被跳过的提供商对应一个条目，包含 provider、name、capability、adds (本可补充的内容) 、reason: "terms_required"、version (条款版本) 和 termsUrl (在 Dashboard 中接受条款的位置) 。
requiresAction (仅限 ask) ：包含 type: "accept_terms"、一个 approvalId 和一个 providers 列表。approvalId 始终存在，它是 terms 待审批项的 id，你在继续该会话时需要对其作出答复。每个提供商都附带需要执行的具体 show (terms/show) 和 accept (terms/accept) 调用。每个提供商的 digest (以及 accept.options.digest) 字段始终存在，但值可能为 null，表示目录未发布摘要。遇到这种情况，请先运行 terms/show，再发送其返回的摘要。

{
  "status": "completed",
  "exchange": {
    "enabled": true,
    "onTermsRequired": "ask",
    "paidCalls": 0,
    "creditsUsed": null,
    "skippedProviders": [
      {
        "provider": "apollo",
        "name": "Apollo",
        "capability": "people/search",
        "adds": "verified work emails and direct phone numbers",
        "reason": "terms_required",
        "version": "F-1.0.0",
        "termsUrl": "https://www.firecrawl.dev/app/alexandria/apollo"
      }
    ],
    "requiresAction": {
      "type": "accept_terms",
      "approvalId": "0199aaaa-0000-7000-8000-000000000000",
      "providers": [
        {
          "provider": "apollo",
          "name": "Apollo",
          "capability": "people/search",
          "version": "F-1.0.0",
          "digest": "<sha256>",
          "url": "https://www.firecrawl.dev/app/alexandria/apollo",
          "show": { "provider": "firecrawl", "capability": "terms/show", "options": { "provider": "apollo" } },
          "accept": {
            "provider": "firecrawl",
            "capability": "terms/accept",
            "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "<sha256>", "confirmed": true }
          }
        }
      ]
    }
  },
  "pendingApproval": {
    "id": "0199aaaa-0000-7000-8000-000000000000",
    "kind": "terms",
    "reason": "Apollo could add verified work emails and direct phone numbers.",
    "calls": [],
    "terms": [{ "provider": "apollo", "name": "Apollo", "version": "F-1.0.0", "digest": "<sha256>", "url": "https://www.firecrawl.dev/app/alexandria/apollo" }],
    "resolution": null
  }
}

先接受条款，再继续

在 ask 模式下：

向用户展示条款。通过 /v2/scrape 并使用 alexandria 执行该提供商的 show 调用。
仅在用户明确同意后，才以相同方式执行其 accept 调用。如果 accept.options.digest 为 null，请使用 terms/show 返回的 digest：

curl -X POST https://api.firecrawl.dev/v2/scrape \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "alexandria": {
      "provider": "firecrawl",
      "capability": "terms/accept",
      "options": { "provider": "apollo", "version": "F-1.0.0", "digest": "<sha256>", "confirmed": true }
    }
  }'

使用 exchange.approve 在同一会话中继续。该提议会被整体接受，其中的 callIds 和 always 将被忽略。下一轮会调用这些提供商来补足上一个答案中指出的缺口，而不会重新运行全部内容。

curl -X POST https://api.firecrawl.dev/v2/agent \
  -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "threadId": "<threadId from the previous run>",
    "prompt": "Continue with Apollo.",
    "exchange": {
      "approve": { "approvalId": "0199aaaa-0000-7000-8000-000000000000" }
    }
  }'

如果想在不使用该提供商的情况下继续，请改用 exchange.decline: { "approvalId": "..." } 继续。这会拒绝整个报价，且在该会话的后续过程中，其中的提供商都不会再被提供。在 skip 模式下，没有需要回复的待审批项。接受条款后，发起一次新的运行 (或在该会话中开始新一轮对话) ，即可使用该提供商。

参数

参数	类型	必填	描述
`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
`maxCredits`	number	否	此代理任务中可花费的最大额度数。如果未设置，默认值为 2,500。Dashboard 最高支持 2,500；如需更高上限，请通过 API 设置 `maxCredits` (高于 2,500 的值始终按付费请求处理) 。如果达到上限，任务会失败，并且不会返回任何数据。失败的运行不会计费：用于 AI 推理的额度在失败时绝不会收费，运行期间任何用于工具调用的额度 (scraping、search、mapping 等) 都会退还，并且响应会返回 `creditsUsed: 0`。
`exchange.onTermsRequired`	string	否	当代理需要使用的 Alexandria 数据提供商要求接受你的团队尚未接受的条款时，应采取的处理方式：`skip` (默认值) 或 `ask`。请参见需要接受条款的数据提供商

Agent 与 Extract：有哪些改进

特性	Agent (新)	Extract
是否需要提供 URL	否	是
速度	更快	标准
成本	更低	标准
可靠性	更高	标准
查询灵活性	高	中等

示例用例

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

在 Agent Playground 中上传 CSV

Agent Playground 支持通过上传 CSV 进行批量处理。你的 CSV 可以包含一列或多列输入数据。例如：一列公司名称，或者多列数据，如公司名称、产品和网站 URL。每一行都代表一个需要由 Agent 处理的条目。上传你的 CSV，然后使用表头中的 ”+” 按钮添加输出列。每一列都有自己的 prompt——点击列表头，描述 Agent 应为该字段查找什么内容 (例如，“CEO 或创始人姓名”、“融资总额”) 。点击 Run，Agent 会并行处理每一行并填充结果。

使用 Ask 排查问题

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

API 参考

请参阅 Agent API Reference 以了解更多详情。有反馈或需要帮助？请发送邮件至 help@firecrawl.com。

价格

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

Agent 计费方式

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

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

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

并行 Agent 计费

如果你使用 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 试用代理，看看在你的具体用例下额度的使用如何随规模变化。

随着我们从 Research Preview 过渡到正式开放，定价可能会发生变化。现有用户将在任何价格更新前提前收到通知。

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

快速上手

核心端点

更多

快速入门

开发者指南

Webhooks

使用场景

其他

参与贡献

代理

在 Playground 中体验

使用 `/agent`

响应

提供 URL (可选)

任务状态与完成

可能的状态

等待中示例

已完成示例

列出代理运行记录

跟踪正在进行的运行

执行追踪和快照

获取代理的源数据

模型选择

Spark 2

指定模型

需要接受条款的数据提供商

响应字段

先接受条款，再继续

参数

Agent 与 Extract：有哪些改进

示例用例

在 Agent Playground 中上传 CSV

使用 Ask 排查问题

API 参考

价格

Agent 计费方式

并行 Agent 计费

入门

成本管理

在 Playground 中体验

​使用 /agent

​响应

​提供 URL (可选)

​任务状态与完成

​可能的状态

​等待中示例

​已完成示例

​列出代理运行记录

​跟踪正在进行的运行

​执行追踪和快照

​获取代理的源数据

​分享代理运行记录

​模型选择

​Spark 2

​指定模型

​需要接受条款的数据提供商

​响应字段

​先接受条款，再继续

​参数

​Agent 与 Extract：有哪些改进

​示例用例

​在 Agent Playground 中上传 CSV

​使用 Ask 排查问题

​API 参考

​价格

​Agent 计费方式

​并行 Agent 计费

​入门

​成本管理

使用 `/agent`

响应

提供 URL (可选)

任务状态与完成

可能的状态

等待中示例

已完成示例

列出代理运行记录

跟踪正在进行的运行

执行追踪和快照

获取代理的源数据

分享代理运行记录

模型选择

Spark 2

指定模型

需要接受条款的数据提供商

响应字段

先接受条款，再继续

参数

Agent 与 Extract：有哪些改进

示例用例

在 Agent Playground 中上传 CSV

使用 Ask 排查问题

API 参考

价格

Agent 计费方式

并行 Agent 计费

入门

成本管理