打造对话式网页研究前端:Firecrawl Web Agent Next.js 模板流式UI与计划可视化全解析

原创2026-10-14 07:02:42675 阅读

打造对话式网页研究前端:Firecrawl Web Agent Next.js 模板流式UI与计划可视化全解析

web-agent 是一个面向结构化网页研究的开源 Web 数据智能体项目,其 Firecrawl Web Agent Next.js 模板开箱即用地提供了对话式研究界面:流式 UI 实时渲染 Agent 的每一步动作,计划可视化用 Mermaid 流程图展示研究规划,还能跟踪并行子智能体进度并导出结构化数据。本文将带你快速理解这套前端架构的核心设计。

Firecrawl Web Agent 对话式网页研究前端模板标识

一、项目分层结构与一键安装步骤

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 查看核心层用法即可。

登录后查看全文
web-agent