我最早写 AI 对话 Demo 的时候其实特别兴奋——模型上下文里塞一段 system prompt用户发一句话返回一句像模像样的回答那种“我的程序懂人话”的成就感确实容易让人上头。但没过多久我就发现Demo 跑通和真正可用的 Agent 平台之间隔着的不是一点点工程工作量而是完全不同的两套设计逻辑。这就像用 C 语言写一个 TCP 通信 Demo能连通、能收发消息你就算完成了教学任务但一个生产级的通信服务要考虑粘包拆包、重连退避、并发隔离、流量控制你不可能拿课堂 Demo 直接顶上去。这篇“开篇”我想做的就是把从 AI 对话 Demo 走向可演进 Agent 平台这条路上最容易被低估的几个问题摊开聊一遍。我不会只给结论会把每个判断背后的原因、踩过的坑、以及我觉得更合理的设计取舍都讲清楚。适合谁看手头已经有一个能跑的对话 Demo、正纠结下一步怎么走的人或者正准备从零搭一个 Agent 项目、想知道哪些东西一开始就要打好地基的人。内容会比较偏工程实践但我会尽量把每个概念都说人话。以下内容是一个“系列开篇”所以文章里很多问题我会只给路线和关键决策不展开全部细节。后面每一章都值得单独拆开写我会在后续的文章里逐个深入。先把全局打通我们才不会在细节里迷路。1. 为什么大多数 AI 对话 Demo 走不进生产环境先泼一盆冷水你在本地 Notebook 或页面上跑通的对话 Demo大概率离“能发布给用户用”还差着三个数量级的工程量。这个差距不是模型能力的问题而是工程特征完全不一样。1.1 Demo 天然是“无状态”的而产品天然要求“有状态”你可以打开一个聊天页面发几轮消息体验很好。但一旦刷新页面、重启服务之前的对话就全没了。模型本身不保存任何记忆它只对你“这次请求里携带的上下文”做响应。所以你会遇到一个特别常见的问题用户上午聊了需求下午回来继续聊你的程序完全不记得上午发生了什么。这不是模型的问题是你没有做状态的持久化。产品的本质要求是会话可以被恢复、被继续、被审计。而一个合格的 Agent 平台状态不只是“聊天记录”还包括当前任务执行到哪一步、已经调用过哪些工具、拿到了哪些结果、用户的长期偏好是什么。这些都不在模型里要你自己设计、存储和维护。1.2 单用户能跑和多人同时用是两码事Demo 阶段通常只有一个用户你自己。数据都在单机内存里怎么搞都不会串。但一旦发布出去你会面对多用户并发。我见过最典型的翻车现场同事 A 在工具里查了“杭州的天气”同事 B 接着问“那上海呢”系统在 B 的会话里沿用了 A 的上下文结果返回了杭州的数据并说“这是上海”。这就是典型的会话隔离没做好。生产环境至少要处理三件事每个会话有独立的上下文空间互不污染。用户权限隔离不是所有用户都能触发管理员级别的工具。资源配额隔离避免某个用户的一次长任务占光所有算力和 token 预算。下面这个表可以很直观地看出 Demo 和平台的差距维度Demo 阶段平台阶段状态内存里重启即丢持久化可恢复、可回溯用户你自己多用户、多角色、多租户错误处理崩了就重跑有重试、有降级、有告警可观测性打印 log 看输出全链路 trace 成本监控成本几乎不在意预算、配额、熔断都要有数据安全无所谓权限、审计、脱敏1.3 你看到的“效果稳定”其实是一场幻觉对话 Demo 的另一个假象是你测了几轮没问题就以为没问题了。但大语言模型是概率输出同样的输入温度稍微调高一点结果就变了换一个问法可能就触发不同的路径。你测试时感觉“聪明、稳定”很可能只是你一直在用同一批问题走了同一条成功路径。Demo 阶段不会去考虑这些情况用户输入包含错别字、口语、中英混排模型到底能不能理解。用户连续追问同一个话题十轮之后模型是否还记得最开始提到的约束条件。模型偶尔“幻觉”出一个不存在的工具参数你的代码会不会因此崩溃。这三件事在 Demo 里可能一次都碰不到但在真实使用中每一条都会高频出现。所以我会在后面的章节里专门讲状态管理、工具调用和评测体系它们分别对应上面三个问题的解决方案。2. 从单轮对话到 Agent 平台思维上的三连跳把 Demo 变成平台最先要转变的其实不是代码而是思维方式。我总结为三连跳从“输入-输出”到“目标-执行”从“纯文本”到“工具调用”从“脚本”到“服务”。2.1 第一跳从“一问一答”到“为结果负责”普通的 AI 对话是用户提问模型回答。它不对结果负责。而 Agent 的核心范式是用户给一个目标Agent 自己拆解成任务逐步执行如果失败了还要尝试换一条路径。这就是 ReAct 这类架构的本质思考Thought—行动Action—观察Observation循环。模型先想清楚当前要做什么然后调用工具执行观察结果再决定下一步。整个过程不再是单轮输出而是一个有状态、有循环的推理过程。很多人在这一跳上栽跟头是因为他们把 Agent 想象成“更聪明的模型”而不是“更聪明的流程设计”。模型本身当然重要但 Agent 的输出质量很大程度取决于你怎么设计目标分解、怎么给工具写说明、怎么处理异常这些模型都不管。2.2 第二跳从“会聊天”到“会干活”对话 Demo 再强也只是在生成文本。但用户真正要的是干活订机票、查库存、生成报表、发邮件。这些动作模型本身做不了它只能通过调用外部工具来实现。所以你的平台需要一套“工具调用”体系模型发送一个结构化的请求比如“调用 search_product 工具参数 name蓝色外套”系统解析后去真实执行再把结果返回给模型。模型是大脑工具是手和脚平台是神经系统——信号要传得准、传得稳。这一步的工程深度远超想象。后面我会单独用一章讲工具注册表、参数校验、错误恢复这里先强调结论如果只做“能聊天的对话”你甚至不需要 Agent 平台一旦要让模型“干活”工具调用体系就是绕不开的必经之路。2.3 第三跳从“我的脚本”到“别人的服务”第三跳是最容易被技术型开发者忽略的。你写一个脚本自己调用哪怕代码写得烂一点也能跑。但做成平台意味着别人要用你的系统、别人要依赖你的系统。那么至少有这几个问题必须回答用户怎么认证每个请求怎么知道是谁发出来的用户能调用哪些工具按什么规则来授权数据是否被记录如果出了问题能不能回放、审计系统能不能平滑升级升级后老会话是否兼容我在很多 Agent 项目里都见过一个奇怪的现象功能迭代优先用户体系长期空缺。直到要上线了才发现根本不知道如何区分两个用户的数据于是开始大面积重构。这个坑的根源就是第三跳没过始终把自己当成写脚本的人而不是做服务的人。顺带说一句现在有很多现成的 Agent 框架可以帮你简化开发但框架解决的主要是第一跳和第二跳的编排问题也就是循环、状态、工具调用这些通用能力第三跳的平台化能力比如用户体系和权限模型通常还是要结合业务自己设计。3. 对话状态管理Agent 平台最容易被低估的根基建链记住我说的状态管理不是把聊天记录存进数据库那么简单。状态管理做不好后面所有 Agent 能力都会像盖在沙子上的楼。这是整个平台最底层的地基之一。3.1 状态到底包含哪些东西一个 Agent 运行过程中需要记录的信息至少包括多轮对话的历史消息用户消息、助手消息。Agent 当前的执行计划用户目标是什么已经拆成了哪些步骤走到哪一步。工具调用的记录调了哪个工具、传了什么参数、返回了什么结果。临时上下文上一步产生的中间数据下一步还要用。长期记忆用户连续几次访问平台累积下来的偏好、历史结论。你可以简单地把状态分成两个层次会话级状态一次用户会话里的短期记忆会话结束或过期后可以清理。用户级状态跨会话的长期记忆需要持久化并且要能检索。很多人在 Demo 阶段只做了“把历史消息拼接起来发给模型”这算是状态管理最原始、最粗糙的形式。它的问题很明显随着对话轮数增加上下文越来越长请求越来越慢、越来越贵而且早期的信息还会被淹没在后来的对话里。3.2 上下文窗口的物理极限这就是热词里很多人问“对话达到上限如何延续”“对话太长变慢了怎么解决”的根源。模型的上下文窗口是有上限的。即使模型支持一百万字上下文先不说成本从产品体验上讲请求越长首字返回时间就越长用户会明显感觉到变慢。我实际操作中的思路是分三层解决滑动窗口只保留最近 N 轮对话。超过 N 轮的直接不发给模型。这是性价比最高的一招。摘要压缩定期把“被挤出窗口”的历史对话用模型生成一段摘要当用户继续提问时把摘要放到对话最前面充当“记忆压缩包”。结构化记忆不是所有信息都塞进文本。比如用户的偏好、业务数据的关键值单独抽出来存成 JSON。需要时再动态注入到 prompt 里。这三层可以叠加使用。我的经验是对大多数业务滑动窗口加摘要压缩就能覆盖 80% 的场景结构化的用户画像适合在用户第二次访问、第三次访问时发挥价值。3.3 用“事件回放”替代“改现状”如果你让我给状态管理选一个最好的工程实践我会推事件溯源每条用户消息、每次 Agent 决策、每次工具调用都当作一条“事件”追加记录。系统当前的状态就是这些事件按顺序回放后的结果。这么做的好处非常明显哪天线上出了问题你可以把某次会话的所有事件拉出来一步步重放看看 Agent 在哪个环节决策错了。这比对着数据库里“最终状态”猜测原因高效太多。我甚至会在调试阶段给每条事件打上一个 trace_id把所有输出串成一整条链路。表结构上我会建议最小集表用途session会话主表记录用户、开始时间、状态message消息表用户和助手消息含角色、内容、token 数event事件表包含思考、工具调用、工具结果、异常等结构化事件memory长期记忆表用户维度键值存储3.4 两条血泪教训第一状态结构要版本化。你现在的消息体可能是{role, content}某天你加了message_id必须保证旧数据还能兼容。如果刚开始不给消息体留一个version字段等数据量大了之后任何一次格式调整都会变成一场灾难。第二不要为了省事把所有状态都放在内存里。内存状态最大的问题不是数据丢失而是多个服务实例之间没法共享。当一个平台从单机变成多实例内存态会直接变成“用户时而记得、时而不记得”的诡异 bug。哪怕第一版用文件存储或 SQLite也比纯内存好。4. 工具调用与 Agent Harness把“能聊”变成“能干”一个只会聊天的助手价值天花板很低。一旦接上真实工具价值就完全不一样了。但工具调用远没有看上去那么简单它决定了你的 Agent 是“聪明助手”还是“人工智障”。4.1 工具调用的本质模型负责“决定”框架负责“执行”很多人第一次接触 Function Calling 时有个误解以为模型自己去执行了函数。实际上不是。模型只是在生成文本时按照你的约定输出一个结构化的调用意图比如{ name: search_order, arguments: { order_id: 20250601 } }真正执行的是你平台的代码。模型是下指令的人系统是执行指令的手。理解这一点你就明白为什么工具描述要写得特别清楚——模型没有用过你的工具它只能通过你提供的描述来“想象”这个工具能干什么、参数代表什么、什么时候应该调用它。我见过很多失败的 Agent 项目问题都出在工具的描述上。比如写search_order(order_id)模型根本不知道 order_id 是什么格式、是必选还是可选、哪些用户权限才能调。所以我的工具注册表里每个工具都至少包含这些字段字段说明name工具名全局唯一模型输出时要用description对工具功能的详细说明包括适用场景parametersJSON Schema说明每个参数的类型、是否必填required必填参数列表permission需要什么用户角色才能调用timeout单个工具单次执行的最大耗时idempotent是否幂等重复执行会不会产生副作用4.2 没有兜底的工具调用是一场连环灾难热词里有一个典型报错agent execution terminated due to error.这个报错的背后通常不是单一原因而是工具调用链路里某一环断裂了。我梳理一下最常见的几类问题模型输出的工具调用不是合法的 JSON。很多模型在长输出时会“飘”前后多了几个字符你的解析器就崩了。模型幻觉出一个不存在的工具名或者参数。它并不是恶意只是“以为自己知道”。工具执行时报错但你的代码没有把错误信息返回给模型。于是模型在黑暗中瞎猜越猜越错。工具陷入死循环。比如一个搜索工具模型反复调用同一组关键词系统反复执行token 哗哗地烧。针对这些我的落地规则是所有模型输出必须先做 JSON 解析失败则要求模型重新生成一次。参数做严格校验不满足 Schema 就直接拦截不进入执行阶段。工具报错时把错误信息稍作包装作为“观察”结果返回给模型让它决定下一步。设置最大迭代轮数比如 5 轮达到上限后强制终止返回“需要人工介入”。我见过有人不解为什么工具报错还要返回给模型道理很简单Agent 的闭环就是“思考—行动—观察”观察里必须有真实的反馈信号。如果反馈是空的、假的模型就没有办法修正自己的下一步。这是 Agent 和普通程序最大的不同普通程序执行失败直接抛异常而 Agent 应该在失败后读取信息、调整策略、再次尝试。4.3 什么是 Harness它和 Agent 到底是什么关系热词里有人问“harness 和 agent 区别”我用一个类比来解释。Agent 是一个决策主体它在思考“我要用什么工具、下一步干什么”而 Harness 是承载这个 Agent 运行的整套执行环境包括循环控制、工具注册表、状态存储、安全边界、终止条件、成本限制。换句话说Agent 是大脑Harness 是身体和骨架。一个最小可用的 Harness 伪代码是这样的for step in range(max_iterations): prompt build_prompt(session_state, current_observation) response model.generate(prompt, toolstool_schemas) if response.finish_reason stop: return response.content tool_call parse_tool_call(response) if not tool_call.is_valid(): current_observation 工具调用格式错误请重新生成 continue if not permission_check(tool_call, user): current_observation 权限不足终止本次调用 break result execute_tool(tool_call) if result.is_timeout(): current_observation 工具执行超时 else: current_observation result.content session_state.record_tool_call(tool_call, result)很多成熟的 Agent 框架本质上就是帮你实现了这个 Harness。但我的建议是不管用不用框架你自己心里必须清楚这个循环每一步在做什么否则出了问题你会连查日志都不知道从哪查起。5. 给平台留三样“未来资产”可观测、可评测、可扩展Demo 阶段不关心平台化属性但一个可演进的平台越早建设这三样东西后续的维护成本越低。我称它们为“未来资产”因为它们在早期不直接产生用户价值但到了中期全是救命稻草。5.1 可观测别让你的 Agent 成为一个黑盒Agent 的每一次运行本质是一条复杂的执行链模型思考、调用工具、拿到结果、再思考、再调用……任何一个环节的失误都可能让最终结果南辕北辙。如果没有全链路追踪你会非常被动——用户在群里说“答案错了”你打开日志只有一句final answer: xxx完全不知道中间发生了什么。我的做法是给每次用户请求生成一个trace_id然后记录以下事件用户请求的原始文本拼装后的完整 prompt以及对应的模型参数模型每次生成的工具调用原始输出工具执行的结果与耗时每一步的 token 消耗最终返回给用户的内容这些事件统一写入结构化日志。出了任何问题只需要拿着 trace_id 到日志系统里拉出整条链立刻能定位到是模型决策错、工具执行错还是状态拼接错。这个能力做晚了排查问题的成本会指数上涨。可观测还包括成本观测。Agent 和普通接口不一样一次任务可能触发几十次模型调用。如果不对单用户、单会话做 token 配额月末账单会给你惊喜。我一般会设三层护栏单次请求 token 上限、单会话累计 token 上限、单用户每日 token 上限。5.2 可评测别用“感觉还行”代替“知道行不行”大语言模型应用的最大痛点就是不稳定。你优化了某个 prompt结果某类问题变好了另一类问题却变差了。如果没有评测集你根本无法回答最基础的问题“这次改动到底是变好还是变坏”我的做法是从第一天就积累回归用例。每发现一个模型回答错的场景就把这个场景加入评测集。比如这样用例 ID: case_017 用户问题: “帮我查一下上个月华东区的销售额对比前年同期” 期望行为: 调用 sales_report 工具参数 regioneast, month202505, comparepre_year 不期望行为: 直接编造一个数字作答评测不一定一开始就要搞复杂的指标。你可以先用最朴素的方式人工跑一遍关键用例记录通过率。对每个用例做“期望工具调用”和“实际工具调用”的比对自动判断工具选择是否正确。对自然语言回答先让模型当裁判打分后期再逐步引入更细的维度。这一步最核心的价值是它会逼着你把“模糊的产品感觉”变成“可量化的指标”。没有这个基础后面做 Prompt 调优、模型选型、工具升级全都在盲人摸象。5.3 可扩展保持扩展点开放剩下的等需求来了再说第三个资产是可扩展性。我给的建议是只设计扩展点不要提前实现扩展内容。具体落地是这三件事工具通过注册表接入而不是写死在主流程 if-else 里。新工具只需要实现统一接口在配置里注册即可。Prompt 放进配置中心不要硬编码在代码里。每次调整 prompt 都不需要发版。事件系统保留兜底出口。当 Agent 执行了关键步骤时往统一事件总线发一条消息后续做消息通知、审计、数据统计都不用重构主链路。平台演进最忌讳两种极端一种是一开始就上微服务、事件总线、多租户等重型架构结果业务没跑通先被架构拖死另一种是完全不预留接口业务一扩张就推倒重来。我的平衡点就是“模块化但不微服务化”代码层面模块边界清晰部署上保持单体或轻量多进程。6. 演进路线先把对话做扎实再谈平台最后聊一聊具体怎么走。我不会给出一个“标准架构”因为每个团队的基础不一样。但我可以分享一个经过验证的最小演进路径分三个阶段推进。6.1 阶段一做一个“有状态、可观测”的对话服务这个阶段不要碰 Agent 概念先把对话本身做扎实。具体任务接入模型统一接口层避免业务代码直接绑死某一家模型。建好 session 和 message 两张表实现会话的创建、续聊、清理。完成基础日志每次请求记录输入、输出、耗时、token 数。写上最简单的用户体系哪怕只有一个用户表也要为以后扩展预留 user_id。判断这个阶段完成的标准发布到测试环境多个人同时使用会话之间不串重启服务后对话可以恢复。做到这里你已经比 70% 停留在 Demo 阶段的项目强了。6.2 阶段二接入第一个真实工具跑通最小 Agent 闭环第二阶段的关键是选一个高频、低风险的业务动作做工具化。比如查订单、查天气、读取数据库报表。不要求多一两个就够。要做的事包括定义工具注册表结构把第一步的工具注册进去。实现带循环控制的 Harness哪怕是最简版。配置成本配额和最大迭代轮数避免工具循环失控。给 trace 链路补上工具调用的事件记录。这一阶段最大的坑是你忍不住同时接十几个工具。我强烈建议克制住因为工具数量一旦上去模型的“工具选择负担”指数增加很多奇怪的选择错误会出现。一两个工具跑通闭环比十个工具乱成麻有价值。6.3 阶段三平台化做多 Agent、权限、评测和运营到这一步你已经不是在做“一个功能”而是在做“一个系统”。平台化阶段我会按优先级做这几件事权限模型用户、角色、工具权限三层确保不同角色能看到和触达的工具不同。评测中心把第二阶段积累的回归用例变成自动化测试每次改动上线前强制跑一遍。Prompt 管理所有模板都走配置中心带版本管理。多 Agent 支持不同业务场景用不同的专长 Agent而不是让一个 Agent 什么都会、什么都不精。这个阶段完成后你的平台才真正称得上“可演进”新业务来的时候你能以增量方式加工具、加 Agent、加评测用例而不是推翻重来。6.4 技术选型的一个建议关于技术选型我唯一想强调的一条原则是抽象层一定要有但重型框架可以晚点上。模型调用、状态存储、工具执行这三个核心接口建议你自己保留足够控制权至于具体是手写 Harness 还是引入现成编排框架取决于团队规模和工程能力。小团队早期手写简单 Harness 完全可行但前提是你把循环、状态、错误处理这三个点想透了。如果只是想快速验证业务引入成熟框架也能节省大量时间但框架会隐藏掉很多细节出了复杂问题你依然要回来理解底层循环。最后说点我自己的体会这条路我走过一遍回头总结一个道理从 Demo 到平台最快的路径不是某个灵光一现的架构而是老老实实把状态存下来、把日志记下来、把评测跑起来。这三点听起来一点都不性感但它们恰恰是 Demo 和产品之间最难以跨越的三道坎。我见过太多项目花大把时间研究如何让模型“更聪明”却连“每次请求的输入输出有没有 trace”都没做到最后出了问题连排查的抓手都没有。这也是我把“开篇”重心放在这几个基础能力上的原因。后续我会分开写这些主题的深度实操状态管理的表结构设计、工具调用失败的恢复策略、评测集怎么从人工走向半自动、多 Agent 的权限设计怎么做。如果你已经有一个对话 Demo现在正准备往 Agent 平台的路上走我建议先别急着写复杂代码花几天时间把状态、日志、成本护栏这三角地基补上。地基稳了后面加多少层楼都不会慌。