Firecrawl Web Agent实时流式输出实战:事件流、进度跟踪与Worker系统完整指南

原创2026-10-13 21:50:261,942 阅读

Firecrawl Web Agent实时流式输出实战:事件流、进度跟踪与Worker系统完整指南

Firecrawl Web Agent(web-agent)是一款开源的 Web 数据研究 Agent,它的核心亮点之一就是实时流式输出:你不必干等几分钟才拿到结果,Agent 的每一次搜索、每一次抓取、每一步推理都会以标准化**事件流(SSE)**的形式实时推送到前端,配合可并行执行的 Worker 系统和进度跟踪接口,让你构建出"看得见的"AI 研究应用。本文将带你快速上手 agent.stream()、读懂 6 种事件类型,并掌握 spawnAgents 并行 Worker 的进度跟踪完整方案。

为什么需要实时流式输出?

Firecrawl Web Agent 实时流式输出事件流与 Worker 进度跟踪示意图

传统的"请求—等待—响应"模式在 AI Agent 场景下体验很差:一次 Web 研究任务往往需要几十步搜索和抓取,耗时几分钟。如果用户只能盯着一个转圈图标,很容易流失。

web-agent 的解决方案是把 Agent 的执行过程变成一条事件流:

  • 模型每输出一段文字 → 推送 text 事件
  • 每调用一个工具(search / scrape)→ 推送 tool-call 事件
  • 每个工具返回结果 → 推送 tool-result 事件
  • 任务结束 → 推送 done 事件(含完整步骤、token 用量、耗时)
  • 出错 → 推送 error 事件

前端只需消费这条流,就能渲染出类似聊天应用的实时过程展示。核心实现在 agent-core/src/agent.ts 的 stream() 方法中,它基于 LangGraph 的 messages + updates 双模式流做归一化。

快速上手:3 步开启流式输出

以官方示例 agent-core/examples/5-streaming.ts 为参考,流式调用只需 3 步:

第 1 步:创建 Agent 实例

import { createAgent } from "@firecrawl/agent-core";

const agent = createAgent({
  firecrawlApiKey: process.env.FIRECRAWL_API_KEY,
  model: { provider: "google", model: "gemini-3-flash-preview" },
});

第 2 步:调用 agent.stream(),用 for await 消费事件

for await (const event of agent.stream({
  prompt: "Find the 5 most recent YC-backed AI startups and their founders",
})) {
  if (event.type === "text") {
    process.stdout.write(event.content ?? "");   // 实时打印文字增量
  } else if (event.type === "tool-call") {
    console.log(`\n  [调用工具] ${event.toolName}`); // 实时打印工具调用
  }
}

第 3 步:在 done 事件中取最终结果

if (event.type === "done") {
  console.log("最终答案:", event.text);
  console.log("共执行步骤:", event.steps?.length);
  console.log("总耗时(ms):", event.durationMs);
}

就这么简单——stream() 是一个异步生成器,事件产生即推送,天然适配实时 UI。

6 种事件类型完整解析

AgentEvent 是流式输出的核心数据结构,定义在 agent-core/src/types.ts,共 6 种类型:

事件类型 触发时机 关键字段 典型用途
text 模型每输出一段文字 content 聊天界面打字机效果
tool-call 模型决定调用工具时 toolName, input 展示"正在搜索 xxx"
tool-result 工具执行完毕返回 toolName, output 展示抓取结果、折叠面板
usage 每一步的 token 统计 usage 实时显示消耗
done 任务完成 text, steps, usage, durationMs, model 汇总展示最终结果
error 运行中发生异常 error 错误提示与重试

💡 设计细节:done 事件是一个"全家桶"——它携带了最终文本、逐步执行记录(steps 数组)、orchestrator 加所有子 Agent 的 token 总用量,以及 schemaMismatch(当指定了 schema 但输出未完全匹配时)。一个 done 事件就足够你渲染整个结果页。

如何把事件流推送到浏览器?SSE 实战

agent-core 内置了 SSE(Server-Sent Events)支持,有两条路径可选:

路径一:Express 模板 —— 一行代码开启

在 agent-templates/express/server.ts 中,POST /v1/run 接口原生支持流式:请求体里加上 "stream": true,服务端就会调用 agent.sse(params, res),自动设置 text/event-stream 响应头并逐条推送事件:

