最近在给团队搭 Agent AI 智能体平台的前端技术架构从协议定义、长连接通道、流式渲染到并发控制前前后后踩了不少坑。正好手上这份《Agent AI 前端技术架构设计文档》迭代到了第三版今天把里面的核心思路和一些源码级的实现细节拿出来聊聊希望对正在做 AI 应用前端的同学有点用。这套架构解决的是这样一类产品问题用户在前端输入一个目标后端由多个 Agent 拆解任务、调用工具、读写记忆、甚至请求人工确认整个执行过程不是一次请求-响应而是一条异步事件流。前端要做的不只是把内容显示出来还要让用户“感知”到 Agent 在思考、在执行、在等待确认并且能随时打断、调整和恢复。这套架构的目标就是把这套体验从“能聊天”做到“可掌控”。适合的人群是正在从传统管理后台转向 AI 应用开发的前端工程师准备自己从 0 到 1 搭建 Agent 前端的团队以及在面试或述职中需要把 Agent 前端方案讲清楚的人。这篇文章不会只贴概念我会把消息协议、状态机、Hook 实现、组件注册机制这些可以直接落地的代码片段都放出来。1. 为什么 Agent AI 前端需要独立架构1.1 传统管理后台的模型为什么不够用传统前端交互模型是“请求-响应”页面发一个 HTTP 请求后端等所有计算完成一次性返回一个 JSON前端把它渲染成表格、表单或者详情页。在这种模型下前端本质上是数据的镜子后端不返回前端就没有东西可渲染。但 Agent 场景完全不是这样。一个 Agent 执行一次任务可能先要规划步骤然后调用一个搜索 API再把结果喂给大模型继续生成下一段内容。整个过程会产生多个阶段的输出而且每个阶段之间没有固定时间间隔可能几十秒都没有一个 token也可能一瞬间涌进来几百个 token。如果沿用传统模型用户只能看到一个转圈 loading完全不知道 Agent 在想什么、在调什么工具、为什么这么慢甚至断线重连后之前的状态全部丢失只能重新开始。这背后真正的变化是后端从一个“返回结果的接口”变成了“持续产生事件的执行流”。前端架构如果不能跟上这个变化后面所有体验问题都会被无限放大。1.2 从 Agent 产品反推前端需求我梳理了几个典型的 Agent 产品形态任务式对话助手、数据分析助理、代码生成插件、企业内部流程 Agent。它们的交互有高度共性流式文本输出而且大多是 Markdown 格式执行过程中动态调用工具用户需要看到工具调用的状态用户可以中途打断、修改参数、重新执行多轮会话保留了上下文前端要能完整还原长会话多 Agent 协作时消息要区分是哪个角色说的甚至哪个 Agent 说的从这些产品共性反推前端必须具备四个基础能力一条可靠的双向长连接通道一套能覆盖流式文本、工具调用、状态切换、错误恢复的消息协议一个支持增量渲染并且不会越用越卡的渲染层以及一个能管理“等待、思考、生成、执行工具、等待用户确认、失败、完成”的状态机。1.3 前端需求清单汇总在设计之前我习惯先把需求全部写下来建了一张优先级表避免后面实现的时候被临时需求打乱节奏模块核心需求优先级连接管理WebSocket 心跳、断线重连、消息确认、会话恢复P0消息协议事件类型定义、seq 序号、增量内容、错误码P0状态管理会话状态机、多会话隔离、局部消息更新P0流式渲染Markdown 增量渲染、剧本文本不卡顿、虚拟滚动P0交互控制中断、重试、参数修改、人工确认面板P1组件生态消息渲染注册中心、可插拔技能组件P1可观测性渲染耗时上报、长任务统计、连接状态面板P2这个清单基本决定了后续所有技术选型。你会发现里面没有一项是传统页面里的“数据表格怎么做”全部围绕“事件流的实时呈现与人机协同控制”展开。2. 前端整体分层架构设计2.1 四层架构协议层、会话层、渲染层、交互层很多团队做 Agent 前端最容易犯的错就是把 WebSocket 逻辑直接塞进 React 组件里。刚开始还能跑等加了四五个 Agent 能力、十几种消息类型之后组件里全是 if else改动一处牵连一片。所以我把前端拆成四层每层只负责一件事协议层负责消息 Schema 定义、编解码、事件类型校验。这一层不接触任何 UI 框架只处理数据。会话层负责 WebSocket 连接、心跳、重连、消息序号管理、多会话通道隔离它把“连接是否活着”这件事从业务里抽离出来。渲染层负责消息渲染器、Markdown 解析、工具调用卡片、虚拟滚动。交互层负责命令面板、技能选择器、人工确认弹窗、流式输入框。分层的核心目的很朴素因为 Agent 协议会持续演进今天加一个“记忆检索事件”明天加一个“子任务进度事件”如果协议和组件耦合在一起每加一个事件都要重构组件树。分层之后加一种新消息类型只需要三件事协议层加 Schema、渲染层注册一个新渲染器、会话层不做任何修改。2.2 传输通道为什么选择 WebSocket 而不是 SSE 或轮询我在选传输通道时把三种方案的实际表现都列了出来对比方案优势在 Agent 场景的短板HTTP 轮询实现最简单任何后端都支持消息延迟取决于轮询间隔无用请求太多断线状态恢复困难SSE服务端单向推送轻量自动重连机制成熟上行控制指令需要额外请求无法直接在一条连接里打断/修改执行WebSocket全双工下行推流、上行控制指令共用一条连接连接管理复杂度高需要自己实现心跳和重连Agent 场景最特殊的地方是交互控制用户看到 Agent 调错工具时要能立刻点击打断这个打断指令最好在几十毫秒内到达后端。如果用 SSE 额外 POST 来实现控制链路多一跳延迟和失败概率都会增加。实测下来如果消息频次高、控制指令多WebSocket 的前期成本完全值得。另外我保留了 REST 接口作为兜底通道。断线重连后如果消息空洞太多直接调 REST 接口拉取整个会话快照而不是靠 WebSocket 重放几千条事件恢复速度快一个数量级。2.3 会话消息协议设计用事件流代替请求-响应协议是整个前端架构的地基。我设计了一套基于事件流的协议服务端所有下行数据都是事件客户端所有上行指令也是事件。核心消息结构是下面这样{ type: agent.message_delta, session_id: sess_8f2a, message_id: msg_01, agent_id: planner, delta: 我们需要先, seq: 102, ts: 1700000000123 }几个字段的设计考量我展开说一下。session_id是所有消息都带的因为前端可能同时跑多个 Agent 会话连接层必须靠它把消息路由到不同的会话通道。seq是全局单调递增序号用于乱序检测和丢帧识别这一项在后面排查问题时帮了大忙。message_id是把一条完整消息从多个 delta 里聚合出来的标识属于同一条消息的 delta 会共用同一个 message_id。下行事件类型我目前定义了这些session.started会话创建成功下发 session_id 和初始状态agent.thinkingAgent 进入思考阶段渲染端展示“正在分析”状态agent.message_delta流式文本增量agent.message_done单条消息输出结束tool.called工具调用开始tool.output工具返回结果agent.waiting_user需要用户确认或补充信息session.error错误信息带错误码session.completed整个任务完成上行指令则包括client.submit_input、client.interrupt、client.retry、client.resume。前后端只认这一套协议无论是换后端框架还是换前端框架协议不变契约就不变。2.4 会话状态机先于 UI 设计的核心搞定协议后我做的第一件事不是画页面而是把状态机定义出来。Agent 前端最复杂的不是某个组件怎么写而是执行过程在不同阶段之间的流转。我把会话状态定义为八个IDLE会话创建待用户输入THINKINGAgent 正在规划GENERATING正在生成文本TOOL_CALLING正在执行工具WAITING_USER等待用户确认或补充FAILED执行失败CANCELED用户主动取消COMPLETED任务完成状态之间不是随意跳转的比如GENERATING可以因为调用工具而跳转到TOOL_CALLING工具执行完跳回GENERATING中途用户点了打断则跳到CANCELED。我在会话层维护了一个状态守卫函数非法跳转直接报错开发期就能发现协议后端的异常行为。UI 只是状态机的一种投影。状态是TOOL_CALLING渲染层就展示工具执行卡片状态是WAITING_USER渲染层就展示确认面板。业务组件里不会出现“这段数据什么时候展示”的判断逻辑因为状态机已经替它做完了。3. 核心细节实现流式渲染与消息组件3.1 增量渲染不要让 React 把整个消息重新渲染流式渲染最容易踩的坑是每次收到 delta就 setState 把整条新字符串替换掉。早期我这么写过消息到三千字的时候页面肉眼可见地卡输入框都跟着掉帧。原因很简单React 会对整个消息组件做 diff三千字的字符串 diff 一次再来几十个 delta性能直接崩。正确做法是把“消息文本”收敛到一个独立的流式文本组件里外层列表继续用 React 渲染内层文本区域用命令式 DOM 追加。我这里贴一个核心 Hookfunction useStreamText() { const ref useRefHTMLDivElement(null); const bufferRef useRef(); const timerRef useRefnumber(); const append useCallback((chunk: string) { bufferRef.current chunk; if (!timerRef.current) { timerRef.current requestAnimationFrame(() { if (ref.current) { ref.current.textContent bufferRef.current; } bufferRef.current ; timerRef.current undefined; }); } }, []); return { ref, append }; }这段代码做了三件事把同一帧里的多个 delta 合并成一次 DOM 写入用 textContent 直接追加跳过 React 虚拟 DOM diff借助 requestAnimationFrame 天然形成节流效果。实测在高速流式输出时页面帧率能稳定在 50 帧以上。注意当流式文本结束后需要做一次完整 Markdown 渲染此时才把 textContent 替换为渲染后的 HTML。否则流式过程中用户看到的是纯文本结束后再看到带格式的版本体验上是可接受的。3.2 Markdown 渲染的性能优化策略Agent 输出的内容几乎都是 Markdown直接用 markdown-it 处理流式文本会有一个经典问题Markdown 语法可能横跨多个 chunk比如某条加粗语法的开始符号**在 chunk A 里结束符号在 chunk B 里。如果每个 chunk 都单独解析页面会出现闪烁甚至渲染出错误的格式。我采用的方案是“稳定期渲染”只要流式 delta 还在持续进来就用明文追加模式完全不解析 Markdown当连续 500ms 没有新的 delta或者该条消息收到message_done事件后才把整个消息的完整文本交给 markdown-it 做一次最终渲染。另外在 markdown-it 初始化时我关闭了几个用不到的增强选项const md new MarkdownIt({ html: false, linkify: false, typographer: false, });linkify 会自动识别链接但在大文本里它需要跑很多正则关掉后渲染速度提升明显。如果产品需要自动识别链接建议在最终渲染阶段单独处理不要在流式阶段开。消息文本超过一定长度后还要做折叠处理。我在消息组件里加了一个阈值超过 2000 字默认折叠为前 200 字摘要点击“展开全文”才做完整渲染。既减少了初始渲染压力也让长会话页面更清爽。3.3 工具调用卡片与人工确认节点工具调用是 Agent 场景里最有价值的部分也是最容易被前端忽视的部分。一个工具调用从前端视角看要经历三个阶段已发出、执行中、已完成每个阶段的 UI 重点不同。我实现了一个ToolCallCard组件核心逻辑是根据工具状态渲染不同内容const ToolCallCard ({ tool }: { tool: ToolCallInfo }) { return ( div classNametool-card div classNametool-card__header span{tool.name}/span span{tool.status running ? 执行中 : 完成}/span {tool.durationMs span{tool.durationMs}ms/span} /div pre{tool.arguments}/pre {tool.status completed pre{tool.output}/pre} /div ); };这里的pre元素直接渲染结构化数据比把参数拼成自然语言更利于用户判断。比如一个查天气工具用户看到入参是{city: 杭州, date: 2026-01-15}一眼就能确认 Agent 是否理解对了需求。人工确认节点更关键。当协议收到agent.waiting_user事件时前端必须把“确认场景、参数信息、风险提示”三要素展示清楚而不是简单弹一个确定框。确认按钮点击后发送client.submit_input事件上行同时把整个会话状态机切到GENERATING。这个交互是整个流程里用户参与感最强的位置值得多花心思打磨。3.4 多智能体协同的消息结构设计当系统里有 planner、executor、critic 多个角色协作时消息结构不再是一问一答那么简单。我在 SessionMessage 类型里增加了几个字段interface SessionMessage { id: string; sessionId: string; agentId: string; agentName: string; role: user | assistant | system; kind: text | tool | image | error; content: unknown; status: streaming | done | error; createdAt: number; }渲染层按agentId分组每个 Agent 有自己的头像和主题色。用户不需要理解复杂的调度逻辑只需要知道“这段话是谁说的、这个工具是谁调的”。多 Agent 消息列表的布局我先后试过两种。如果执行流程是线性的单线滚动列表最省空间。如果有多个 Agent 并行执行子任务单线列表会显得很乱我改成“执行计划卡片 单线详情”的混合模式计划卡片展示每个子任务的状态点击后详情区展示对应的消息流。这种模式在数据分析类 Agent 产品里效果尤其好。4. 前端如何扛住 Agent 的并发与长连接4.1 WebSocket 连接管理与心跳保活“ai agent 怎么扛并发”是很多团队关心的核心问题。前端这里的并发压力不像后端那么直白更多体现在连接稳定性上。只要 Agent 任务持续几十分钟中间很可能有几十秒没有新数据推送Nginx、网关甚至浏览器都可能断开空闲连接。所以我必须做心跳保活。心跳的逻辑不算复杂每 30 秒发一个ping服务端回pong连续 3 次没有 pong判定连接失效触发重连。重连不能无脑快速重试我用的是指数退避const connect () { ws new WebSocket(url); ws.onmessage handleMessage; ws.onclose () { const delay Math.min(1000 * 2 ** retryCount, 15000); setTimeout(connect, delay); retryCount; }; ws.onopen () { retryCount 0; startHeartbeat(); }; };首次失败 1 秒重试之后翻倍最大 15 秒封顶。这比固定间隔重连要稳得多尤其在服务端发布重启、批量连接断开的时间点指数退避可以避免所有客户端同时撞上来。4.2 消息序列号与乱序处理WebSocket 本身是顺序传输的但在 Agent 场景里后端往往不是单进程多个微服务可能同时往同一个会话里推消息这时候前端就会遇到消息乱序。协议层每一条事件都带了seq前端维护一个lastSeq变量。收到事件时这样处理事件的 seq 小于等于 lastSeq直接判为重复等于 lastSeq 1正常处理并推进 lastSeq大于 lastSeq 1说明中间有空洞先放入 pending 队列同时触发一次快照拉取请求以 REST 接口返回的完整数据为准修正乱序状态。这套机制在实际生产里处理掉了绝大多数偶发的消息乱跳问题。4.3 多会话并发隔离的渲染策略一个用户同时开多个 Agent 任务是很常见的。比如用户在左侧会话列表里挂了三个任务同时切到第四个任务在看详情。如果前端把四个任务的消息全都实时渲染再强大的浏览器也会卡。我给每个会话分配了独立的 message 队列。渲染层只对当前激活会话做 DOM 更新非激活会话的消息到达后只做协议解析和状态写入不触发 React 重渲染。等用户切回来时直接渲染最新状态用户看到的效果是“切回来就是最新的”。这个策略在代码层面的落地是给每条消息加了一个dirty标记。非激活会话积压的 dirty 消息不清除切回激活时一次性批量渲染并清除标记。消息列表组件用 React.memo 包裹只有 dirty 集合有变化时才触发更新。4.4 渲染层的节流与空闲调度高频 token 涌入时即使用了流式文本组件其他区域的渲染也可能受到影响。我做了三个层面的优化第一所有 delta 事件统一经过一个节流处理器用 requestAnimationFrame 合并同一帧的多次更新。第二消息列表如果很长开启虚拟滚动只渲染可视区内的 10 到 20 条消息。第三低优先级的任务比如会议摘要生成、历史消息详情展开用 requestIdleCallback 延迟到浏览器空闲时才执行。另外有一个很容易忽略的细节自动滚动。流式输出时如果用户已经在往上翻看历史消息自动滚动会把他的阅读位置强行拉走非常恼人。我通过 IntersectionObserver 判断消息列表底部是否在可视区内只有“用户在底部”时才跟随滚动否则只更新未读数量。5. 工程化实践与可扩展组件生态5.1 状态管理选型为什么最终选了 ZustandAgent 前端的状态管理有一个特殊需求频繁更新局部消息而且更新源来自 WebSocket 回调不一定在 React 事件周期内。我对比了几个主流方案方案优势在 Agent 场景的问题Redux Toolkit团队规范强、DevTools 成熟样板代码多流式高频更新时写起来很繁琐Zustand轻量、selector 精确订阅、可在组件外直接更新需要团队约定好 store 结构PiniaVue 生态首选React 项目里需要额外适配层Jotai原子状态粒度细消息列表的嵌套更新反而更麻烦最后选了 Zustand。核心原因有两个一是它的 selector 能力可以精确到只监听某一会话某一条消息的变化流式更新时不会带动整个 store 消费组件重渲染二是不需要 Provider 包裹WebSocket 的消息回调里可以直接调用 store 的方法来更新状态不用绕 React 的 API 层。实际写起来差不多是这样const useAgentStore createAgentStore((set, get) ({ sessions: {}, upsertMessage: (sessionId, message) set((state) { const session state.sessions[sessionId] ?? createEmptySession(); const updatedSession upsertMessageToSession(session, message); return { sessions: { ...state.sessions, [sessionId]: updatedSession, }, }; }), }));注意我在upsertMessage里为每个 session 单独做更新而不是把整个 sessions 对象重新创建就是为了尽可能减少触发全量更新的范围。5.2 消息组件注册中心让技能可插拔Agent 的能力会持续扩展前端消息类型必然跟着增长。我不可能在组件里写死所有类型。我的做法是维护一个全局的消息渲染器注册中心const renderers new Mapstring, React.ComponentTypeany(); export function registerRenderer(type: string, component: React.ComponentTypeany) { renderers.set(type, component); } export function getRenderer(type: string) { return renderers.get(type) ?? FallbackRenderer; }每次新增一种 Agent 技能只需要调用一次registerRenderer把消息类型和组件绑定好。渲染层拿到的消息带kind字段直接查表渲染查不到就用兜底组件展示原始 JSON。这个机制让前端和 Agent 技能开发完全解耦后端加新工具前端不需要发版。5.3 前端 SDK 与组件库设计底层能力稳定之后我花时间把核心逻辑抽成了一个独立的 SDK 包暴露给上层业务线使用。SDK 内部封装了 WebSocket 连接、心跳重连、消息解析、状态机更新对外只提供三个东西createAgentClient({ endpoint })创建客户端实例useAgentSession(client)返回消息列表、发送指令方法AgentMessageList /和AgentInput /两个基础组件业务线使用时核心代码很简洁const client createAgentClient({ endpoint: /agent/v1 }); function Chat() { const { messages, sendMessage, interrupt } useAgentSession(client); return ( div AgentMessageList messages{messages} / AgentInput onSend{sendMessage} onInterrupt{interrupt} / /div ); }之所以抽 SDK是因为我发现很多业务线用到了同样的协议和组件如果不抽每一条业务线都会自己实现一套 WebSocket 管理质量参差不齐。抽出来之后协议升级只需要改 SDK业务线保持零感知。5.4 与后端编排器的对接约定前端协议一旦确定后端无论用什么编排框架LangGraph、自研引擎、还是 FastAPI LangChain只要遵循同一套接口约定就能对接。REST 接口我定义了四个POST /v1/agent/session创建会话返回 session_idPOST /v1/agent/session/{id}/messages提交用户消息或确认指令GET /v1/agent/session/{id}/messages拉取历史消息用于断线恢复GET /v1/agent/session/{id}/snapshot拉取会话状态快照用于修复乱序WebSocket 接口则固定为/v1/agent/ws?session_idxxx服务端下行事件、客户端上行事件都遵循协议层定义。前端完全不关心后端内部是 DAG 编排还是链式调用只要走这套契约前后端就能并行开发。6. 常见问题与排查技巧实录6.1 流式消息乱序、丢帧怎么处理现象同一会话的文本顺序错乱或者最后一段内容丢了。这个问题在并发推送场景最常见。排查时先看 WebSocket 连接是否正常再打开协议日志确认每个事件的 seq 是否连续。如果服务端某个微服务没有接入统一的事件服务单独往会话里推数据就会出现空洞。处理办法是协议层保证每个事件都走同一个序号生成器前端收到 seq 大于 lastSeq 1 时不要盲目等待直接触发快照拉取。快照接口返回的是完整会话状态和当前本地状态做一次合并乱序问题从根上解决。6.2 页面卡顿、ECharts 图表闪烁怎么解决卡顿的根源通常不是图表本身而是消息列表的每次更新带动了整个页面 state 变更图表组件间接被重新渲染。排查时可以打开 Performance 面板看长任务分布如果 Chart 组件渲染占总耗时比例很高就说明它被无关更新连坐了。我的解法有三个第一消息列表区域用 React.memo 隔离props 没变就不更新第二图表组件改用增量setOption而不是全量替换避免每次销毁重建第三图表只在窗口可见时才执行渲染配合content-visibility: auto可以把不可见区域的渲染成本降到零。图表闪烁问题在优化后基本消失。6.3 WebSocket 断线后如何找回上下文断线重连不只是“重新把连接建立起来”更要把断线期间错过的事件补回来。我采用的方案是前端持久化记录last_event_id重连成功后发送client.resume指令并带上这个标识。服务端收到后从该事件之后开始重放所有事件。如果事件量特别大服务端直接下发会话快照前端丢弃本地旧消息用快照整体替换。这里有个容易踩的坑重连成功瞬间用户可能正好发了一条新消息。如果client.resume和client.submit_input同时发出后端处理顺序不确定可能导致新消息被插入到重放事件流的中间。我在会话层做了串行处理重连成功后先等resume_ack再放行用户指令避免了这类竞态。6.4 超大上下文和超长文本的处理技巧长会话场景下前端不能把几千条消息全部渲染到 DOM。我采用了三层策略第一层消息列表虚拟滚动只渲染可视区附近的消息第二层单条消息超过 2000 字默认折叠展开时才渲染完整内容第三层历史消息里的工具输出过长时只展示摘要点击后通过 REST 接口拉取详情。在实际使用中这三个策略组合起来即使会话里有上百条包含大段代码和日志的消息页面也能保持流畅。我个人在实际操作中的体会是Agent AI 前端最核心的认知转变是不要把它当成一个“聊天页面”来写而要当成一个“流式事件驱动的执行控制台”来设计。协议和状态机的设计决定了后面所有优化是不是顺利。如果你正在做类似的架构建议先花两三天把消息协议和状态机定清楚再开始写组件。最后再分享一个小技巧发送打断指令client.interrupt时一定要带上当前正在执行的工具调用 ID否则后端可能不知道你要取消的是哪一个执行步骤。这个细节在早期联调时坑了我们整整一天。