Firecrawl Web Agent实时流式输出实战:事件流、进度跟踪与Worker系统完整指南
Firecrawl Web Agent实时流式输出实战:事件流、进度跟踪与Worker系统完整指南
Firecrawl Web Agent(web-agent)是一款开源的 Web 数据研究 Agent,它的核心亮点之一就是实时流式输出:你不必干等几分钟才拿到结果,Agent 的每一次搜索、每一次抓取、每一步推理都会以标准化**事件流(SSE)**的形式实时推送到前端,配合可并行执行的 Worker 系统和进度跟踪接口,让你构建出"看得见的"AI 研究应用。本文将带你快速上手 agent.stream()、读懂 6 种事件类型,并掌握 spawnAgents 并行 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 章节。
核心文件导航
- agent-core/src/agent.ts ——
stream()/sse()/toResponse()主实现 - agent-core/src/types.ts ——
AgentEvent、StepDetail类型定义 - agent-core/src/stream-helpers.ts —— 通用事件流与 SSE 辅助函数
- agent-core/src/worker/index.ts —— Worker 系统、
spawnAgents与进度跟踪 - agent-core/examples/5-streaming.ts —— 流式输出最小示例
- agent-core/openapi.yaml —— HTTP API 与事件结构规范
- agent-templates/express/server.ts —— Express 版 SSE 与进度接口
- agent-templates/next/app/(agent)/api/v1/run/route.ts/api/v1/run/route.ts) —— Next.js 版流式路由
小结
web-agent 的实时流式输出体系可以概括为三层:
- 事件层:
agent.stream()归一化出 6 种AgentEvent,产生即推送 - 传输层:
sse()/toResponse()一键封装成 SSE,Express 和 Next.js 模板开箱即用 - 并行层:
spawnAgents分派最多 6 个 Worker 并行抓取,workerProgress全局状态 +/v1/workers/progress轮询接口让每个 Worker 的进度尽收眼底
掌握这套组合,你就能给自己的 AI 应用加上"过程可视化"能力——让等待变得透明,让 Agent 真正可信。🚀
