打造对话式网页研究前端:Firecrawl Web Agent Next.js 模板流式UI与计划可视化全解析
打造对话式网页研究前端:Firecrawl Web Agent Next.js 模板流式UI与计划可视化全解析
web-agent 是一个面向结构化网页研究的开源 Web 数据智能体项目,其 Firecrawl Web Agent Next.js 模板开箱即用地提供了对话式研究界面:流式 UI 实时渲染 Agent 的每一步动作,计划可视化用 Mermaid 流程图展示研究规划,还能跟踪并行子智能体进度并导出结构化数据。本文将带你快速理解这套前端架构的核心设计。
一、项目分层结构与一键安装步骤
web-agent 采用"逐层搭建"的分层架构,Next.js 模板位于最上层,是上手最快的入口:
| 层级 | 说明 |
|---|---|
| agent-templates/next/ | 本文主角:Chat UI、流式渲染、Skills、子智能体、结构化输出 |
| agent-templates/express/ | 纯 API 服务版本,适合后端集成 |
| agent-core/ | 核心编排逻辑:基于 Deep Agents(LangChain)的 Orchestrator |
| Firecrawl AI SDK | Search、Scrape、Interact 三大网络工具的封装 |
🚀 快速启动只需三步:
git clone https://gitcode.com/gh_mirrors/weba/web-agent
cd web-agent/agent-templates/next
npm install
cp .env.local.example .env.local # 填入 FIRECRAWL_API_KEY
npm run dev # 访问 http://localhost:3000
模板完整说明见 agent-templates/next/README.md,核心 API 一览:
| 端点 | 作用 |
|---|---|
POST /api/agent |
主 Agent 流式端点(聊天 UI 使用,AI SDK 流) |
POST /api/v1/run |
REST API,与 Express 模板同构 |
POST /api/plan |
仅生成执行计划,不实际执行 |
GET /api/workers/progress |
轮询并行 Worker 的实时进度 |
POST /api/skills/generate |
从对话流式生成可复用的 SKILL.md |
二、流式 UI:消息如何实时"生长"出来 💬
对话界面基于 Vercel AI SDK 的 useChat 实现,数据链路是:
page.tsx (useChat) → POST /api/agent → agent-core → LangGraph 图 → SSE 流回浏览器
几个值得新手关注的设计点:
- 双流合并:
/api/agent路由(位于app/(agent)/api/agent/route.ts)以streamMode: ["values", "messages"]订阅 LangGraph。messages模式产生 token 级增量(打字机效果),values模式触发工具调用状态翻转——两者缺一,工具卡片都无法正常"完成"。 - 子图穿透:通过
subgraphs: true让子智能体的内部事件穿透父流。服务端在app/(agent)/api/agent/route.ts中做了命名空间映射,把子智能体内部的每一次 search/scrape 都归属到对应的父级task工具调用上。 - 时间线瓦片:前端 plan-visualization.tsx/_components/plan-visualization.tsx) 把流式事件还原成一条垂直时间线,每种工具有专属卡片:
- Search 卡片:favicon 堆叠 + 结果折叠展开,历史查询自动收起保持版面紧凑;
- Scrape 卡片:展示页面标题、状态码、缓存命中、credits 消耗,内容用 Markdown 渲染;
- Interact 卡片:浏览器自动化进行时内嵌 live view iframe,你能直接看到 Agent 在页面上点按钮、填表单;
- Bash 卡片:自动识别
jq/awk/cat等命令语义,把原始命令翻译成"Processing JSON""Saving notes"这类人话标签。
这套设计让"等待 3 分钟的 Agent"变成了"可围观的直播"。
三、计划可视化:Mermaid 流程图 + 工具调用时间线 📋
"计划可视化"是这个模板最有辨识度的功能,分两部分:
3.1 执行计划(Mermaid 流程图)
Agent 在动手前会先生成一份编号执行计划:每步标注用什么工具、什么输入、期望拿到什么数据。计划端点 POST /api/plan(位于 app/(agent)/api/plan/route.ts)用轻量模型独立生成,提示词约束为"每步一行、末尾给出最终输出格式"。
前端从消息流中筛出第一个包含 ```mermaid 围栏的文本块,交给 streamdown-block.tsx 渲染——它挂载了 @streamdown/mermaid 插件,在流式输出过程中就能渐进渲染流程图,而非等整块结束。
3.2 并行子智能体追踪
当 Orchestrator 通过 task 工具派出并行 Worker 时,每个 Worker 会渲染为一张 SubagentCard:
- 运行中:自动展开,实时展示"Train of thought"流式文本 + 内部工具调用;
- 完成后:自动折叠,只留一行统计胶囊,如
3 searches · 5 pages scraped · 12cr; - 头部展示该 Worker 触碰过的域名 favicon 堆叠,不展开也能看清它"去了哪些网站"。
配合 GET /api/workers/progress 轮询,maxWorkers(默认 10)个并行任务各有独立进度。
四、Artifact 面板:结构化数据输出 ⚡
研究结束不是终点。formatOutput 工具把结果整理为 JSON/CSV/Markdown,前端 Artifact 面板(app/(agent)/_components/artifact-panel.tsx)提供:
- JSON Viewer:可折叠树形结构浏览 + 复制/下载;
- Markdown 渲染器:带一键下载;
- Save as Skill:把一次成功的对话沉淀为可复用的
SKILL.md技能文件(流式生成,走/api/skills/generate),技能随后被agent-core自动发现并在后续会话中按需加载。
五、最快定制方法:只改一个配置文件
整个模板的模型与行为配置集中在 app/(agent)/_config.ts 一个文件中:
export const config = {
orchestrator: { provider: "anthropic", model: "claude-sonnet-4-6" },
subAgent: { provider: "anthropic", model: "claude-sonnet-4-6" },
background: { provider: "anthropic", model: "claude-haiku-4-5-20251001" },
maxWorkers: 10, // 最大并行 Worker 数
workerMaxSteps: 50, // 每个 Worker 最大步数
tasks: { plan: null, suggestions: null, /* 按任务覆盖模型 */ },
history: { enabled: false },
};
切换 Anthropic / OpenAI / Google / 自定义 OpenAI 兼容端点只需注释切换对应块;UI 侧还有 Model Selector(运行时换模型)和 Settings 面板(BYOK,直接粘贴 API Key),无需改代码。
六、关键文件路径速查
| 模块 | 路径 |
|---|---|
| 模板说明与 API 列表 | agent-templates/next/README.md |
| 模型与功能总配置 | agent-templates/next/app/(agent)/_config.ts |
| 主聊天页面 | agent-templates/next/app/(agent)/page.tsx |
| 流式 Agent 端点 | agent-templates/next/app/(agent)/api/agent/route.ts |
| 计划生成端点 | agent-templates/next/app/(agent)/api/plan/route.ts |
| 时间线 + 计划可视化 | agent-templates/next/app/(agent)/_components/plan-visualization.tsx |
| 结构化产物面板 | agent-templates/next/app/(agent)/_components/artifact-panel.tsx |
| Mermaid/Markdown 渲染 | agent-templates/next/components/shared/streamdown-block.tsx |
| 系统提示词加载 | agent-templates/next/prompts/loader.ts |
| 核心编排层 | agent-core/src/orchestrator/index.ts |
| 内置技能定义 | agent-core/src/skills/definitions/ |
小结
Firecrawl Web Agent Next.js 模板把"计划 → 流式执行 → 可视化 → 结构化导出"这条完整链路做成了参考实现:/api/agent 双流订阅解决实时性,Mermaid 计划 + 工具瓦片时间线解决可解释性,SubagentCard 解决并行透明性,Artifact 面板解决数据落地。读懂 plan-visualization.tsx 这一个文件,基本就能掌握对话式 Agent 前端可视化的全部套路。想要更细粒度控制时,再向下沉到 agent-core/README.md 查看核心层用法即可。
