从AI对话Demo到企业级Agent平台：流式输出与工具调用的演进之路

前阵子有个做企业服务的客户拿我们的 AI 对话 Demo 去现场演示回来跟我说了一句话聊得挺好但它啥也干不了。这句话我记到现在。一个能流式输出、能连续追问、还能切换话题的 Demo 看似已经很完整可真到要用它解决实际问题的时候你会发现它既没有手也没有脚——不会查数据库、不会调内部接口、不会按流程办事甚至连记性都只有上下文窗口那么大。这篇是从 AI 对话 Demo 到可演进的 Agent 平台系列的开篇我想把我们从一版用于演示的聊天页面逐步演进成一个企业级 Agent 平台的过程、踩坑和设计取舍完整地写出来。如果你正在做 AI 应用落地尤其是想把对话能力升级成生产力工具的团队这篇应该对你有用。1. 从能聊天到能干活Demo 的真正局限在哪里1.1 我们最初那版 Demo 的样子先还原一下起点。我们的第一版 Demo 很简单前端用 Vue 写了一个聊天页面后端对接大模型接口通过 SSE 把内容流式推给前端。用户每发一句话前端把历史消息拼进上下文一起发过去模型流式返回页面逐字渲染。为了演示效果好我们还预设了几个提示词模板比如用一段话总结这段文字按三步解释这个概念。这版 Demo 拿去演示的时候体验其实相当不错。响应快、字是一段一段蹦出来的视觉上很有智能感连续对话也能接住上一句的内容。但说白了它本质上就是一个带聊天界面的模型 API 封装所有能力都停留在语言层面——模型说什么页面就显示什么没有任何动作发生。当时的我还没有意识到这种语言上的智能和业务上的智能之间隔着一道巨大的鸿沟。1.2 Demo 失效的三个典型场景后来我们在真实客户现场试跑连续碰到了三个场景直接把 Demo 的底裤掀了。第一个是数据问答。客户问上季度华东区签约了多少合同模型一本正经地答了一串数字但那是它编的。它根本不知道我们系统里有什么数据更别说怎么查了。我们当时只能尴尬地解释这只是 Demo数据没接。第二个是任务执行。客户说帮我在 OA 里建一个采购申请单金额走审批流。模型回复好的我已经理解了你的需求。然后就没有然后了。它既不会调建单接口也不会处理审批流回调。第三个是长周期协作。客户问能不能每天早上九点自动跑一次销售日报推给我这就不是模型能回答的问题了它连定时这个概念都没有落地的载体。这三个场景其实代表着 Agent 平台必须具备的三类能力工具调用查数据、调接口、任务编排按流程办事、状态与调度记住约定、按时执行。而我们的 Demo一样都没有。1.3 Demo、原型和平台之间的边界吃了一次亏之后我认真梳理了 Demo、原型和平台的区别建议每个做 AI 项目的团队都先把这个边界想清楚否则后面全是返工。维度Demo原型平台目标验证能不能验证怎么用支撑一直用用户演示对象内部/种子用户真实业务用户数据假数据/预设部分真实数据全量真实数据容错可人工兜底允许少量 bug必须稳定可观测扩展性不考虑预留接口模块化、可演进安全合规不涉及基本权限完整权限与审计能演示和能用之间隔着的是一个完整的工程体系。但这里有一个重要的判断你不需要一上来就奔着平台去Demo 的核心价值是低成本试错。所以关键不是不要做 Demo而是做 Demo 的同时要清楚知道它哪些部分是一次性的哪些部分是要留下来继续生长的。我们在做第一版 Demo 的时候至少把三样东西留对了前端流式渲染组件、SSE 通信协议、会话上下文管理。这三样在后面的平台里原封不动地沿用了下来。所以我的建议是Demo 阶段多想想哪些代码将来会被生产环境羞辱提前把那部分写干净。2. 一场流式输出引发的血案标签截断与半句话问题2.1 现象Markdown 渲染到一半就断了团队在开发流式对话功能时遇到了一个特别典型的问题用户问一个问题模型回答的内容是一段带 Markdown 的文本前端在流式渲染过程中经常出现标签不完整的情况。最常见的就是代码块——模型已经说了python但内容还没输出完前端就把这个标签渲染出去了导致整段代码变成了普通文本更严重的是如果模型输出的是结构化 JSON前端在流式解析时直接报错因为 JSON 才解析了一半。当时团队有人提议干脆等整个回答结束再渲染算了。这个提议差点被执行因为从体验角度流式输出是 AI 对话最容易让用户感受到它在思考的交互方式等完整输出会明显拉长首屏等待时间尤其长回答会让人以为系统卡了。2.2 根本原因你没有设计增量协议后来我排查代码时发现问题不在于流式本身而在于我们根本没有设计增量协议。SSEServer-Sent Events只是在传输层把数据一块一块推过来但每一块数据应该是什么形态、前端拿到之后怎么处理很多人是没想清楚的。流式输出有三个层次。第一层是块级传输后端把 token 或文本片段直接抛给前端什么都不管。第二层是事件级协议不同的消息用事件名区分比如delta增量内容、tool_call工具调用、done结束。第三层是状态级还原前端根据事件流在本地维护一个可恢复的状态机无论中间断在哪一帧都能正确回退或补齐。我们的问题就出在第一层。文本分片到达前端时你可能刚好切在 Markdown 标签中间前端拿到半个python就开始渲染自然会出错。这不是 bug而是流式传输的天然特性——你拿到的一定是不完整的全貌你要做的不是假装它完整而是建立一套缓冲与还原机制。2.3 我们的解决方案缓冲、增量与后处理我给的方案分成三步。第一步前端不再逐字渲染最新一帧的文本而是维护一个content buffer结构。凡是可能被截断的语法单元Markdown 的围栏、HTML 标签、JSON 的引号都先放进 buffer等语法完整了再合并进 content。// SSE 接收端buffer 增量渲染 let buffer ; const streamBuffer new StreamBuffer(); stream.addEventListener(message, (event) { const frame JSON.parse(event.data); if (frame.type delta) { const { complete, pending } streamBuffer.append(frame.delta); renderMarkdown(complete); // 渲染完整部分 showPending(pending); // 待定部分用占位符显示 } else if (frame.type done) { const rest streamBuffer.flush(); renderMarkdown(rest); } });第二步对结构化输出做流式 JSON 解析。我们引入了一个轻量的增量 JSON 解析器它不要求完整 JSON 才能工作而是每次只解析已经闭合的部分把未闭合的留在缓冲区。这个方案尤其适合工具调用场景——模型输出工具参数的时候前端可以边接收边把参数列表渲染成卡片用户体验非常好。第三步后端协议规范化。我们把之前随手定义的 SSE 格式升级成了统一事件协议每个事件带上type、request_id、sequence字段。这样前端可以根据sequence检测丢帧可以根据request_id区分不同会话的数据流排查问题的时候一眼就能看出是哪一跳断了。type: delta request_id: conv_8f3a sequence: 17 data: {content: 现在开始处理} type: tool_call request_id: conv_8f3a sequence: 18 data: {tool: createTicket, params: {...}}2.4 教训Demo 里的将就会成为平台里的事故这个问题的核心教训是在 Demo 阶段内容短、用户少、场景预设断流和半标签问题几乎不会暴露但到了平台阶段一次长回答的流式渲染 多个并发的工具调用事件会让所有将就都变成事故现场。我后来把这个经验总结成一句话流式对话的本质不是传输分片而是状态还原。前端必须有能力从任意一个分片位置恢复出当前已确定内容和当前待定内容这就是 Agent 平台里所有流式交互的基础能力。这个能力在纯聊天 Demo 里是锦上添花在 Agent 平台里是地基。3. Agent 的四肢从哪来工具调用与执行循环的设计3.1 对话和 Agent 的分水岭工具如果说流式输出解决了怎么说的问题那工具调用解决的就是怎么干的问题。一个系统要被称作 Agent至少要具备三个要素能理解目标、能调用工具、能根据工具结果调整下一步行动。这三点缺一个都还是高级聊天机器人。工具调用的工程本质是把模型的自然语言输出翻译成确定性的结构化调用。大模型本身不执行任何函数它只负责输出一段符合约定的 JSON——包含工具名和参数。真正执行的是你的应用代码。所以你要做两件事第一用机器可读的方式通常是 JSON Schema把工具有什么能力、参数长什么样告诉模型第二把模型输出的 JSON 安全地解析出来校验参数执行工具再把结果返回给模型。{ name: create_ticket, description: 在工单系统中创建一张工单, parameters: { type: object, properties: { title: { type: string, description: 工单标题 }, priority: { type: string, enum: [high, medium, low] }, assignee: { type: string, description: 处理人 } }, required: [title, priority] } }方案落地时有个细节很容易被忽略参数校验。模型输出的 JSON 即使格式正确值也可能不合法——比如把不存在的用户填进了assignee。我们做了一层严格校验先校验 Schema再校验业务规则最后在调用前留一次人工确认钩子。这个钩子对高风险工具发通知、删数据、提审批尤其重要。3.2 执行循环ReAct 模式的工程落地有了工具之后Agent 的自主性来自一个循环思考Thought→ 行动Action→ 观察Observation→ 再思考直到任务完成。这个模式在学术上叫 ReAct在工程上就是一串 while 循环。def run_agent(task, tools, max_steps10): state initialize(task) for step in range(max_steps): decision model.plan(state, tools) if decision.action finish: return state.final_answer if decision.action not in tools: raise ToolNotFoundError(decision.action) observation tools[decision.action].execute(**decision.args) state.observe(decision.action, observation) raise MaxStepsExceededError()这个循环看起来简单落地时处处是坑。最典型的一个循环得有一个出口。模型经常会陷入我已经完成任务了但还想继续啰嗦的状态或者反过来工具调用报错之后模型不知道如何收场。我们的做法是强制设定max_steps并且要求模型每个循环都必须输出一个thought字段——不是为了让它思考而是为了让可观测性系统知道每一步它在想什么、为什么调用这个工具。这里插一句和热词harness 和 agent 区别相关的理解。Harness 是承载 Agent 运行的执行环境它负责提供工具、管理上下文窗口、控制循环迭代、处理超时与异常Agent 本身是决策核心。两者界限在工程上非常明确你的业务代码是 harness模型是 agent。很多人纠结这算不算 Agent其实是在纠结词汇而不是纠结架构——只要你的系统里有决策→执行→反馈→再决策的闭环它就是 Agent 形态。另外skill 和 agent 的区别也值得单独说。Skill 是能力单元Agent 是组织这些能力单元的自主体。一个 Agent 可以拥有多个 Skill查询数据、生成报告、发邮件而一个 Skill 也可以被多个 Agent 复用。设计平台时把 Skill 做成独立可插拔的模块比把所有逻辑堆在 Agent 里要优雅得多——后面扩展新场景时你会感激这个决定。3.3 状态与记忆平台和脚本的本质区别Demo 阶段上下文就是把整个聊天历史拼起来发给模型。这个方案在平台阶段撑不住因为 Agent 运行过程中会产生大量中间状态工具调用结果、子任务进度、用户临时修改的需求、跨轮对话的偏好信息。全部塞进上下文既费 token 又容易让模型迷失重点。我们的做法是引入三层状态。第一层是会话状态保存对话历史、用户身份、当前业务上下文第二层是运行状态保存当前 Agent 循环内部每一步的中间结果包括工具调用记录和观察值第三层是长期记忆用向量库存储历史任务的关键结论和用户偏好让模型在后续对话中能主动检索和引用。三层状态拆分带来的直接收益是对话可以跨天进行Agent 不会因为上下文窗口被占满而失忆同时平台的审计能力也变强了——任何一步状态都可以回溯当模型输出异常时你能清楚地看到是哪个中间环节带了错误的节奏。4. 平台化改造企业级 Java Agent 平台的模块拆分4.1 为什么要扎进 Java 生态聊到平台化改造第一个绕不开的问题就是语言选型。我们的候选是 Python 和 Java。Python 在 AI 生态有明显优势模型 SDK、数据处理库一抓一大把但我们的实际情况是目标客户是传统企业内部系统以 Java 为主已有的权限体系、审批流、消息中间件全部跑在 Java 技术栈上。当时团队讨论了很久最后选了 Java理由有三个。第一集成成本低Agent 要调的工单、OA、CRM 接口全是 Java 服务用同语言对接心智负担最小。第二企业级治理成熟Java 在权限、事务、审计、高可用这些方面有大量成熟方案而这恰恰是企业级 AI 应用最缺的部分。第三团队可持续性招一个懂 Java 的后端工程师比招一个懂 AI 编排的工程师容易得多平台长期维护不能依赖少数几个人。这个选择现在回头看依然正确。AI 模型本身是无状态的推理服务真正需要工程化的部分是编排、集成、治理这些恰好是 Java 生态的强项。4.2 核心模块清单平台不是大号的 Demo平台化改造的核心工作是把之前在 Python 脚本和单机服务里揉成一团的逻辑拆成边界清晰的模块。我们最终沉淀下来六个核心模块模块职责关键设计接入网关统一对外 API、SSE 流式转发、鉴权限流WebFlux 非阻塞处理流式请求会话管理会话生命周期、上下文持久化、历史回放会话快照 增量存储Agent 运行时执行循环、决策调度、步骤控制支持多 Agent 编排与嵌套工具注册中心工具定义、参数校验、调用代理、人工确认钩子Schema 驱动动态加载Skill 管理技能包版本、依赖、灰度发布每个 Skill 独立模块化观测审计日志、追踪、指标、全链路回放每一步决策与调用留痕这个拆分方式有一个核心理念模型是可替换的工具是可插拔的Agent 是可编排的。模块与模块之间只通过接口通信谁都不直接依赖某个具体的大模型厂商或某个具体的工具实现。这样做的原因后面会详细说但简单讲就是——这个领域变化太快了你今天选的模型和框架半年后大概率不是最优解架构上必须留好换血的口子。4.3 一个请求从进入到返回的完整链路拿一个实际场景串一遍用户在界面上说帮我把上周的销售数据整理成周报邮件发给总监。请求先进接入网关网关完成鉴权和限流把它路由到会话管理模块。会话管理加载该用户的上下文识别出这是一个新的任务型请求交给 Agent 运行时。运行时开始执行循环模型第一步决策是需要查询销售数据于是通过工具注册中心找到query_sales_report工具校验参数后调用后端服务拿到数据接着模型决策需要写周报于是调用generate_report这个 Skill生成 Markdown 报告最后决策需要发邮件调用send_email工具此时因为发邮件属于高风险操作工具注册中心触发人工确认钩子前端弹出一个确认卡片用户点击确认后工具才真正执行。整个过程中所有事件模型思考、工具调用、参数详情、执行结果都通过 SSE 实时推送到前端用户看到的是Agent 先在界面上显示正在查询销售数据然后显示正在生成报告最后显示等待你确认发送邮件。这个体验和单纯聊天完全不同——用户不是在等一个回答而是在看一个同事干活。后端实现上我们用了SseEmitter做流式推送关键是设计好回调接口把 Agent 运行时的每个事件都暴露给 Web 层PostMapping(value /agent/execute, produces MediaType.TEXT_EVENT_STREAM_VALUE) public SseEmitter execute(RequestBody AgentRequest request) { SseEmitter emitter new SseEmitter(120_000L); agentRuntime.execute(request, new AgentObserver() { Override public void onThought(String thought) { emitter.send(Event.event().name(thought).data(thought)); } Override public void onToolCall(ToolCall call) { emitter.send(Event.event().name(tool_call).data(call)); } Override public void onConfirm(ConfirmRequest confirm) { emitter.send(Event.event().name(confirm).data(confirm)); } Override public void onDone(String answer) { emitter.send(Event.event().name(done).data(answer)); emitter.complete(); } }); return emitter; }4.4 演进路线别想着一步到位很多团队做平台化改造时最容易犯的错是希望一口气把架构调到终态。我们踩过这个坑。一开始我画了一张特别宏大的架构图包含多租户隔离、模型网关、插件市场、可视化编排结果团队做了两个月第一个完整的端到端场景都没跑通。后来我调整了策略先用最丑的方式把一个真实场景完整跑通再逐层优化。我们分了三个阶段。第一阶段保留 Demo 的对话界面和流式能力后端引入 Agent 运行时和工具注册中心只接了一个工具查数据库。第二阶段加上会话持久化、多 Agent 编排、人工确认钩子并把工具数量扩展到十几个。第三阶段才做企业级治理——权限、审计、灰度、监控告警、评估回放。这个顺序的本质是先验证业务价值闭环再补规模化底座。如果一开始就在为不存在的流量和场景设计架构你优化的一切都是空中楼阁。5. 框架选型与造轮子的边界5.1 市面上的 Agent 框架能帮你解决什么当你决定从零搭平台时第一个问题一定是要不要用现成的 Agent 框架市面上有纯编排层的框架有图形化工作流引擎也有带运行时和工具的全家桶方案。这些东西能帮我们解决三件事执行循环的标准实现、工具定义与调用的通用协议、多步骤编排的调度能力。但框架也带来一个隐性成本它的抽象是别人定义的你和业务之间的缝隙要你自己填。比如很多框架把工具抽象成一个函数但你企业的工具是有权限、有审批、有审计的这些横切关注点在框架里没有位置。再比如框架自带的记忆机制通常只考虑对话记忆而企业场景还需要业务状态记忆和外部系统事件记忆这完全超出了框架的抽象范围。5.2 框架抽象与业务现实的冲突说两个我们实际遇到的冲突。第一个冲突是技能与流程的边界。框架通常把技能理解成一个可以被模型调用的函数但在企业里很多操作不是单个函数而是一串跨系统的流程创建合同可能要经过法务审核、财务校验、领导审批。强行把这些流程塞进一个技能里要么技能内部逻辑臃肿到无法维护要么违反权限规则。我们最后的解法是框架只负责调用技能流程本身交给业务侧的流程引擎管理Agent 只负责决定走哪个流程和在节点间传递上下文。第二个冲突是评估。很多框架都宣称支持评估但它们评估的是模型回答质量而企业更关心的是任务完成度工单建没建成功、邮件发没发出去、审批有没有卡住。这类评估必须深入到业务系统拿结果框架给不了。所以我们自己建了一套任务级评估体系追踪每个 Agent 任务的最终业务结果而不是只看模型答了什么。5.3 我们的混合策略框架做编排业务做实现最终我们的选型策略是混合式底部运行时和编排逻辑使用框架的成熟能力避免自己重复造轮子但所有和业务相关的部分——工具实现、权限校验、审批流对接、人工确认、业务结果回调——全部自己实现通过标准接口接入框架。这个策略有个前提要选择抽象边界清晰的框架而不是裹挟一切的平台。能用接口替换的部分越多越不容易被套牢反之如果框架把通信协议、存储结构、前端组件都定了那基本没有演进空间了。我还想提醒一点框架的版本升级在 AI 领域特别频繁我们的教训是所有对接框架的代码必须收口到一个适配层里禁止在业务代码里直接调用框架 API。这样框架升级时你只改适配层业务逻辑纹丝不动。5.4 可演进的关键稳定的接口 可替换的实现最后回到可演进这个主题。到底什么决定了平台能不能长期演进我的答案很简单接口的稳定性决定了演进的天花板。如果一个平台的内部接口是稳定的——Agent 运行时不知道模型是哪家的工具注册中心不关心工具是内部实现的还是第三方集成的会话管理不依赖具体的存储引擎——那你的替换成本就会很低。今天用一个模型明天可以换另一个今天用某个框架明天可以重写运行时今天用 Postgres明天可以换向量数据库。每一处替换都只发生在适配层不影响上下游。这就是我理解的从 Demo 到可演进平台的核心不是把代码写得有多漂亮而是把变化点隔离好让每一项新技术、新需求进来的时候都只动它该动的地方。6. 回看这一路几个我踩过才懂的建议如果你也在走这条路基于这一轮改造的实战我最后唠叨几句实在的。第一流式能力是平台的地基不是加分项。我们在 Demo 阶段把流式协议整理干净了后面所有 Agent 事件推送、工具状态展示、人工确认交互都建立在上面。如果当初偷懒用了整段返回后面全部要重做。第二工具调用一定要做人工确认钩子。这不是为了限制 Agent而是为了让用户信任 Agent。用户看到 Agent 要先征求他的同意再发邮件、再执行删除操作他对系统的信任感会大幅提升这点在 To B 场景里比技术本身还重要。第三不要让模型自己决定什么时候结束。我们在早期遇到过 Agent 不停调用工具、预算快速消耗的失控情况后来强制了max_steps和每步必须给出 thought的约束失控问题基本消失。给 Agent 的自由度一定要建立在可观测、可中断、可回退的基础上。第四优先做一个完整场景不要先做完整平台。这个系列里我最想强调的就是这条。把一个真实业务场景从头到尾跑通——包括流式交互、工具调用、人工确认、结果持久化——能让你在最短时间内暴露最核心的问题。等这条链路稳定了再去铺平台化的各种能力。关于从 AI 对话 Demo 到可演进的 Agent 平台这篇算是开个头把整体思路和几条主线串起来了。后面我计划逐篇拆开讲会话管理怎么做、工具注册中心的 Schema 设计、人工确认交互的体验细节、任务级评估体系怎么搭。这个领域没有标准答案每个团队的技术栈和业务场景都不一样但如果我的这些取舍和踩坑记录能让你少做几个错误决策这篇就值了。