尧图网页设计 
1. 从一次线上事故说起Agent 和渲染为什么会扯上关系去年年底我接手了一个内部工具项目核心功能是让一个 Agent 自动分析用户上传的数据文件然后把分析结果以可视化图表的形式呈现出来。听起来很常规对吧Agent 负责数据处理和逻辑推理前端负责把结果画出来各司其职。但项目上线第三天就出问题了用户反馈图表偶尔会“卡住”页面显示空白刷新之后又正常。排查了两天才定位到根因——Agent 在流式输出中间结果时前端渲染层拿到了一份“半成品”数据图表库在解析这份不完整数据时抛了异常整个渲染树崩了。这件事让我开始认真思考一个平时容易被忽略的问题Agent 应用开发和渲染之间到底是什么关系很多做 Agent 的开发者把渲染当成“前端的事”做前端的又把 Agent 当成“后端的一个黑盒”两边各干各的结果在集成的时候问题集中爆发。实际上Agent 应用的渲染链路和传统 Web 应用有本质区别它涉及流式输出、状态不确定性、工具调用中间态、多轮对话上下文等一系列特殊因素这些因素直接决定了渲染层该怎么设计。这篇文章适合三类人看正在做 Agent 应用开发但被渲染问题困扰的工程师、做前端但需要对接 Agent 能力的开发者、以及正在设计 Agent 架构需要提前考虑渲染策略的技术负责人。我会从实际项目经验出发把 Agent 开发和渲染之间的耦合点一个个拆开讲清楚包括流式渲染的状态管理、工具调用结果的可视化策略、多 Agent 协作时的渲染调度、以及性能优化中那些文档里不会写的坑。2. Agent 输出为什么不能直接丢给渲染层2.1 流式输出的“半成品”问题传统 Web 应用的渲染逻辑很清晰后端返回完整数据前端拿到之后一次性渲染。但 Agent 应用的输出模式完全不同——它通常是流式的token 一个一个往外吐中间还夹杂着工具调用的请求和结果。这就导致渲染层拿到的东西天然是“不完整”的。我见过很多团队的做法是Agent 每输出一个 chunk前端就重新渲染一次。这在简单文本场景下勉强能用但一旦涉及结构化数据比如表格、图表、代码块问题就大了。举个例子Agent 正在输出一段 JSON 格式的分析结果前端拿到{name: test, val这样的半截数据JSON.parse 直接报错整个组件树崩溃。正确的做法是在 Agent 输出层和渲染层之间加一个缓冲与校验层。具体来说Agent 的流式输出先进入一个缓冲区缓冲区负责判断当前数据是否“可渲染”。对于纯文本可以按句子或段落为单位释放对于结构化数据必须等到完整的结构闭合比如 JSON 的括号匹配完成才触发渲染。这个缓冲层的实现方式取决于你的 Agent 框架但核心思路是一样的不要让渲染层直接消费原始流。# 一个简化的缓冲层示例 class RenderBuffer: def __init__(self): self.buffer self.structured_depth 0 def feed(self, chunk): self.buffer chunk # 检测结构化数据的嵌套深度 for char in chunk: if char in {[: self.structured_depth 1 elif char in }]: self.structured_depth - 1 # 只有结构闭合或纯文本段落完成时才释放 if self.structured_depth 0: return self.flush() return None def flush(self): data self.buffer self.buffer return data2.2 工具调用中间态的可视化需求Agent 和普通聊天机器人最大的区别在于它会调用工具。一次完整的工具调用包含多个阶段决定调用哪个工具、生成调用参数、等待工具返回、解析返回结果、基于结果继续推理。每个阶段都有不同的渲染需求。我刚开始做 Agent 应用的时候工具调用的中间态是直接隐藏的用户只看到最终结果。后来发现用户体验很差——Agent 在调用一个耗时较长的工具时页面没有任何反馈用户以为卡死了。后来改成显示一个简单的 loading 动画但还是不够因为用户不知道 Agent 在干什么。比较理想的做法是把工具调用的每个阶段都映射到具体的渲染状态。比如“正在搜索数据库”显示一个搜索图标加进度条“正在分析结果”显示一个思考中的动画“正在生成报告”显示打字机效果。这些状态需要 Agent 框架在输出时携带明确的阶段标记渲染层根据标记切换 UI。这里有个关键设计决策状态标记应该由 Agent 层输出而不是渲染层自己猜测。我见过一些实现是前端根据输出内容的关键词来猜 Agent 在干什么这种做法极其脆弱Agent 换个措辞就失效了。正确的做法是在 Agent 的输出协议里定义明确的状态字段。2.3 多轮对话中的渲染状态继承多轮对话场景下渲染层需要维护一个对话历史的状态树。每一轮对话可能包含文本、工具调用记录、结构化数据、错误信息等多种内容类型。当用户滚动查看历史消息时渲染层需要能够快速重建每一轮的状态。这里容易踩的坑是很多实现把每一轮对话的渲染状态存在组件内部当组件被虚拟滚动回收后再重新挂载时状态丢失了。解决方案是把渲染状态提升到全局 store 或者对话级别的状态管理中组件只负责根据状态渲染不持有状态。另外多轮对话中经常出现“引用上一轮结果”的情况。比如用户说“把刚才那个表格按第二列排序”Agent 需要理解“刚才那个表格”指的是哪一轮的哪个数据。渲染层需要给每个结构化数据块分配稳定的 IDAgent 在引用时通过 ID 定位。这个 ID 的生成和管理策略需要在 Agent 和渲染层之间达成一致。3. 渲染策略怎么选从文本流到富交互的完整光谱3.1 纯文本流式渲染的最小实现如果你的 Agent 应用只输出纯文本那渲染层的复杂度相对较低。但“纯文本”也有讲究。最粗糙的做法是每来一个 token 就 append 到 DOM 上这种做法在长文本场景下性能极差因为每次 append 都会触发浏览器的重排和重绘。稍微好一点的做法是用requestAnimationFrame做批量更新把一段时间内到达的 token 合并成一次 DOM 操作。但更好的做法是使用虚拟化技术只渲染可视区域内的文本。不过对于大多数 Agent 对话场景文本长度不会特别夸张用 rAF 批量更新加上合理的节流策略就足够了。// 用 rAF 做批量文本更新 let pendingText ; let rafScheduled false; function onTokenReceived(token) { pendingText token; if (!rafScheduled) { rafScheduled true; requestAnimationFrame(() { appendToDOM(pendingText); pendingText ; rafScheduled false; }); } }这里有个细节打字机效果的实现。很多产品喜欢让文本像打字一样逐字出现这需要控制渲染速度。但 Agent 的输出速度本身就不稳定有时候一秒吐几十个 token有时候几秒才吐一个。如果渲染层再做额外的延迟用户体验会很奇怪。我的建议是渲染速度跟随 Agent 输出速度只在输出过快时做上限控制不要人为添加延迟。3.2 结构化数据的渐进式渲染Agent 输出表格、列表、代码块等结构化数据时渐进式渲染是个挑战。你不能等到整个表格数据都到齐了才渲染那样用户等待时间太长但也不能拿到一行就渲染一行因为列宽和对齐会不断变化视觉上很跳。我的经验是采用骨架屏加渐进填充的策略。当检测到 Agent 开始输出结构化数据时先根据数据类型渲染一个骨架比如表格的列头和空行然后随着数据到达逐行填充。列宽在骨架阶段就根据列头文字估算好后续填充时不再调整避免布局抖动。对于代码块渐进式渲染需要特别处理语法高亮。如果每来一行就重新高亮整个代码块性能开销很大。可以用增量高亮的方式只高亮新增的行。另外代码块的自动滚动也需要处理——当代码行数超过可视区域时是自动滚动到底部还是保持当前位置我的做法是如果用户没有手动滚动过就自动跟随一旦用户手动滚动就停止自动跟随并显示一个“回到底部”的按钮。3.3 图表和可视化的延迟渲染Agent 生成图表数据时渲染层面临一个选择是等数据完全生成后再渲染图表还是边生成边渲染从技术上讲大多数图表库如 ECharts、Chart.js都支持动态更新数据但频繁更新会导致动画闪烁和性能问题。我的建议是对于图表类可视化等数据完全生成后再渲染中间用 loading 状态过渡。因为图表的视觉完整性很重要半成品图表反而会让用户困惑。但可以在数据生成过程中显示一个进度指示让用户知道 Agent 正在准备数据。如果 Agent 生成的是复杂的 3D 场景或大规模数据可视化渲染策略又不一样。这类场景通常需要 WebGL 或 Canvas 渲染初始化成本高不适合频繁重建。可以考虑在 Agent 开始生成数据时就预先初始化渲染上下文等数据到位后直接更新。3.4 不同渲染策略的对比与选型渲染策略适用场景优点缺点实现复杂度全量重渲染短文本、简单结构实现简单性能差、闪烁低流式追加纯文本对话实时感强结构化数据易崩低缓冲后渲染结构化数据稳定可靠有延迟感中渐进式渲染表格、列表平衡体验布局抖动风险高延迟渲染图表、3D视觉完整等待时间长中选型的核心原则是根据数据类型的确定性程度来选择。确定性高的数据纯文本可以用流式追加确定性低的数据结构化输出需要缓冲或渐进式处理。4. Agent 框架与渲染层的对接实战4.1 主流 Agent 框架的输出协议差异不同的 Agent 框架在输出协议上有很大差异这直接影响渲染层的对接方式。LangChain 的输出通常是链式调用的结果中间态需要通过 callback 捕获Dify 的输出是事件流格式有明确的事件类型标记CrewAI 的多 Agent 协作输出则更加复杂需要区分不同 Agent 的消息。我在项目里同时对接过 LangChain 和 Dify最大的感受是渲染层不应该直接依赖某个框架的输出格式而应该在中间做一层适配。适配层负责把不同框架的输出转换成统一的渲染指令。这样当框架升级或更换时渲染层不需要改动。# 统一的渲染指令格式 class RenderCommand: type: str # text, table, chart, code, tool_call, error content: any status: str # streaming, complete, error metadata: dict # 额外信息如工具名称、执行时间等 # LangChain 适配器 def adapt_langchain_output(event): if event.type llm_stream: return RenderCommand(typetext, contentevent.token, statusstreaming) elif event.type tool_start: return RenderCommand(typetool_call, contentevent.tool_name, statusstreaming) # ... # Dify 适配器 def adapt_dify_output(event): if event.event message: return RenderCommand(typetext, contentevent.answer, statusstreaming) elif event.event agent_thought: return RenderCommand(typetool_call, contentevent.tool, statusstreaming) # ...4.2 工具调用结果的可视化映射Agent 调用工具后返回的结果格式千差万别可能是纯文本、JSON、文件路径、图片 URL、甚至二进制数据。渲染层需要根据结果类型选择合适的展示方式。我的做法是建立一个结果类型到渲染组件的映射表。比如 JSON 结果用可折叠的树形组件展示图片 URL 用图片预览组件文件路径用文件卡片组件长文本用折叠面板。这个映射表可以配置化方便后续扩展。const resultRenderers { application/json: JsonTreeViewer, image/*: ImagePreview, text/plain: CollapsibleText, text/markdown: MarkdownRenderer, application/octet-stream: FileCard, }; function renderToolResult(result) { const mimeType detectMimeType(result); const Renderer resultRenderers[mimeType] || FallbackRenderer; return Renderer data{result} /; }这里有个容易忽略的点工具调用结果可能很大。比如 Agent 调用了一个搜索工具返回了 100 条结果。如果全部渲染出来页面会非常卡。需要做分页或虚拟滚动或者只展示摘要点击后展开详情。4.3 多 Agent 协作时的渲染调度多 Agent 场景下多个 Agent 可能同时输出内容渲染层需要决定如何展示这些并行的输出。我见过几种做法第一种是串行展示把多个 Agent 的输出按时间顺序排列像群聊一样。这种做法实现简单但当 Agent 数量多时消息会非常混乱。第二种是分栏展示每个 Agent 占一栏各自输出各自的内容。适合 Agent 角色分明的场景比如一个负责搜索、一个负责分析、一个负责总结。第三种是主从展示只展示主 Agent 的输出子 Agent 的输出折叠在详情里。适合层级分明的多 Agent 架构。我实际项目中用的是第二种加第三种混合主 Agent 的输出占据主区域子 Agent 的输出在侧边栏以时间线形式展示点击可以展开详情。这样既能看到全局进展又能深入查看细节。渲染调度还需要考虑输出优先级。当多个 Agent 同时输出时渲染层应该优先渲染主 Agent 的内容子 Agent 的内容可以降低更新频率。这需要在适配层给每个 RenderCommand 打上优先级标记。5. 性能优化那些文档里不会写的坑5.1 长对话的渲染性能衰减Agent 应用的一个特点是对话可能非常长尤其是当 Agent 执行复杂任务时一轮对话就可能产生几十条消息。随着对话轮次增加渲染性能会明显下降。我实测过一个案例对话到第 50 轮时页面滚动开始卡顿输入框响应延迟明显。排查后发现主要问题是 DOM 节点过多以及每次新消息到达时触发了全量重渲染。解决方案分三层第一层是虚拟滚动只渲染可视区域内的消息第二层是消息组件 memo 化避免无关消息的重渲染第三层是状态分片把对话状态按轮次分片存储新消息到达时只更新对应分片。虚拟滚动在 Agent 场景下有个特殊问题消息高度不固定。Agent 输出的内容长度差异很大有的消息只有一行有的消息包含一个大表格。这导致虚拟滚动的定位计算很复杂。我的做法是给每条消息估算一个初始高度渲染后测量实际高度并缓存滚动时用缓存的高度做定位。5.2 流式更新引发的重排风暴流式更新是 Agent 渲染的性能杀手。每来一个 token 就更新 DOM浏览器需要不断重排重绘。在低端设备上这会导致明显的卡顿和电池消耗。除了前面提到的 rAF 批量更新还有几个优化点使用containCSS 属性限制重排范围使用will-change提示浏览器提前优化避免在流式更新期间触发 layout thrashing比如频繁读取 offsetHeight。.message-streaming { contain: content; will-change: contents; }另一个容易被忽略的点是滚动位置的维护。流式更新时如果用户正在查看历史消息新内容的追加不应该影响用户的滚动位置。这需要在更新前记录滚动位置更新后恢复。但如果用户本来就在底部则应该自动跟随新内容。5.3 内存泄漏的隐蔽来源Agent 应用的内存泄漏有几个隐蔽来源。第一是事件监听器未清理尤其是 Agent 连接断开后相关的监听器没有移除。第二是定时器未清除比如打字机效果的定时器在组件卸载后仍在运行。第三是缓存未设上限比如渲染结果缓存、工具调用结果缓存随着对话进行不断增长。我踩过最坑的一个内存泄漏是Agent 的流式连接在组件重新挂载时没有正确关闭导致旧连接的回调仍然持有组件引用组件无法被 GC 回收。排查这个问题花了大半天最后用 Chrome 的 Memory 面板做堆快照对比才定位到。提示在 Agent 应用的开发阶段建议定期用 Chrome DevTools 的 Performance 和 Memory 面板做检查不要等到线上出问题才排查。5.4 渲染降级策略当 Agent 输出速度过快或数据量过大时渲染层需要有降级策略。比如当 token 到达速度超过阈值时自动切换到批量更新模式当单条消息内容超过一定长度时自动折叠并显示“展开全文”当检测到设备性能不足时关闭动画效果。这些降级策略应该是自动的不需要用户手动配置。实现方式可以是监听帧率当帧率持续低于阈值时触发降级。也可以根据设备信息如navigator.hardwareConcurrency预设降级级别。6. 几个真实项目中的决策复盘6.1 为什么最终选择了缓冲渲染而不是纯流式回到开头提到的那个线上事故最终的修复方案就是引入了缓冲层。具体来说Agent 的输出先进入一个队列队列根据内容类型决定释放策略纯文本按段落释放结构化数据等闭合后释放工具调用状态变化立即释放。这个方案带来的代价是用户感知到的延迟增加了。纯文本场景下用户看到第一个字的时间从原来的即时变成了等待一个段落完成。为了缓解这个问题我们在缓冲层加了一个“快速通道”如果缓冲区内容超过一定长度比如 50 个字符还没有遇到段落边界就强制释放一次。实测下来这个折中方案在稳定性和实时感之间取得了不错的平衡。线上事故率降为零用户对响应速度的投诉也没有增加。6.2 工具调用可视化从隐藏到全展示的演进最初我们的工具调用是完全隐藏的用户只看到最终答案。后来改成显示一个简单的“正在处理”提示。再后来改成显示工具名称和状态。最后演变成现在的完整时间线展示。这个演进过程让我意识到Agent 应用的透明度直接影响用户信任度。当用户能看到 Agent 在做什么、做到哪一步、遇到了什么问题他们对结果的接受度会高很多。即使 Agent 最终失败了用户也能理解失败的原因而不是觉得“这个 AI 不靠谱”。当然透明度也要适度。不是所有工具调用的细节都需要展示比如内部的向量检索过程、模型推理的中间步骤这些对用户没有意义。展示的重点应该是用户能理解的、与任务相关的操作。6.3 多 Agent 渲染调度的取舍在多 Agent 项目中我们最初尝试了完全并行的渲染方式每个 Agent 的输出独立更新。结果发现当 Agent 数量超过 3 个时页面更新非常混乱用户根本看不清发生了什么。后来改成了“主 Agent 驱动”的模式主 Agent 的输出决定整体节奏子 Agent 的输出作为补充信息在侧边栏展示。主 Agent 在关键节点会汇总子 Agent 的结果这样用户只需要关注主 Agent 的输出就能了解全局。这个决策的核心逻辑是渲染层的信息密度需要与用户的认知能力匹配。并行展示多个 Agent 的输出虽然技术上可行但用户处理不了那么多信息。串行化、层级化的展示方式更符合人的认知习惯。7. 从渲染反推 Agent 设计的几个思路做了一段时间 Agent 应用之后我发现渲染层的需求其实可以反过来指导 Agent 的设计。这里分享几个我在实践中总结的思路。第一个思路是让 Agent 输出“渲染友好”的数据格式。比如 Agent 在生成表格数据时不要输出一段 Markdown 表格文本让前端去解析而是直接输出结构化的 JSON 数据前端拿到后直接渲染。这样既减少了前端的解析负担也避免了格式解析错误。第二个思路是在 Agent 的输出协议里预留渲染提示字段。比如 Agent 可以标记某段内容是“重点”需要高亮某段内容是“警告”需要特殊样式某个工具调用是“关键步骤”需要突出展示。这些提示字段让渲染层能够更智能地呈现内容而不是一视同仁地渲染所有文本。第三个思路是把渲染状态纳入 Agent 的上下文。当用户滚动到某条历史消息并提问时Agent 应该知道用户当前关注的是哪部分内容。这需要渲染层把用户的交互状态滚动位置、点击的元素、选中的文本反馈给 Agent。这个反馈链路在很多实现里是缺失的导致 Agent 的回答与用户的当前关注点脱节。第四个思路是考虑渲染性能对 Agent 输出节奏的影响。如果渲染层处理不过来Agent 的输出速度应该适当降低。这需要 Agent 层能够接收渲染层的背压信号。虽然目前大多数 Agent 框架不支持这种双向流控但在自定义 Agent 实现中是可以做到的。8. 一些实用建议和踩坑记录最后分享一些零散但实用的经验都是实际项目中踩过的坑或者总结出来的技巧。关于流式文本的复制功能。流式输出时用户可能想复制已经显示的部分文本。但如果文本还在更新复制的内容可能不完整。我的做法是在流式输出期间禁用复制或者复制时提示“内容仍在生成中”。另外流式文本的选区在更新时会被重置这需要特殊处理——在更新 DOM 前保存选区更新后恢复。关于代码块的渲染。Agent 输出的代码块经常有格式问题比如缩进不一致、语言标记缺失。渲染层需要做容错处理语言标记缺失时自动检测缩进不一致时用代码格式化工具处理。但要注意自动格式化可能改变代码语义所以只做展示层的格式化不影响复制出来的内容。关于错误状态的渲染。Agent 执行失败时渲染层需要展示错误信息。但错误信息往往包含技术细节直接展示给用户不友好。我的做法是分层展示用户看到的是友好的错误提示点击“详情”可以看到技术细节。同时错误信息应该包含可操作的建议比如“请检查网络连接后重试”而不是“Error: ECONNREFUSED”。关于移动端的适配。Agent 应用在移动端的渲染挑战更大屏幕小、性能有限。我的建议是移动端默认使用更保守的渲染策略关闭复杂动画、减少同时渲染的消息数量、使用更简单的可视化组件。另外移动端的输入框和滚动区域的交互需要特别处理避免键盘弹出时布局错乱。关于无障碍访问。Agent 应用的动态内容更新对屏幕阅读器不友好。需要给流式更新的区域加上aria-live属性让屏幕阅读器能够感知内容变化。但要注意aria-liveassertive会打断用户当前的操作对于频繁更新的流式内容用aria-livepolite更合适。关于测试。Agent 渲染层的测试比普通前端组件复杂得多因为输入是不确定的流式数据。我的做法是录制真实的 Agent 输出流在测试中回放这些流验证渲染结果。同时要测试边界情况空输出、超长输出、包含特殊字符的输出、快速连续的工具调用等。这些经验都是在实际项目中一点点积累的有些是踩坑之后的教训有些是优化过程中的发现。Agent 应用开发和渲染的关系还在不断演进随着 Agent 能力的增强和应用场景的扩展渲染层需要解决的问题也会不断变化。但核心原则是不变的渲染层要理解 Agent 输出的特殊性在实时性、稳定性和性能之间找到适合具体场景的平衡点。 Agent应用开发与渲染层对接实战：流式输出、状态管理与性能优化
1. 从一次线上事故说起Agent 和渲染为什么会扯上关系去年年底我接手了一个内部工具项目核心功能是让一个 Agent 自动分析用户上传的数据文件然后把分析结果以可视化图表的形式呈现出来。听起来很常规对吧Agent 负责数据处理和逻辑推理前端负责把结果画出来各司其职。但项目上线第三天就出问题了用户反馈图表偶尔会“卡住”页面显示空白刷新之后又正常。排查了两天才定位到根因——Agent 在流式输出中间结果时前端渲染层拿到了一份“半成品”数据图表库在解析这份不完整数据时抛了异常整个渲染树崩了。这件事让我开始认真思考一个平时容易被忽略的问题Agent 应用开发和渲染之间到底是什么关系很多做 Agent 的开发者把渲染当成“前端的事”做前端的又把 Agent 当成“后端的一个黑盒”两边各干各的结果在集成的时候问题集中爆发。实际上Agent 应用的渲染链路和传统 Web 应用有本质区别它涉及流式输出、状态不确定性、工具调用中间态、多轮对话上下文等一系列特殊因素这些因素直接决定了渲染层该怎么设计。这篇文章适合三类人看正在做 Agent 应用开发但被渲染问题困扰的工程师、做前端但需要对接 Agent 能力的开发者、以及正在设计 Agent 架构需要提前考虑渲染策略的技术负责人。我会从实际项目经验出发把 Agent 开发和渲染之间的耦合点一个个拆开讲清楚包括流式渲染的状态管理、工具调用结果的可视化策略、多 Agent 协作时的渲染调度、以及性能优化中那些文档里不会写的坑。2. Agent 输出为什么不能直接丢给渲染层2.1 流式输出的“半成品”问题传统 Web 应用的渲染逻辑很清晰后端返回完整数据前端拿到之后一次性渲染。但 Agent 应用的输出模式完全不同——它通常是流式的token 一个一个往外吐中间还夹杂着工具调用的请求和结果。这就导致渲染层拿到的东西天然是“不完整”的。我见过很多团队的做法是Agent 每输出一个 chunk前端就重新渲染一次。这在简单文本场景下勉强能用但一旦涉及结构化数据比如表格、图表、代码块问题就大了。举个例子Agent 正在输出一段 JSON 格式的分析结果前端拿到{name: test, val这样的半截数据JSON.parse 直接报错整个组件树崩溃。正确的做法是在 Agent 输出层和渲染层之间加一个缓冲与校验层。具体来说Agent 的流式输出先进入一个缓冲区缓冲区负责判断当前数据是否“可渲染”。对于纯文本可以按句子或段落为单位释放对于结构化数据必须等到完整的结构闭合比如 JSON 的括号匹配完成才触发渲染。这个缓冲层的实现方式取决于你的 Agent 框架但核心思路是一样的不要让渲染层直接消费原始流。# 一个简化的缓冲层示例 class RenderBuffer: def __init__(self): self.buffer self.structured_depth 0 def feed(self, chunk): self.buffer chunk # 检测结构化数据的嵌套深度 for char in chunk: if char in {[: self.structured_depth 1 elif char in }]: self.structured_depth - 1 # 只有结构闭合或纯文本段落完成时才释放 if self.structured_depth 0: return self.flush() return None def flush(self): data self.buffer self.buffer return data2.2 工具调用中间态的可视化需求Agent 和普通聊天机器人最大的区别在于它会调用工具。一次完整的工具调用包含多个阶段决定调用哪个工具、生成调用参数、等待工具返回、解析返回结果、基于结果继续推理。每个阶段都有不同的渲染需求。我刚开始做 Agent 应用的时候工具调用的中间态是直接隐藏的用户只看到最终结果。后来发现用户体验很差——Agent 在调用一个耗时较长的工具时页面没有任何反馈用户以为卡死了。后来改成显示一个简单的 loading 动画但还是不够因为用户不知道 Agent 在干什么。比较理想的做法是把工具调用的每个阶段都映射到具体的渲染状态。比如“正在搜索数据库”显示一个搜索图标加进度条“正在分析结果”显示一个思考中的动画“正在生成报告”显示打字机效果。这些状态需要 Agent 框架在输出时携带明确的阶段标记渲染层根据标记切换 UI。这里有个关键设计决策状态标记应该由 Agent 层输出而不是渲染层自己猜测。我见过一些实现是前端根据输出内容的关键词来猜 Agent 在干什么这种做法极其脆弱Agent 换个措辞就失效了。正确的做法是在 Agent 的输出协议里定义明确的状态字段。2.3 多轮对话中的渲染状态继承多轮对话场景下渲染层需要维护一个对话历史的状态树。每一轮对话可能包含文本、工具调用记录、结构化数据、错误信息等多种内容类型。当用户滚动查看历史消息时渲染层需要能够快速重建每一轮的状态。这里容易踩的坑是很多实现把每一轮对话的渲染状态存在组件内部当组件被虚拟滚动回收后再重新挂载时状态丢失了。解决方案是把渲染状态提升到全局 store 或者对话级别的状态管理中组件只负责根据状态渲染不持有状态。另外多轮对话中经常出现“引用上一轮结果”的情况。比如用户说“把刚才那个表格按第二列排序”Agent 需要理解“刚才那个表格”指的是哪一轮的哪个数据。渲染层需要给每个结构化数据块分配稳定的 IDAgent 在引用时通过 ID 定位。这个 ID 的生成和管理策略需要在 Agent 和渲染层之间达成一致。3. 渲染策略怎么选从文本流到富交互的完整光谱3.1 纯文本流式渲染的最小实现如果你的 Agent 应用只输出纯文本那渲染层的复杂度相对较低。但“纯文本”也有讲究。最粗糙的做法是每来一个 token 就 append 到 DOM 上这种做法在长文本场景下性能极差因为每次 append 都会触发浏览器的重排和重绘。稍微好一点的做法是用requestAnimationFrame做批量更新把一段时间内到达的 token 合并成一次 DOM 操作。但更好的做法是使用虚拟化技术只渲染可视区域内的文本。不过对于大多数 Agent 对话场景文本长度不会特别夸张用 rAF 批量更新加上合理的节流策略就足够了。// 用 rAF 做批量文本更新 let pendingText ; let rafScheduled false; function onTokenReceived(token) { pendingText token; if (!rafScheduled) { rafScheduled true; requestAnimationFrame(() { appendToDOM(pendingText); pendingText ; rafScheduled false; }); } }这里有个细节打字机效果的实现。很多产品喜欢让文本像打字一样逐字出现这需要控制渲染速度。但 Agent 的输出速度本身就不稳定有时候一秒吐几十个 token有时候几秒才吐一个。如果渲染层再做额外的延迟用户体验会很奇怪。我的建议是渲染速度跟随 Agent 输出速度只在输出过快时做上限控制不要人为添加延迟。3.2 结构化数据的渐进式渲染Agent 输出表格、列表、代码块等结构化数据时渐进式渲染是个挑战。你不能等到整个表格数据都到齐了才渲染那样用户等待时间太长但也不能拿到一行就渲染一行因为列宽和对齐会不断变化视觉上很跳。我的经验是采用骨架屏加渐进填充的策略。当检测到 Agent 开始输出结构化数据时先根据数据类型渲染一个骨架比如表格的列头和空行然后随着数据到达逐行填充。列宽在骨架阶段就根据列头文字估算好后续填充时不再调整避免布局抖动。对于代码块渐进式渲染需要特别处理语法高亮。如果每来一行就重新高亮整个代码块性能开销很大。可以用增量高亮的方式只高亮新增的行。另外代码块的自动滚动也需要处理——当代码行数超过可视区域时是自动滚动到底部还是保持当前位置我的做法是如果用户没有手动滚动过就自动跟随一旦用户手动滚动就停止自动跟随并显示一个“回到底部”的按钮。3.3 图表和可视化的延迟渲染Agent 生成图表数据时渲染层面临一个选择是等数据完全生成后再渲染图表还是边生成边渲染从技术上讲大多数图表库如 ECharts、Chart.js都支持动态更新数据但频繁更新会导致动画闪烁和性能问题。我的建议是对于图表类可视化等数据完全生成后再渲染中间用 loading 状态过渡。因为图表的视觉完整性很重要半成品图表反而会让用户困惑。但可以在数据生成过程中显示一个进度指示让用户知道 Agent 正在准备数据。如果 Agent 生成的是复杂的 3D 场景或大规模数据可视化渲染策略又不一样。这类场景通常需要 WebGL 或 Canvas 渲染初始化成本高不适合频繁重建。可以考虑在 Agent 开始生成数据时就预先初始化渲染上下文等数据到位后直接更新。3.4 不同渲染策略的对比与选型渲染策略适用场景优点缺点实现复杂度全量重渲染短文本、简单结构实现简单性能差、闪烁低流式追加纯文本对话实时感强结构化数据易崩低缓冲后渲染结构化数据稳定可靠有延迟感中渐进式渲染表格、列表平衡体验布局抖动风险高延迟渲染图表、3D视觉完整等待时间长中选型的核心原则是根据数据类型的确定性程度来选择。确定性高的数据纯文本可以用流式追加确定性低的数据结构化输出需要缓冲或渐进式处理。4. Agent 框架与渲染层的对接实战4.1 主流 Agent 框架的输出协议差异不同的 Agent 框架在输出协议上有很大差异这直接影响渲染层的对接方式。LangChain 的输出通常是链式调用的结果中间态需要通过 callback 捕获Dify 的输出是事件流格式有明确的事件类型标记CrewAI 的多 Agent 协作输出则更加复杂需要区分不同 Agent 的消息。我在项目里同时对接过 LangChain 和 Dify最大的感受是渲染层不应该直接依赖某个框架的输出格式而应该在中间做一层适配。适配层负责把不同框架的输出转换成统一的渲染指令。这样当框架升级或更换时渲染层不需要改动。# 统一的渲染指令格式 class RenderCommand: type: str # text, table, chart, code, tool_call, error content: any status: str # streaming, complete, error metadata: dict # 额外信息如工具名称、执行时间等 # LangChain 适配器 def adapt_langchain_output(event): if event.type llm_stream: return RenderCommand(typetext, contentevent.token, statusstreaming) elif event.type tool_start: return RenderCommand(typetool_call, contentevent.tool_name, statusstreaming) # ... # Dify 适配器 def adapt_dify_output(event): if event.event message: return RenderCommand(typetext, contentevent.answer, statusstreaming) elif event.event agent_thought: return RenderCommand(typetool_call, contentevent.tool, statusstreaming) # ...4.2 工具调用结果的可视化映射Agent 调用工具后返回的结果格式千差万别可能是纯文本、JSON、文件路径、图片 URL、甚至二进制数据。渲染层需要根据结果类型选择合适的展示方式。我的做法是建立一个结果类型到渲染组件的映射表。比如 JSON 结果用可折叠的树形组件展示图片 URL 用图片预览组件文件路径用文件卡片组件长文本用折叠面板。这个映射表可以配置化方便后续扩展。const resultRenderers { application/json: JsonTreeViewer, image/*: ImagePreview, text/plain: CollapsibleText, text/markdown: MarkdownRenderer, application/octet-stream: FileCard, }; function renderToolResult(result) { const mimeType detectMimeType(result); const Renderer resultRenderers[mimeType] || FallbackRenderer; return Renderer data{result} /; }这里有个容易忽略的点工具调用结果可能很大。比如 Agent 调用了一个搜索工具返回了 100 条结果。如果全部渲染出来页面会非常卡。需要做分页或虚拟滚动或者只展示摘要点击后展开详情。4.3 多 Agent 协作时的渲染调度多 Agent 场景下多个 Agent 可能同时输出内容渲染层需要决定如何展示这些并行的输出。我见过几种做法第一种是串行展示把多个 Agent 的输出按时间顺序排列像群聊一样。这种做法实现简单但当 Agent 数量多时消息会非常混乱。第二种是分栏展示每个 Agent 占一栏各自输出各自的内容。适合 Agent 角色分明的场景比如一个负责搜索、一个负责分析、一个负责总结。第三种是主从展示只展示主 Agent 的输出子 Agent 的输出折叠在详情里。适合层级分明的多 Agent 架构。我实际项目中用的是第二种加第三种混合主 Agent 的输出占据主区域子 Agent 的输出在侧边栏以时间线形式展示点击可以展开详情。这样既能看到全局进展又能深入查看细节。渲染调度还需要考虑输出优先级。当多个 Agent 同时输出时渲染层应该优先渲染主 Agent 的内容子 Agent 的内容可以降低更新频率。这需要在适配层给每个 RenderCommand 打上优先级标记。5. 性能优化那些文档里不会写的坑5.1 长对话的渲染性能衰减Agent 应用的一个特点是对话可能非常长尤其是当 Agent 执行复杂任务时一轮对话就可能产生几十条消息。随着对话轮次增加渲染性能会明显下降。我实测过一个案例对话到第 50 轮时页面滚动开始卡顿输入框响应延迟明显。排查后发现主要问题是 DOM 节点过多以及每次新消息到达时触发了全量重渲染。解决方案分三层第一层是虚拟滚动只渲染可视区域内的消息第二层是消息组件 memo 化避免无关消息的重渲染第三层是状态分片把对话状态按轮次分片存储新消息到达时只更新对应分片。虚拟滚动在 Agent 场景下有个特殊问题消息高度不固定。Agent 输出的内容长度差异很大有的消息只有一行有的消息包含一个大表格。这导致虚拟滚动的定位计算很复杂。我的做法是给每条消息估算一个初始高度渲染后测量实际高度并缓存滚动时用缓存的高度做定位。5.2 流式更新引发的重排风暴流式更新是 Agent 渲染的性能杀手。每来一个 token 就更新 DOM浏览器需要不断重排重绘。在低端设备上这会导致明显的卡顿和电池消耗。除了前面提到的 rAF 批量更新还有几个优化点使用containCSS 属性限制重排范围使用will-change提示浏览器提前优化避免在流式更新期间触发 layout thrashing比如频繁读取 offsetHeight。.message-streaming { contain: content; will-change: contents; }另一个容易被忽略的点是滚动位置的维护。流式更新时如果用户正在查看历史消息新内容的追加不应该影响用户的滚动位置。这需要在更新前记录滚动位置更新后恢复。但如果用户本来就在底部则应该自动跟随新内容。5.3 内存泄漏的隐蔽来源Agent 应用的内存泄漏有几个隐蔽来源。第一是事件监听器未清理尤其是 Agent 连接断开后相关的监听器没有移除。第二是定时器未清除比如打字机效果的定时器在组件卸载后仍在运行。第三是缓存未设上限比如渲染结果缓存、工具调用结果缓存随着对话进行不断增长。我踩过最坑的一个内存泄漏是Agent 的流式连接在组件重新挂载时没有正确关闭导致旧连接的回调仍然持有组件引用组件无法被 GC 回收。排查这个问题花了大半天最后用 Chrome 的 Memory 面板做堆快照对比才定位到。提示在 Agent 应用的开发阶段建议定期用 Chrome DevTools 的 Performance 和 Memory 面板做检查不要等到线上出问题才排查。5.4 渲染降级策略当 Agent 输出速度过快或数据量过大时渲染层需要有降级策略。比如当 token 到达速度超过阈值时自动切换到批量更新模式当单条消息内容超过一定长度时自动折叠并显示“展开全文”当检测到设备性能不足时关闭动画效果。这些降级策略应该是自动的不需要用户手动配置。实现方式可以是监听帧率当帧率持续低于阈值时触发降级。也可以根据设备信息如navigator.hardwareConcurrency预设降级级别。6. 几个真实项目中的决策复盘6.1 为什么最终选择了缓冲渲染而不是纯流式回到开头提到的那个线上事故最终的修复方案就是引入了缓冲层。具体来说Agent 的输出先进入一个队列队列根据内容类型决定释放策略纯文本按段落释放结构化数据等闭合后释放工具调用状态变化立即释放。这个方案带来的代价是用户感知到的延迟增加了。纯文本场景下用户看到第一个字的时间从原来的即时变成了等待一个段落完成。为了缓解这个问题我们在缓冲层加了一个“快速通道”如果缓冲区内容超过一定长度比如 50 个字符还没有遇到段落边界就强制释放一次。实测下来这个折中方案在稳定性和实时感之间取得了不错的平衡。线上事故率降为零用户对响应速度的投诉也没有增加。6.2 工具调用可视化从隐藏到全展示的演进最初我们的工具调用是完全隐藏的用户只看到最终答案。后来改成显示一个简单的“正在处理”提示。再后来改成显示工具名称和状态。最后演变成现在的完整时间线展示。这个演进过程让我意识到Agent 应用的透明度直接影响用户信任度。当用户能看到 Agent 在做什么、做到哪一步、遇到了什么问题他们对结果的接受度会高很多。即使 Agent 最终失败了用户也能理解失败的原因而不是觉得“这个 AI 不靠谱”。当然透明度也要适度。不是所有工具调用的细节都需要展示比如内部的向量检索过程、模型推理的中间步骤这些对用户没有意义。展示的重点应该是用户能理解的、与任务相关的操作。6.3 多 Agent 渲染调度的取舍在多 Agent 项目中我们最初尝试了完全并行的渲染方式每个 Agent 的输出独立更新。结果发现当 Agent 数量超过 3 个时页面更新非常混乱用户根本看不清发生了什么。后来改成了“主 Agent 驱动”的模式主 Agent 的输出决定整体节奏子 Agent 的输出作为补充信息在侧边栏展示。主 Agent 在关键节点会汇总子 Agent 的结果这样用户只需要关注主 Agent 的输出就能了解全局。这个决策的核心逻辑是渲染层的信息密度需要与用户的认知能力匹配。并行展示多个 Agent 的输出虽然技术上可行但用户处理不了那么多信息。串行化、层级化的展示方式更符合人的认知习惯。7. 从渲染反推 Agent 设计的几个思路做了一段时间 Agent 应用之后我发现渲染层的需求其实可以反过来指导 Agent 的设计。这里分享几个我在实践中总结的思路。第一个思路是让 Agent 输出“渲染友好”的数据格式。比如 Agent 在生成表格数据时不要输出一段 Markdown 表格文本让前端去解析而是直接输出结构化的 JSON 数据前端拿到后直接渲染。这样既减少了前端的解析负担也避免了格式解析错误。第二个思路是在 Agent 的输出协议里预留渲染提示字段。比如 Agent 可以标记某段内容是“重点”需要高亮某段内容是“警告”需要特殊样式某个工具调用是“关键步骤”需要突出展示。这些提示字段让渲染层能够更智能地呈现内容而不是一视同仁地渲染所有文本。第三个思路是把渲染状态纳入 Agent 的上下文。当用户滚动到某条历史消息并提问时Agent 应该知道用户当前关注的是哪部分内容。这需要渲染层把用户的交互状态滚动位置、点击的元素、选中的文本反馈给 Agent。这个反馈链路在很多实现里是缺失的导致 Agent 的回答与用户的当前关注点脱节。第四个思路是考虑渲染性能对 Agent 输出节奏的影响。如果渲染层处理不过来Agent 的输出速度应该适当降低。这需要 Agent 层能够接收渲染层的背压信号。虽然目前大多数 Agent 框架不支持这种双向流控但在自定义 Agent 实现中是可以做到的。8. 一些实用建议和踩坑记录最后分享一些零散但实用的经验都是实际项目中踩过的坑或者总结出来的技巧。关于流式文本的复制功能。流式输出时用户可能想复制已经显示的部分文本。但如果文本还在更新复制的内容可能不完整。我的做法是在流式输出期间禁用复制或者复制时提示“内容仍在生成中”。另外流式文本的选区在更新时会被重置这需要特殊处理——在更新 DOM 前保存选区更新后恢复。关于代码块的渲染。Agent 输出的代码块经常有格式问题比如缩进不一致、语言标记缺失。渲染层需要做容错处理语言标记缺失时自动检测缩进不一致时用代码格式化工具处理。但要注意自动格式化可能改变代码语义所以只做展示层的格式化不影响复制出来的内容。关于错误状态的渲染。Agent 执行失败时渲染层需要展示错误信息。但错误信息往往包含技术细节直接展示给用户不友好。我的做法是分层展示用户看到的是友好的错误提示点击“详情”可以看到技术细节。同时错误信息应该包含可操作的建议比如“请检查网络连接后重试”而不是“Error: ECONNREFUSED”。关于移动端的适配。Agent 应用在移动端的渲染挑战更大屏幕小、性能有限。我的建议是移动端默认使用更保守的渲染策略关闭复杂动画、减少同时渲染的消息数量、使用更简单的可视化组件。另外移动端的输入框和滚动区域的交互需要特别处理避免键盘弹出时布局错乱。关于无障碍访问。Agent 应用的动态内容更新对屏幕阅读器不友好。需要给流式更新的区域加上aria-live属性让屏幕阅读器能够感知内容变化。但要注意aria-liveassertive会打断用户当前的操作对于频繁更新的流式内容用aria-livepolite更合适。关于测试。Agent 渲染层的测试比普通前端组件复杂得多因为输入是不确定的流式数据。我的做法是录制真实的 Agent 输出流在测试中回放这些流验证渲染结果。同时要测试边界情况空输出、超长输出、包含特殊字符的输出、快速连续的工具调用等。这些经验都是在实际项目中一点点积累的有些是踩坑之后的教训有些是优化过程中的发现。Agent 应用开发和渲染的关系还在不断演进随着 Agent 能力的增强和应用场景的扩展渲染层需要解决的问题也会不断变化。但核心原则是不变的渲染层要理解 Agent 输出的特殊性在实时性、稳定性和性能之间找到适合具体场景的平衡点。