curl -N -X POST http://localhost:3000/v1/run \
  -H 'Content-Type: application/json' \
  -d '{"prompt": "Get pricing for Vercel", "stream": true}'

终端会持续收到形如 data: {"type":"tool-call","toolName":"search",...} 的 SSE 帧,每帧以 \n\n 结尾。

路径二:Next.js / Hono / Bun —— 用 toResponse()

agent-core 提供了 toResponse() 辅助函数,直接把事件流包装成标准 Web Response(ReadableStream),在 Next.js 模板/api/v1/run/route.ts#L94-L122) 的 /api/v1/run 路由中可以看到完整用法。此外 stream-helpers.ts 还导出了纯函数 streamEvents(),即使你不用 createAgent 包装、直接操作 Deep Agent,也能复用同一套事件归一化逻辑。

📖 完整的 HTTP API 与事件结构定义见 agent-core/openapi.yaml 中的 AgentEvent schema。

Worker 系统:并行抓取 + 实时进度跟踪

当任务包含大量独立目标(比如同时抓取 10 个网站的价格),web-agent 的 orchestrator 会调用 spawnAgents 工具把任务分派给多个并行的 Worker Agent,实现在 agent-core/src/worker/index.ts。

Worker 的运行规则

  • 并行上限:由 maxWorkers 控制,默认 6 个
  • 步数上限:每个 Worker 由 workerMaxSteps 限制(默认 10),防止跑偏
  • 工具裁剪:Worker 只有 search、scrape、bashExec——浏览器类工具 interact 太重,不进入并行 Worker,避免会话冲突
  • 超时保护:单个 Worker 超过 5 分钟自动中止,状态标记为 error
  • 提示词约束:Worker 的系统提示(worker/prompts/system.md)要求只输出事实与来源 URL,不写叙述,保持结果精简

进度跟踪:workerProgress 共享状态

每个 Worker 的运行状态会被实时写入一个全局 workerProgress Map(定义于 worker/index.ts),字段包括:

字段 含义
status running / done / error 三态
steps 已执行步数
currentTool / currentInput 当前正在用的工具及参数(截断至 80 字符)
tokens 累计 token 消耗
stepLog 逐步操作日志,如 Searched: "RTX 5090 price"
liveViewUrl 浏览器会话的实时预览地址(如有)

状态在每完成一步(onStepFinish 回调)时增量更新,天然适合前端轮询。

前端如何消费进度?1 秒轮询一次

Express 模板暴露了 GET /v1/workers/progress 路由(server.ts),把整个 workerProgress Map 序列化为 JSON 返回;Next.js 模板在 workers/progress/route.ts/api/workers/progress/route.ts) 提供等价接口。

Next.js 前端的 WorkersPanel 组件/_components/plan-visualization.tsx#L1540-L1553) 展示了最佳实践:只要检测到 Worker 处于 running 状态,就以 1 秒为间隔轮询进度接口,把每个 Worker 的当前工具、步数实时渲染成卡片;全部完成后自动折叠面板。

这套"SSE 主事件流 + 轮询进度接口"的组合,就是 web-agent 实时体验的完整配方:主线程用 SSE 保证文字增量零延迟,并行分支用轻量轮询展示进度,两条通道互不阻塞。

关键参数速查表

参数 位置 默认值 说明
maxSteps createAgent / run 50 orchestrator 最大步数
maxWorkers createAgent 6 并行 Worker 上限
workerMaxSteps createAgent 10 单个 Worker 最大步数
stream /v1/run 请求体 false true 时返回 SSE 事件流
subAgentModel createAgent 同主模型 Worker 可单独指定更便宜的模型

完整参数说明见 agent-core/README.md 的 API 章节。

核心文件导航

小结

web-agent 的实时流式输出体系可以概括为三层:

  1. 事件层:agent.stream() 归一化出 6 种 AgentEvent,产生即推送
  2. 传输层:sse() / toResponse() 一键封装成 SSE,Express 和 Next.js 模板开箱即用
  3. 并行层:spawnAgents 分派最多 6 个 Worker 并行抓取,workerProgress 全局状态 + /v1/workers/progress 轮询接口让每个 Worker 的进度尽收眼底

掌握这套组合,你就能给自己的 AI 应用加上"过程可视化"能力——让等待变得透明,让 Agent 真正可信。🚀

登录后查看全文
web-agent