1. 从一个被问烂了的问题说起Agent 到底要不要懂渲染这两年做 AI Agent 应用开发的人几乎都会在某个阶段撞上同一个困惑我到底该把精力放在 Agent 的编排逻辑上还是放在前端渲染上这个问题听起来像是两个不相干的领域硬凑在一起但只要你真正落地过一个带界面的 Agent 产品就会发现它俩的耦合程度远超想象。我先把这个问题的本质摊开讲。Agent 应用的核心是感知—决策—执行这条链路而渲染的核心是把状态变成人能看到的东西。问题在于Agent 的执行过程是流式的、异步的、可能长达几十秒甚至几分钟的而用户的眼睛是实时的、连续的、没有耐心的。这中间的落差就是所有 Agent 渲染难题的根源。举个最直观的例子。你让 Agent 去查一份资料、调用三个工具、最后生成一份报告。后端这边是tool_call→tool_result→thinking→output一串事件流前端这边用户看到的是什么如果只是转圈圈用户三十秒就跑了如果每个 token 都往屏幕上怼用户又会被闪烁和抖动搞得头晕。所以渲染策略直接决定了 Agent 产品的留存这不是夸张。这篇文章我想聊的不是某个具体框架的 API 怎么调而是把Agent 应用开发和渲染这两件事放在一起拆解它们之间的真实关系。适合谁看如果你正在做 Agent 产品的前端、正在设计 Agent 的事件协议、或者正在纠结要不要自己写渲染层那这篇应该能帮你少走一些弯路。我会从架构选型、事件流设计、具体渲染实现、性能排查几个角度展开尽量把踩过的坑都摊出来。2. Agent 与渲染的架构关系拆解2.1 为什么 Agent 应用天然是渲染敏感的传统 Web 应用的渲染模型很简单请求 → 响应 → 渲染。数据是批量的、离散的、有明确边界的。但 Agent 应用完全不是这个模型。Agent 的输出是增量式的它可能先吐一段思考再调一个工具工具返回后再吐一段中间还可能因为工具失败而回滚重来。这种边算边说的特性决定了渲染层必须能处理不完整、不确定、可能被推翻的状态。我见过太多团队一开始用最朴素的方式做等 Agent 全部跑完拿到完整结果再一次性渲染。这个方案在 demo 阶段没问题但一上生产就崩。原因很简单Agent 跑一次动辄十几秒用户盯着空白页面十几秒心理上已经判定这个产品卡死了。所以流式渲染不是锦上添花是 Agent 产品的生存底线。再往深一层想Agent 的渲染还面临一个传统应用没有的问题状态来源的多样性。一次 Agent 执行里状态可能来自模型输出的 token 流、工具调用的结构化返回、系统注入的中间事件、以及用户自己的输入。这四路状态要在同一个界面上协调呈现谁先谁后、谁覆盖谁、谁和谁合并都是设计问题。这就是为什么我说 Agent 开发和渲染是绑在一起的——你设计 Agent 事件协议的时候其实就在设计渲染的数据源。2.2 三种主流的 Agent 渲染架构选型落地的时候架构选型基本逃不出这三种模式我按复杂度和适用场景排一下。第一种单流式文本渲染。最简单Agent 的所有输出都当成一段 Markdown 文本流前端用类似markdown-it这样的解析器边收边渲染。优点是实现快缺点是当 Agent 要展示图表、表格、工具调用卡片时纯文本流就撑不住了。适合聊天型 Agent、问答型 Agent。第二种事件驱动的分块渲染。Agent 后端把执行过程拆成结构化事件thinking、tool_start、tool_end、text_delta、artifact等前端根据事件类型分发到不同的渲染组件。这是目前最主流的方案也是我推荐大多数团队采用的。它的核心是把渲染什么的决策从文本层上移到事件层前端只需要维护一个事件到组件的映射表。第三种状态机驱动的整体渲染。前端维护一个完整的 Agent 状态机每个事件都是状态转移的输入界面是状态的纯函数。这个方案最重但可控性最强适合多 Agent 协作、需要精确回放、需要断点续传的复杂场景。选哪种我的经验是先看你的 Agent 会不会调用工具。如果会直接排除第一种再看你的 Agent 执行会不会超过 30 秒。如果会第二种方案里必须加上中间态可视化否则用户还是会跑。第三种方案除非你有明确的回放或协作需求否则不要一上来就上维护成本很高。2.3 事件协议Agent 和渲染之间的合同这里我要重点讲一个容易被忽视的东西Agent 事件协议。它是后端 Agent 和前端渲染之间的合同设计得好不好直接决定渲染层能不能优雅地工作。一个合格的事件协议至少要包含这几个字段事件类型、事件 ID、时间戳、父事件 ID用于表达嵌套关系比如工具调用里嵌套了思考、以及 payload。我见过很多团队的事件协议只有type和data两个字段结果前端想做工具调用折叠展开的时候发现根本不知道哪个事件属于哪个工具只能靠顺序猜一遇到并发就乱套。提示事件协议一定要在项目早期定死并且写进文档。后期改协议的代价是前端所有渲染逻辑重写。还有一个细节事件要不要带序号。我的建议是必须带而且是单调递增的序号。因为流式传输在网络抖动时可能乱序到达前端靠序号可以做重排和去重。这个坑我在一个长连接项目里踩过Agent 输出的思考片段偶尔会前后颠倒排查了半天才发现是传输层乱序加上序号后问题立刻消失。3. 核心渲染环节的实操要点3.1 流式 Markdown 渲染别小看这件事Agent 输出 Markdown 是标配但流式渲染 Markdown 是个技术活。你不可能每收到一个字符就重新解析整篇文档那样性能会炸。正确的做法是增量解析 局部更新。具体怎么操作我一般用markdown-it这类解析器但不会直接用它渲染 HTML。而是维护一个已解析块列表每次收到新的文本增量只解析最后一个未闭合的块。比如当前正在写一个代码块那新来的字符就追加到代码块内容里不触发整篇重解析。只有当遇到块级分隔符比如空行、标题符号时才把当前块封口开一个新块。这里有个关键判断如何知道一个块是否闭合。Markdown 的块级语法是有明确边界的标题、列表、代码块、引用都有起始标记。你可以用一个轻量的状态机跟踪当前处于哪种块中遇到对应的结束条件就封口。这个状态机不复杂但一定要写否则你会遇到代码块还没结束就被当成普通段落渲染的经典 bug。另一个坑是代码高亮。流式渲染时代码块内容是不完整的你不能每来一个字符就重新高亮整块。我的做法是代码块在闭合前不高亮只做等宽字体展示闭合后再触发一次高亮。这样既避免了频繁重排又保证了最终效果。用户感知上几乎无差别因为代码块通常几秒内就写完了。3.2 工具调用卡片的渲染时机与状态管理工具调用是 Agent 渲染里最有戏的部分。一个工具调用从发起到返回中间有多个状态pending已发起未返回、running执行中、success、error、timeout。每个状态在界面上应该有明确的视觉区分。我的实操经验是工具卡片要在tool_start事件到达的瞬间就渲染出来而不是等结果。为什么因为用户需要知道Agent 正在干活一个显示正在查询数据库...的卡片比一个转圈圈能给用户强得多的确定感。卡片先以骨架屏或加载态出现等tool_end事件到达后再填充结果。状态管理上我建议给每个工具调用分配一个稳定的 ID前端用一个 Map 维护toolId → 卡片状态。这样即使事件乱序到达也能正确更新对应卡片。我踩过的坑是早期用数组存工具调用结果并发工具调用时后返回的结果覆盖了前一个卡片用户看到的是错乱的内容。改成 Map 后彻底解决。还有一个细节是工具调用的折叠。Agent 可能连续调用十几个工具如果全部展开界面会非常长。我的做法是默认只展开最近一个工具调用历史工具调用折叠成一行摘要比如已调用 搜索工具耗时 1.2s。用户可以手动展开查看详情。这个交互在长任务场景下体验提升非常明显。3.3 图表与可视化ECharts 闪烁问题的根治Agent 经常需要输出图表ECharts 是前端最常用的选择。但流式场景下ECharts 有个经典问题闪烁。原因是每次数据更新都调用setOption而setOption默认会重新计算布局、重绘整个图表数据频繁更新时就会看到明显的抖动。根治方案有三个层次。第一层合并更新。不要每来一个数据点就setOption而是用一个缓冲区收集每 100ms 或每积累 N 个点才更新一次。第二层使用notMerge: false和lazyUpdate: true。lazyUpdate会让 ECharts 在下一帧才真正更新避免同一帧内多次更新。第三层对于增量数据用appendData而不是setOption。appendData是专门为大数据量增量场景设计的性能比setOption高一个数量级。我实测下来一个每秒更新 50 个点的折线图用setOption会明显卡顿改用appendData加 100ms 节流后丝滑得完全看不出是流式数据。这里的关键认知是ECharts 的setOption是全量替换语义不是增量更新语义用错语义就会付出不必要的重绘代价。注意appendData只支持部分图表类型折线、散点等柱状图和饼图不支持。如果你的 Agent 要输出柱状图只能用节流 setOption的方案。3.4 3D 与卡通渲染在 Agent 场景的定位热词里出现了3d网页渲染、liltoon卡通渲染、unity shader npr 卡通渲染这些词说明有人在做带 3D 形象的 Agent。这块我要泼点冷水3D 渲染和 Agent 的逻辑渲染是两套完全独立的管线不要混在一起设计。Agent 的逻辑渲染文本、卡片、图表走的是 DOM 或 Canvas 2D而 3D 形象走的是 WebGL 或 Unity WebGL。它们之间只应该有一个薄薄的通信层Agent 的状态变化通过事件通知 3D 层3D 层根据状态切换动画比如思考中播放思考动画输出中播放说话动画。千万不要让 3D 层去解析 Agent 的文本流那是灾难。如果你确实要做卡通渲染的 Agent 形象NPR非真实感渲染是主流方向核心是描边 色阶量化 高光控制。但我要提醒的是WebGL 上的 NPR 性能开销不小移动端尤其吃紧。我的建议是形象层用预渲染的序列帧或 Lottie 动画把 3D 留给真正需要实时交互的场景。除非你的产品核心卖点就是 3D 形象否则不值得为它牺牲整体流畅度。4. 完整实操流程从事件流到界面4.1 后端事件流的构造与推送先讲后端。Agent 执行时我习惯用一个统一的EventEmitter把内部状态往外抛。每个事件都经过一个serialize函数转成前端能消费的 JSON。推送方式上短任务用 SSEServer-Sent Events就够了长任务和需要双向通信的场景用 WebSocket。SSE 的优势是简单、自动重连、天然支持文本流。我大多数 Agent 项目都用 SSE只有需要用户中途打断、或者多 Agent 协作需要双向通信时才上 WebSocket。这里有个细节SSE 的每条消息要带id字段这样断线重连时浏览器会自动带上Last-Event-ID后端可以据此补发丢失的事件。这个机制很多人不知道但它是 SSE 相比裸 WebSocket 的一大优势。事件推送的节奏也要控制。不要每生成一个 token 就推一次那样网络开销太大。我的做法是按时间窗口聚合每 50ms 把这段时间内产生的 token 合并成一个text_delta事件推送。用户感知上依然是实时的但网络请求数降低了一个数量级。4.2 前端事件消费与状态归并前端这边核心是一个事件消费循环。收到事件后先根据type分发再更新对应的状态容器。我一般会维护三个状态容器messages对话消息列表、toolCalls工具调用 Map、artifacts产物列表比如生成的图表、文件。状态归并的难点在于顺序和嵌套。比如一个text_delta事件它可能属于主对话流也可能属于某个工具调用的内部思考。怎么区分靠事件里的parentId。如果parentId为空就是主流程如果不为空就找到对应的工具调用卡片把文本追加到卡片内部。这个设计让工具调用内部的思考过程可以独立渲染用户展开卡片就能看到 Agent 在工具里想了什么。我踩过的一个坑是状态更新没有做批处理。早期每个事件到达都触发一次 React 重渲染Agent 输出快的时候一秒触发几十次界面直接卡死。后来引入requestAnimationFrame做批处理把一帧内的多次状态更新合并成一次渲染问题解决。这个优化在 React 18 的自动批处理下部分被内置了但跨异步边界的事件还是需要手动处理。4.3 渲染层的组件映射与降级策略渲染层我建议做成组件注册表的模式。维护一个eventType → Component的映射新事件类型来了就查表渲染。这样扩展新事件类型时只需要注册一个新组件不用改核心逻辑。降级策略也很重要。Agent 可能输出前端不认识的 Markdown 语法、不支持的图表类型、或者格式错误的 JSON。这时候不能白屏要有兜底。我的做法是Markdown 解析失败就降级为纯文本展示图表数据格式错误就展示一个数据格式异常的提示卡片同时把原始数据折叠在下面供排查JSON 解析失败就原样展示字符串。永远不要让渲染层的异常冒泡到整个应用一个组件崩了不能拖垮整个界面所以每个渲染组件外面都要包一层 Error Boundary。4.4 一个可复现的最小实现骨架我把核心逻辑抽成一个最小骨架你可以直接照着搭。后端伪代码def run_agent(query): emit({type: start, id: next_id(), ts: now()}) for chunk in agent_stream(query): if chunk.kind text: emit({type: text_delta, id: next_id(), ts: now(), text: chunk.text}) elif chunk.kind tool_start: emit({type: tool_start, id: chunk.tool_id, ts: now(), name: chunk.name, args: chunk.args}) elif chunk.kind tool_end: emit({type: tool_end, id: chunk.tool_id, ts: now(), result: chunk.result, status: chunk.status}) emit({type: end, id: next_id(), ts: now()})前端消费伪代码const state { messages: [], toolCalls: new Map(), artifacts: [] }; function consume(event) { switch (event.type) { case text_delta: appendText(state, event); break; case tool_start: state.toolCalls.set(event.id, { name: event.name, status: running, args: event.args }); break; case tool_end: const card state.toolCalls.get(event.id); if (card) { card.status event.status; card.result event.result; } break; } scheduleRender(); }这个骨架看起来简单但把前面讲的所有要点都覆盖了事件带 ID、工具调用用 Map、状态更新后统一调度渲染。你可以在此基础上加批处理、加降级、加折叠逐步演进。5. 常见问题与排查技巧实录5.1 渲染卡顿与闪烁的排查路径Agent 渲染卡顿排查顺序我总结成一张表按这个顺序查基本能定位到根因。现象可能原因排查方法解决方案整体界面卡顿状态更新过于频繁在渲染函数里打点计数用 rAF 批处理合并同帧更新图表闪烁setOption 全量重绘看 ECharts 更新调用频率改 appendData 或加节流文本抖动每字符重解析 Markdown看解析器调用次数增量解析只解析未闭合块滚动跳变新内容插入导致高度突变观察滚动位置用 scroll anchoring 或固定容器高度内存持续增长事件监听未清理看内存曲线组件卸载时移除监听Map 定期清理这张表是我从多个项目里攒出来的基本覆盖了 90% 的渲染问题。特别说一下滚动跳变这个最容易被忽视。Agent 流式输出时新内容不断插入如果用户正在往上翻看历史新内容会把视口顶下去体验极差。解决方案是检测用户是否在底部如果在底部就自动滚动如果用户手动上滑了就停止自动滚动并显示一个回到最新的按钮。5.2 长文本渲染的性能陷阱热词里有markdown-it 渲染大量文字说明很多人遇到了长文本渲染的性能问题。Agent 生成的报告动辄几千字如果一次性渲染成 DOM节点数会爆炸。我的处理策略是虚拟滚动 分块渲染。把长文本按段落或按标题切成块只渲染视口内的块。但这里有个坑Markdown 的块级元素高度是不固定的虚拟滚动需要动态测量高度。我一般用IntersectionObserver配合高度缓存测量过的块记住高度没测量过的先给一个估算高度滚动到附近再精确测量。这个方案实现起来有点复杂但如果你的 Agent 经常输出长文值得投入。另一个更轻量的方案是折叠 懒渲染。长文本默认只渲染前 N 个块用户点击展开全文再渲染剩余部分。这个方案实现简单适合大多数场景。我大多数项目用的都是这个只有确实需要连续滚动的场景才上虚拟滚动。5.3 Agent 并发场景下的渲染隔离ai agent 怎么扛并发是个高频问题但大多数人只关注后端并发忽略了前端渲染的并发问题。当用户同时发起多个 Agent 任务时多个事件流会同时到达前端如果状态管理没做好就会出现A 任务的输出跑到 B 任务的界面里这种串台。解决方案是给每个 Agent 任务分配独立的会话 ID所有事件都带上这个 ID前端按会话 ID 隔离状态。每个会话有独立的messages、toolCalls、artifacts。渲染时当前激活的会话才渲染其他会话的状态保留在内存里但不渲染。这样既保证了隔离又不会因为切换会话丢失状态。我踩过的坑是早期用全局单例存状态结果多任务并发时状态互相污染排查了很久才发现是状态没隔离。改成按会话 ID 分片存储后问题彻底解决。这个教训是Agent 应用的状态天然是多实例的从第一天就要按会话隔离设计。5.4 几个我反复踩的坑第一个坑事件没有终态标记。Agent 执行结束一定要发一个明确的end事件否则前端不知道什么时候停止 loading。我见过有的实现靠多久没收到事件就认为结束这个方案在慢工具调用时会误判。第二个坑错误事件被当成正常事件渲染。Agent 执行出错时后端要发error类型的事件前端要有专门的错误渲染组件。如果错误被当成普通文本渲染用户会看到一堆堆栈信息体验很差。第三个坑工具调用的参数和结果没有脱敏。工具调用可能包含敏感信息比如查询参数里的用户 ID渲染到界面上要谨慎。我的做法是工具参数和结果在渲染前过一层脱敏函数敏感字段用***替换。这个在面向 C 端的产品里尤其重要。第四个坑没有做渲染性能监控。上线后你不知道用户那边渲染是否流畅。我的做法是埋点上报事件到达时间和渲染完成时间算出差值作为渲染延迟指标。这个指标超过阈值就告警能提前发现性能退化。6. 我对 Agent 渲染这件事的几点个人判断做了这么多 Agent 项目我越来越觉得渲染不是 Agent 应用的附属品而是它的另一半。Agent 的智能体现在后端但用户感知到的智能几乎全部来自渲染层。一个响应及时、状态清晰、过渡自然的界面能让一个普通的 Agent 显得很聪明反过来一个卡顿、闪烁、状态混乱的界面能让一个强大的 Agent 显得很蠢。所以我的建议是在 Agent 项目立项时就把渲染方案和事件协议一起设计不要等后端跑通了再补前端。事件协议是两者的接口接口设计好了两边可以并行开发接口设计烂了后期返工的成本是双倍的。另外不要迷信全流式。有些内容适合流式比如思考过程、长文本有些内容适合等完整了再渲染比如结构化表格、图表。判断标准是这个内容在生成过程中用户看了有没有价值。思考过程有价值所以流式表格生成到一半没价值所以等完整。这个判断能帮你省下很多不必要的渲染复杂度。最后分享一个我最近在用的技巧给 Agent 的每个渲染块加一个淡入动画新内容出现时透明度从 0 到 1 过渡 150ms。这个微小的动画能极大缓解流式输出的跳变感让界面显得更柔和。成本几乎为零效果立竿见影你可以试试。