从AI对话Demo到Agent平台：演进路径、架构设计与工程实践指南

最近身边好几个做技术的朋友都在干同一件事拿大模型API先写一个AI对话Demo跑通了就到处演示。演示的时候大家夸两句等冷静下来真正的问题才开始浮现——这个Demo下一步到底怎么走是继续堆Prompt还是把工具、记忆、任务状态都一股脑塞进去我见过太多项目卡在这个岔路口表面上是技术选型问题实际上是没想清楚“对话Demo”和“Agent平台”之间那条代际鸿沟。这篇算是这个系列的开篇我先不急着给具体代码方案而是把边界、架构思路、演进路线和最容易被忽略的坑讲清楚。适合正在做AI对话Demo但不知道如何演进的开发者也适合想梳理Agent平台技术架构、想搞明白工具调用和记忆系统怎么设计的人。你不需要是资深架构师最好已经写过一点调用大模型接口的代码剩下的跟着思路走就行。1. 先把“对话Demo”和“Agent平台”的边界划清楚1.1 Demo、聊天机器人和Agent差距不在“智能”而在“闭环”很多人分不清这三个词。我见过最典型的误解以为能连续对话就约等于在做Agent了实际上差得很远。这里我说的“闭环”不是指对话有来有回而是指“感知-决策-行动-观察”这个完整回路有没有跑起来。Demo指向外部展示“能跑”验证API通、模型能返回合理文本。对话往往单轮不处理状态不接外部系统。Demo的价值是证明“管道通了”核心指标是“能答上来”。Chatbot在Demo基础上加了多轮、人设、会话隔离、内容过滤、知识库检索等核心是“聊得好”但行为边界基本锁定在“语言交互”里。Agent不仅要会“说”还要会“做”。它需要能拆解任务、调用外部工具、读取状态、修正计划、记忆上次结果然后继续行动。核心指标是“能闭环完成任务”。比如用户说“帮我把项目里所有的TODO项汇总成周报”Agent不是直接生成一份假的周报而是去查代码仓库、读Git记录、调接口拿到真实数据然后汇总呈现。那为什么很多项目想从Demo直接跳到一个Agent平台很容易翻车因为这两者之间的结构差异是代际级的不是“加几个if”能解决的。我习惯用一个判断标准你的程序有没有“行动-观察-再行动”的循环。如果从头到尾只是“用户发消息-模型生成回答”哪怕接了一百个工具本质还是对话Demo。只有当模型生成的不是最终答案、而是“下一步动作”并且程序有对应的执行、回灌和再决策机制时才真正进入了Agent的范畴。这也是我在后面所有章节里反复围绕的一条主线。1.2 为什么一大半项目都死在“Demo能跑”这一步Demo能跑只能说明“这条路走通了”不能说明“这个架构能长起来”。我见过太多项目死在从Demo到产品的路上原因高度重复不是我故意要泼冷水而是见过太多次同样的翻车现场。第一Prompt和逻辑混在一起。用户在页面上问一句你拼一段字符串发给大模型再把返回内容渲染出来。听起来很简单但一旦要加权限、加工具、加记忆字符串拼接的复杂度会指数上升最后连开发本人都不敢动代码。我今天刚改了一行工具描述结果另一个场景的输出就变形了这种牵连问题在后期会频繁出现。第二没有为“演进”留接口。模型写死了工具写死了记忆根本没有日志只有print。你Demo阶段可能觉得省事但到了第二天要同时支持多个模型、多个工具时你会发现所有代码都要改一遍而且改完还会互相影响。我有个朋友做得更极端直接把API密钥和Prompt硬编码在页面里结果要换模型时等于重写整个后端。第三Demo和原型被混为一谈。Demo是“证明可行”原型是“验证形态”而一个平台是“支撑生态”。我见过很多人拿着Demo就开始排期做产品结果一跑起来发现用户要的根本不是“能聊”而是“能办事”。于是团队精力全花在返工上之前的“炫技”代码反而成了包袱。Demo和原型的区别本质上是对“下一步投入方向”的判断搞错了就是浪费几个月。第四缺少最基础的工程保障。没有评测集改一版模型Prompt后不知道是不是变笨了没有traceAgent哪天抽风执行了一长串工具调用出了问题只能对着终端干瞪眼没有成本核算跑了一百轮循环都没意识到这个Demo已经花了远超预期的API费用。工程保障听起来不酷但它决定了项目能走多远。我并不是说Demo不该做。相反Demo阶段是必要的它最大的价值是用最小成本验证模型能力和场景可行性。但你必须在写第一版代码时就意识到这是一个“未来会长大”的系统而不是一个“发完朋友圈就扔”的一次性脚本。这也是这个系列第一篇最想传达的东西。2. 从Demo到Agent平台的整体设计思路2.1 以“工具调用”作为分水岭来切架构自称要搞Agent的人很多但真正动手时几乎所有人都在同一道题上卡住模型怎么调用工具大模型本身不能执行代码也不能直接读取数据库。它只能生成文本其中可能包含“应该调用什么工具、传什么参数”的表示。业界最常见的做法是Function Calling也就是在请求里声明一批工具的描述和参数Schema模型根据对话内容返回一个结构化调用请求然后由你的程序执行这个请求将结果作为新消息连同历史一起再发给模型。这个循环就是Agent闭环的核心引擎。从架构上看你要不要把“对话流程”和“工具执行流程”分离开我的建议是必须分而且是在设计的第一步就分。最简单的方式是对话流程只管接收用户输入、维护会话上下文、把组装好的消息发给模型、拿到回复并返回。工具执行流程负责调用外部系统、校验参数、处理超时和错误、把结果整理成模型能理解的结构化文本。这两个流程之间只通过一种结构通信——“模型要调用工具程序执行结果回灌”。如果你把工具执行的逻辑写在对话处理的同一个函数里一次两次没事做到十个工具以上就会变成一团乱麻。我后续的代码示例也都基于这个分工你可以先去理解这个边界再动手写代码。这里我想强调一点Function Calling不是唯一的工具调用方案。很多开源模型支持Code Interpreter语义让模型直接生成Python代码还有的方案让模型输出JSON指令由程序解释执行更复杂的平台会做专用的动作规划。但从可演进性来看统一函数协议的方式最通用也最容易做权限、审计和重试。这也是为什么大多数Agent框架都把Function Calling作为一等公民。2.2 四个必须一开始就留好的抽象层我复盘了自己和周围人的项目凡是能从Demo长成平台的几乎都早早在下面四个层上做了抽象。这四个层不要求一开始很完善但只要接口正确后面替换实现都非常轻松。这也是“可演进”最核心的含义。模型层不要在自己的业务代码里直接写死“调用某某服务”。你需要一个统一的LLMProvider接口至少暴露chat(messages, tools)这个方法返回消息对象和可能的工具调用。这样今天用某个商业模型明天换开源模型甚至本地部署模型只需要新增一个Provider实现业务代码零改动。我见过很多人把pandas里的数据清洗逻辑和模型调用写在一起结果后面想换个模型牵连出一堆bug就是因为没有这一层。工具层任何工具都封装成“名称描述参数Schema执行函数”的结构。执行函数接收参数返回字符串或结构体。平台不关心执行函数内部是查数据库还是调HTTP接口。这里的关键是参数Schema要交给模型而描述要写得让模型一看就懂这两件事是工具能不能被正确调用的核心。记忆层对话历史、长期事实、任务中间状态都要通过一个Memory接口来读写。前期可以是内存里的一个列表后期换成Redis、向量数据库或SQLite都行。不要为了省事直接在各处操作“messages”数组那样一旦要做持久化、会话隔离你会想把键盘砸了。记忆层这一点我后面会专门展开。可观测层从第一天起就记录trace_id、调用时间、token消耗、工具调用序列、错误类型。很多团队等到线上出了诡异问题才亡羊补牢那时日志格式已经烂到没法分析。前期做轻量结构化日志花费不过半小时收益却是巨大的。你后面做评测、做成本治理、做问题定位全都依赖这一层。这四个层本质上都在做同一件事把“可能变化的点”隔离在接口后面。可演进系统的核心不是代码多漂亮而是“当需求变化时改动可以局部化”。你不需要一开始就把每一层做得很重但接口一定要留出来。2.3 自研轻量框架还是直接上LangGraph这类Agent框架在动手前得先做一个选择题完全自己写还是用现成的Agent框架我用过的框架不少也自己写过。这里给出比较主观的经验如果你只是想快速验证一个想法可以直接上LangGraph、Semantic Kernel这类框架它们已经把图状态、节点路由、记忆、工具调用模板都做好了很适合快速搭原型。但如果你要做的是一个长期演进、要接自己业务系统、要做定制化权限和审计的平台我很推荐“自研一个很薄的执行引擎按需引入现成组件”的路线。我并不是反对框架。恰恰因为我用得多才知道框架带来了什么抽象复杂、学习成本高、升级有迁移成本出了问题很难定位到底是自己代码的问题还是框架的问题。而且在模型飞速迭代的这两年很多框架本身都还在剧烈变动你辛辛苦苦学的API下个版本可能就废弃了。我自己踩过这个坑花了两周学一个框架的图编排结果换模型时发现某个核心概念在新版本里已经被替换掉了等于白学。自研轻量引擎听起来很吓人实际上核心代码可能不到两百行。最核心的无非是一个AgentExecutor循环判断模型返回的结果里有没有工具调用有就执行然后把结果回灌没有就结束同时设置最大轮数限制避免死循环。框架的价值在于帮你省掉这些样板代码但你自己掌握的是每个循环节点的控制权。对“可演进”这件事来说这个控制权至关重要。我建议的做法是先用现成框架跑通一个最小Demo理解整个闭环是怎么运作的然后自己照着写一个极简版本再逐步加能力。这样既有框架的启发又不会把命运完全交给一个快速变化的外部依赖。3. 实操把一个AI对话Demo演进成可跑通的Agent3.1 阶段一先做一个不含Agent逻辑的干净对话服务先用FastAPI写一个极简的对话接口。这个阶段不要急着加Agent逻辑先把“用户请求-模型响应”这条管道打通并且把后面要用的抽象接口留出来。很多人一上来就直接写工具调用循环结果基础通道都没稳定出了问题都不知道是哪个环节的锅。# app.py from fastapi import FastAPI from pydantic import BaseModel app FastAPI() class ChatRequest(BaseModel): session_id: str message: str history: list[dict] | None None class ChatResponse(BaseModel): reply: str trace_id: str app.post(/chat) async def chat(req: ChatRequest): reply, trace_id await handle_chat(req) return ChatResponse(replyreply, trace_idtrace_id)这里的handle_chat我暂时没有展开它至少要做三件事根据session_id取历史、组装请求调用模型、把回复追加到历史。你会发现session_id这个字段一开始就有了这是为了后面做会话隔离和记忆持久化留的口子如果一开始就做成无状态的单轮接口后面加状态会非常痛苦。session_id就像快递单号每一轮对话都要能追踪到具体的收件人。当时我踩的一个坑是直接用官方SDK的response.choices[0].message.content一段字段就返回完全没有处理stream。后来用户一多接口响应时长普遍在十秒以上体验很差。所以在阶段一就应该把streamTrue的开关加上前端用SSE接收虽然代码多几行但这个管道一旦建立后面所有能力都能在这个基础上加。你不想让用户盯着一个转圈圈十几秒才看到文本那就老老实实做流式。3.2 阶段二把工具调用嵌进主循环当你的对话服务稳定了下一步就把工具调用加进来。我建议先做两个最简单的工具一个是查天气的mock函数一个是查内部文档的检索函数。你不需要真的接入外部系统只需要让“模型能够请求工具、程序能够执行并把结果回灌”这条链路通起来。这一步的核心是验证闭环不是验证工具的准确性。# tools.py TOOL_WEATHER { type: function, function: { name: get_weather, description: 查询指定城市的当前天气, parameters: { type: object, properties: { city: {type: string, description: 城市名如北京、上海}, unit: {type: string, enum: [celsius, fahrenheit]} }, required: [city] } } } async def get_weather(city: str, unit: str celsius) - str: # 这里可以替换为真实天气API return f{city} 现在 22 度{unit}多云工具描述要写得“面向模型”不是面向人类。模型靠description来理解什么时候该用这个工具、参数怎么填所以描述里一定要写清楚触发条件和参数含义。我试过“城市名”这种描述模型经常把“深圳”当成“shenzhen”又拼不对后来改成“城市名必须是中文全称例如北京、上海、深圳”成功率立刻上去了。说白了写工具描述是在给模型做“产品说明”要越具体越好。主循环的写法是Agent的核心逻辑我习惯用伪代码优先表达。这段代码是整个平台的心脏每一步都值得你反复推敲async def run_agent(user_message, tools): messages load_history(user_message.session_id) messages.append({role: user, content: user_message}) for step in range(MAX_STEPS): # 比如10轮 response await llm.chat( messagesmessages, toolstools, tool_choiceauto, ) msg response.choices[0].message if not msg.tool_calls: messages.append(msg) return msg.content messages.append(msg) # 把包含tool_calls的消息放入历史 for tool_call in msg.tool_calls: result await execute_tool(tool_call) # 执行工具 messages.append({ role: tool, tool_call_id: tool_call.id, content: result, }) return 达到最大执行轮数已停止。这段代码第一次跑通的时候我会建议你故意让某个工具报错观察模型能不能理解错误信息并给出下一步方案。如果模型能根据错误调整说明你的链路是通的。如果模型反复调用同一个失败工具就说明缺少错误处理和重试策略这我在第五部分会展开。记住第一次跑通时别太兴奋故意搞点破坏再观察才是成熟的做法。3.3 阶段三加上记忆和任务状态机当工具调用链路稳定后用户开始会提更长的任务比如“帮我调研竞品A并对比我们的产品输出一份报告”。这种任务不是一轮能完成的必须拆成多步而且中间状态要能保存。这里就需要引入记忆和状态机。我当时的做法是做一个MemoryManager统一管理两类记忆。短期记忆是最近N条对话直接存数据库或Redis每次请求只带最近的一部分长期记忆是向量库把用户偏好、长期目标、重要事实等写入向量之后用相似度检索回来。初期不要做太复杂一个简单的实现长这样class MemoryManager: def __init__(self, history_store, vector_store): self.history history_store # redis / sqlite self.vector vector_store # 可选chroma / qdrant / faiss async def load_context(self, session_id, max_messages20): history await self.history.get(session_id) recent debounce_to_tokens(history, max_tokens4000) long_term await self.vector.search(session_id, top_k5) return recent long_term async def save_turn(self, session_id, messages): await self.history.append(session_id, messages) await self.vector.upsert(extract_facts(messages))任务状态机则是给每个复杂任务分配一个状态定义如下pending、planning、running、tool_call、waiting_user_input、finished、error。每条状态流转都记录成事件方便事后审计。有了状态机以后平台才能支持暂停、恢复、超时取消否则一个卡住的Agent就永远占着你的资源。这里有一个我反复强调的细节短期记忆不要一股脑把完整对话全塞给模型。一个简单规则是“按token预算裁剪摘要压缩”。先给最近对话预留60%的token历史太长的部分做摘要摘要本身再作为一条系统消息参与后续对话。这个方案能在“尽量保留上下文”和“控制成本”之间取得一个相对稳定的平衡。3.4 阶段四评测与可观测性越早做越省钱很多团队在Demo期完全不做评测上线后才靠用户投诉来发现问题。等用户来投诉说明已经产生信任损失了。我建议在Agent平台的第一天就搭一个最小的评测闭环一组golden case加上一个简单的自动评判器。评测用例至少覆盖几类场景常规问题、需要调用工具的问题、工具执行失败后能自我纠正的问题、连续多轮后的记忆保持问题。评判方式可以先简单粗暴人工看回复是否合格合格打1分或者用一个强模型当裁判给出“正确/部分正确/错误”的评分。后期再做更细的自动评估但先得把“有没有退化”这个问题解决。没有评测你就是闭着眼睛改代码。可观测性的核心是trace。每个会话、每次执行循环都记录下trace_id、步骤号、模型名、输入token、输出token、延迟、工具调用结果、错误类型。把这些写入结构化日志然后用简单的命令行工具或一个轻量面板查看。不要觉得这是额外的负担出了问题你会感谢自己当初多写的几行日志。logger.info({ event: tool_call, trace_id: trace_id, step: step, tool: tool_name, args: args, result: result, latency_ms: latency_ms, tokens: tokens_used, })在演进阶段这些日志就是你做评测、做优化、做问题排查的唯一依据。很多平台上复杂的“Prompt链路追踪”功能本质上就是这套日志的展示层。4. 工具调用、记忆与任务状态把关键能力做扎实4.1 工具注册中心从“一个函数”到“一个协议”当工具从两三个涨到二三十个你会立刻发现一个问题代码里散落着一堆if-else来分发工具新人根本不敢改模型也经常选错工具。我建议从第二十个工具之前就把工具统一收编进注册中心。注册中心的核心是一个字典key是工具名value是工具的完整定义包含name、description、parameters schema、execute函数、超时时间、权限级别、错误处理策略。在注册中心里工具实际上变成了一种“协议”而不是一段代码。你的Agent循环只需要遍历注册中心来动态组装tools参数执行时按字典分发即可。新增一个工具就是往注册中心里添加一条记录不涉及业务层改动。跟你把代码写进一个配置文件里的感觉差不多但比配置更结构化。在这个阶段我也建议统一工具调用的结果格式。不要有的工具返回纯文本有的返回JSON有的返回“成功”二字模型会很困惑。统一用结构体“状态码正文结构化数据”。比如失败时返回{“status”: “error”, “message”: “城市不存在”, “detail”: …}模型就能读懂并判断下一步该做什么。你甚至可以定义“工具调用协议版本号”将来升级时方便做兼容。4.2 记忆不是“把聊天记录全塞进去”我见过有人为了实现“长期记忆”直接用一张表把所有对话历史存起来然后每次请求前把全量历史拼进Prompt。这种做法的后果就是token爆炸和上下文混乱而且模型会从很旧的对话里捡出过时信息来回答效果非常差。这就像一个人背着十年日记去开会翻到哪页就看哪页能记住重点才怪。一个更务实的记忆设计是分层的第一层是“即时工作记忆”承载当前任务进行中的上下文通常就是最近几轮控制在token预算内第二层是“场景记忆”存储本次会话中用户明确表达过的偏好、任务目标、关键约束第三层是“长期事实记忆”用向量库保存跨会话的事实检索时按相关度召回。在实现上第三层最简单的方法是把用户消息做摘要摘要转成向量存进Chroma或Qdrant检索时拿当前问题向量召回。记忆还有一个容易被忽略的点内容要经过筛选。不要什么句子都往长期记忆里写只抽“用户确认过的事实”和“明确的任务要求”这类信息才有长期价值。我见过有人把用户随口说的一句“我最近在减肥”也写进了向量库结果模型在聊别的话题时莫名其妙把减肥建议拿出来说用户体验非常出戏。记忆系统要克制不是记录越多越好而是记录越准越好。4.3 任务状态机让Agent可中断、可恢复、可审计Agent平台区别于随手写的脚本最重要的一点是任务有生命周期。用户可能启动了一个耗时的调研任务跑了五分钟结果发现需求变了想换个方向。没有状态机的平台只能杀掉任务重新来所有中间结果全部丢失有状态机的平台可以直接把任务置为paused保存中间状态调整参数后从planning阶段重新启动。状态机的核心是事件驱动。每次发生一个事件比如tool_call完成、用户插入新消息、模型返回错误都会触发状态迁移。你可以用一张表记录current_state、event、next_state、context_snapshot这样任何一个任务的执行轨迹都清清楚楚。审计时回放这张表就行。这个设计还有一个好处任务可以被优先级调度。平台不再只是“同步接口”而是一个执行引擎。你收到新任务后可以立即返回“已受理”后台慢慢跑跑完推送给用户。很多所谓“Agent平台”其实只是写了一大堆异步任务队列却没有一个能表达Agent任务复杂周期的模型这才是最大的架构缺口。5. 演进过程中最容易踩的坑与兜底策略5.1 上下文膨胀与Token预算失控最常见的问题没有之一。我做过的Agent里最夸张的一次是用户连续对话二百多轮然后我直接把全量历史塞给模型结果先是请求超时然后是费用飙升最后模型开始“忘事”——因为被大量无关历史冲淡了注意力。解决思路是分层处理我再强调一遍。第一给每次请求设定一个硬性token上限比如总量不超过8K在这个预算内动态裁剪历史。第二超出的历史做摘要摘要独立存放需要时再取出。第三系统消息、工具描述、外部检索结果这三类内容要分开计数防止长工具描述把预算吃光。第四监控每个session的token消耗超过阈值时主动触发“精简对话”动作比如告诉用户“对话过长我可以帮你总结后继续”。很多人以为模型上下文窗口越大越好实际上多轮长上下文对注意力分配的影响是真实存在的不是窗口够了就万事大吉。与其把所有东西都塞进去不如训练自己的裁剪和摘要能力。可以这么说把上下文联当“无限大”的窗口用是新手最容易交的学费。5.2 工具调用循环卡死与重复错误这是Agent开发新手最容易碰到又最想摔键盘的问题。模型在工具调用失败后经常犯一个毛病换个参数再调一次又失败再换个参数……一直循环到步数耗尽。造成这个现象的底层原因是模型没有从错误信息里学到“这个工具当前不可用”这一事实或者是你的错误信息给得太不明确。给三条非常实用的兜底规则。第一配置max_steps一般10轮以内足够完成绝大多数简单任务超过了就立即终止并回退到“告诉用户需要简化任务”。第二对同一个工具连续失败N次比如3次后把该工具标记为禁用在下一次模型请求里不再提供它同时告诉模型哪个工具被禁用了。第三错误信息要结构化明确告诉模型“失败原因”和“可尝试的替代方案”而不是简单返回“调用失败”。另外工具本身要有超时处理。我用HTTP调用外部接口最怕的就是外部服务没响应那Agent就会卡在“观察”阶段。我的做法是给每个工具单独设timeout默认10秒超时后返回一个特殊错误类型让模型知道是超时而非参数错误。5.3 模型输出不稳定别指望“多试几次”在Agent场景里模型的输出稳定性比对话场景更重要因为一个格式错误的结构化输出可能让整个循环崩溃。常见问题是工具参数里多了一个字段、JSON里夹了一段自然语言解释、参数类型写错或者干脆没生成tool_call就开始幻觉回答。对策有几个层次。第一优先选择支持结构化输出或JSON Mode的模型接口如果支持尽量用。第二对模型返回的工具调用做schema校验不通过就让模型“修正你的参数并重试”而不是直接让程序崩溃。第三重试要有上限三次以上就切换为“无法完成当前工具调用”的兜底话术给用户。第四在工具描述里使用严格类型提示和必填项减少模型自由发挥的空间。我还会在开发期给模型固定一个低temperature比如0.1到0.2。Agent任务和聊天不一样需要的不是创意而是稳定。你可以在用户面对话层用更高的temperature在工具规划和执行层用低temperature这是两套参数不要混用一个配置。这个细节很多人不在意但对结果稳定性影响非常大。5.4 并发、超时与后端依赖雪崩当你的Agent平台从Demo走向正式使用并发是绕不开的。最典型的坑是工具函数里直接调用第三方API没有做连接池和熔断一旦第三方慢你的Agent线程全部卡在等待上新的请求也进不来最后整个服务雪崩。我的建议是所有工具调用都要走异步IO并且设置独立限流器。按照工具的吞吐能力分配信号量比如外部天气API每秒最多10次就在工具执行函数上套一个asyncio.Semaphore(10)。同时把第三方依赖做两层降级第一层超时降级第二层结果降级比如天气查询失败时返回“暂无实时数据请稍后再试”并用一个备用数据源兜底。平时没人注意这些细节一旦线上流量上来它们就是平台能不能活下来的关键。还要考虑“外部依赖不信任原则”。Agent每次调用工具都可能产生副作用比如发邮件、下订单、删除数据。这类高危工具一定要加审批环节状态机里预留一个waiting_user_input状态工具执行前必须先向用户确认用户确认后再放行。这是平台做大的必要条件也是工程上的底线保障。6. 常见问题速查、评测清单与“可演进”自检6.1 常见问题速查表我把Agent开发过程中最常遇到的十来个问题列成一张表你可以直接对照处理。这些不是理论全是实际踩出来的。现象可能原因处理建议模型不调用工具只会口头回答工具描述不够清晰或tool_choice设置为none拆细工具描述明确触发条件必要时用tool_choice强制选择调用工具参数频繁缺失参数Schema缺少必填项声明检查required字段使用strict模式并在描述里举例同一工具重复失败直到步数耗尽错误信息不明确或模型无法判断当前不可用错误结构化连续失败禁用工具设置max_steps兜底对话越长回答越差历史全量塞入无关信息干扰裁剪摘要控制Token预算工具调用结果回灌后模型忽略结果接着答工具角色消息格式错误或顺序不对检查tool_call_id是否正确对应消息顺序必须符合接口规范并发一高就超时工具调用阻塞无超时和熔断全部异步化加Semaphore限流设置单工具timeoutAgent“擅自”执行高风险操作缺少工具权限校验高危工具增加审批状态执行前必须用户确认模型输出JSON解析失败模型自由生成格式不保证启用JSON Mode或结构化输出校验失败让模型修正重试换了新模型后效果大跳水Prompt和工具描述依赖旧模型特性把Prompt和工具描述做成模型版本兼容评测集上跑回归调用量上来了费用高到不敢看没有Token监控和缓存看板监控成本系统消息缓存超长历史摘要化这张表不是公式不同场景表现可能不同但套路基本一致先复现看trace再针对循环里出错的那一环做调整。6.2 Agent评测从“感觉还行”到可量化Agent的评测比普通对话难得多因为它不是单一回复评判而是一串动作链。我建议至少从三个维度评估任务成功率、步骤效率、安全合规率。任务成功率好理解就是目标是否达成。步骤效率看完成同一任务消耗的步数和token两个Agent如果都能完成任务一个用3步、一个用12步这里面的成本差异是巨大的。安全合规率则是看有没有触发高危操作、有没有违反内容安全要求、有没有跑偏去执行不该执行的命令。评测集可以自己手写三五十条也可以从真实日志里挑。我一般会用“黄金集回归集”的组合黄金集是几十条包含关键能力的用例每次改动模型或代码后全量跑一遍回归集是历史线上失败用例的回放防止倒退。对Agent平台来说不设回归测试就等于裸奔模型一发新版你根本不知道哪里坏了。今天你觉得“凭感觉还可以”明天用户就会用一张截图教你怎么做人。6.3 “可演进平台”自检清单最后给你一份判断自己的项目“有没有资格称得上平台”的检查清单每一条都是我在实际项目里被反复验证过的模型支持几种了是不是改一个配置就能切换到另一种包括本地部署模型工具总量超过10个后代码结构还能不能轻松加第11个每个任务的执行轨迹能不能一键回放出问题能定位到具体哪一次调用吗Token消耗、延迟、成本有没有一个看板能看同一套逻辑能不能在同步接口、异步任务、定时任务三种触发方式下复用高危工具有没有权限管控和人工审批会话和任务是不是隔离的两个人同时用会不会串数据有没有一套用例能在半小时内验证“这次改动没把平台改坏”如果这些问题里有三个以上你答不上来那你还处在Demo阶段只是装饰得像个平台。别急着铺功能先把这几根支撑柱子立起来。我个人在实际操作中的体会是很多项目不是输在技术难度上而是输在“Demo期太爽演进期太痛”这种节奏错位上你能越早意识到自己是“在建平台”而不是“在写调接口的脚本”后面就越省力。另外再分享一个小技巧无论你用什么框架一定要让自己能“零成本地换模型提供商”。哪怕你现在只有一个模型也在代码里把模型名、API地址、密钥这些都做成可配置项。等你某天因为成本、效果或者合规原因要切换到另一个模型时你会感谢当初多写的这几行配置。Agent平台的核心从来不是某一个模型有多聪明而是你的整套系统有多抗变化。