直接割开讲Agent写出来的东西乱不乱很多时候根本不在模型聪明不聪明而在于你有没有给它一套“放东西的地方”。我接手过好几个所谓的智能体项目最初都奔着“让模型自己搞定一切”去结果跑了两周就开始出现同一个工具在不同任务里行为不一致、写死的指令覆盖了通用规则、新加一个能力要把整个调用链翻一遍这种破事。后来我把注意力从“调模型”挪到了“搭技能体系”问题一下少了大半。这篇就是把我踩过的坑、整理出来的套路、还有现场排查的经验完整写出来适合正在做Agent应用、被多工具管理搞得头大的开发者参考。1. 为什么Agent会越用越乱1.1 从单一指令到多技能混杂很多项目一开始其实很清爽。一个Agent只干一件事查天气、写周报、做个简单问答。这时候所有逻辑都塞在系统提示里加上一两个函数调用跑得又快又准。可一旦业务开始扩展同一个Agent要处理数据分析、文档生成、外部接口对接、多轮任务规划原来的“单条大Prompt 散装工具”就会迅速失控。我见过一个典型状态项目里积累了大大小小二十几个工具函数有的叫get_info有的叫search_data参数命名五花八门返回值结构也不统一。模型在决策时根本分不清哪个该用经常调错。更麻烦的是这些能力没有明确的边界一个工具改了返回值格式连带另外七八个工具全跟着遭殃。这个阶段表现出的症状就是同一个问题今天答得对明天答得偏再问一次又换一种答法。所以“告别混乱”的第一步不是换更强的模型也不是粗暴地把工具数量砍掉而是把Agent的能力从“散装函数列表”升级成“有边界、有规范、可组合”的技能体系。所谓技能就是把一组相关的工具、提示词片段和执行规则打包成一个独立单元让Agent知道自己“在什么场景下能做什么、怎么做、做不了什么”。1.2 混乱的三个典型来源把混乱归因于“模型不行”是偷懒的。我复盘下来问题其实集中在三个地方第一是责任边界模糊。两个技能都声称能处理同一种输入Agent只能靠猜。比如既有一个“生成摘要”技能又有一个“提炼要点”技能表面看都行实际输出风格完全不同。模型选哪个纯看当时Prompt的措辞结果自然不稳定。第二是缺少统一的调用契约。有的技能是纯文本输入有的要求结构化Json参数有的还会主动去读文件。互相之间没有规约Agent在执行多步任务时前一步的输出根本没有办法平滑地变成下一步的输入只能在中间胶水层做重试和修正。第三是变更没有约束。改一个技能就像拆一颗雷你不知道谁在依赖它。线上Agent还在跑旧任务新版本的技能已经上线没有灰度没有兼容策略旧会话调多了就出行为分叉。这三个来源本质上都是管理问题。技术层面的模型能力反而往往是够用的。明白了这一点后面整套设计思路就顺了。2. 技能设计把Agent能力当工程做2.1 技能边界划分的黄金规则我建议在设计技能时先问三个问题这个技能负责哪一类任务它跟别的技能在输入上会不会重叠它执行到一半失败时调用者能不能理解为什么失败如果三个问题都能明确回答那这个技能的边界基本是清醒的。实际操作中我用一条很朴素的规则来切分按“业务动作”切不按“技术动作”切。举个例子同样是调一个内部接口获取数据“获取销售日报”是一个业务动作它可以包含读取接口、解析字段、格式化输出三个技术步骤而“发送邮件通知”是另一个业务动作。但如果有人把“调用HTTP接口”做成一个通用技能那就麻烦了所有联网类任务都会去复用它参数膨胀到无法维护异常处理也根本写不完整。边界清晰的技能应该像功能单一、接口明确的小组件。它内部可以很复杂但对外只暴露一个动作、一组入参、一个标准返回。这样Agent在决策时只需要在一个清晰的技能列表里做选择题而不是在一团缠在一起的逻辑里做推理题。关于技能粒度我踩过的最典型的坑就是过度拆分。把“发送邮件”拆成“连接SMTP”“格式化正文”“调用发送接口”三个技能看起来合理但对Agent来说毫无必要。模型每一步都要做一次工具选择选择越多出错概率越高。合理的粒度应该是“一个技能能独立完成一个用户可见的结果”比如发邮件、生成报表、搜索知识库而不是底层实现的一个环节。2.2 技能接口与参数设计原则接口设计的核心是让Agent“容易用对”。我见过很多技能定义写得像给程序员看的API文档对模型来说全是噪音。第一个原则是参数宁少勿多。每个技能暴露给模型的参数控制在三到五个以内。多余参数能内部推导就内部推导能合并继承就合并继承。一开始我做技能参数动辄十几个模型经常漏传或者乱传导致大量校验失败。后来把一半参数改成可选、带默认值或者干脆从上下文里自动获取错误率肉眼可见地下降。第二个原则是描述要写“什么时候用”而不是只写“能干什么”。模型的工具选择其实依赖的是描述里的场景信号。比如你写“用于计算两日期之间的工作日数量”模型在匹配“项目要排期到月底帮我看下还剩多少工作日”时不一定会选中它但如果你写“当用户询问剩余工作日、排期耗时、任务截止日期时使用”匹配率立刻高很多。技能描述本质上是在帮模型做意图分类写得好不好直接决定调用准不准。第三个原则是返回结构要带上“执行状态”。不要只把结果丢给模型还要让模型知道这次调用到底成没成、成到什么程度。我通常会在返回里附加一个机器可读的状态字段比如success、empty_result、needs_human并配上人能看懂的说明文字。这样Agent可以自己决定继续、换方案还是停下来问用户而不是在被一个失败结果困住之后反复空转。3. 实战抓一把搭一套可维护的技能体系3.1 第一步建立技能清单与目录结构动手之前先把现状完整盘一遍。我做这件事的方法很简单把所有现有的工具函数、Prompt片段、甚至临时写在业务代码里的处理逻辑全部列出来逐条打上标签标签包括“业务场景”、“输入依赖”、“产出结果”、“负责人”、“最近修改时间”。这个清单就是整套技能体系的底账。底账有了之后再按业务动作归类每组动作对应未来一个技能。老的工具函数能并则并能拆则拆但原则是只做映射不做重写。不要一边重构一边改业务那样风险和混乱会叠在一起。目录结构我习惯用三层不太深但要稳定skills/ {技能名}/ SKILL.md payload/ assets/ tests/SKILL.md是技能的说明文件也是Agent会读到的核心描述里面写清楚触发场景、参数定义、执行流程、注意事项。payload放执行逻辑可以是Python脚本也可以是调用外部API的配置文件。assets放技能依赖的模板、静态资源。tests放针对技能的测试用例和样例输入输出。这套结构看起来琐碎但它把所有“让Agent能力运转起来的信息”收拢到了一个技能目录里。新人接手任何一个项目只要打开对应技能目录就能在两分钟内搞明白这个技能是什么、怎么调用、边界在哪不会再去邮件列表和代码注释里考古。3.2 第二步技能注册与统一调度目录建好之后下一步是把技能注册到一个统一的服务里。我通常维护一个技能注册表格式类似这样skills: - name: generate_daily_report version: 2.1.0 entry: ./payload/main.py description: 当用户需要查看或汇总每日业务数据时使用 parameters: - name: date required: false type: string default: today on_error: report_error_and_ask注册表的核心价值是让Agent始终只面对一个“入口调度器”而不是一堆散装工具。调度器读取注册表、把技能按场景索引好然后暴露给模型统一调用。模型不需要知道技能内部写在哪个文件、用什么语言实现它只需要知道“有这个名字、这几个参数、什么时候用”就够了。统一调度还带来一个额外好处可以在入口统一做权限校验、参数校验、超时控制和审计日志。以前技能各自为战的时候安全策略很难统一下发现在所有调用都必须经过调度层你可以在一个位置控制谁能用哪个技能、调用频率上限是多少、敏感参数要不要脱敏。这些能力在前期可能看不出价值等Agent接入真实业务数据时就成了刚需。3.3 第三步编写技能文档与自检清单技能文档不是给领导看的PPT是给模型和同事看的说明书。我把SKILL.md当作给模型的“省流版指令”要求它正面回答五个问题触发这个技能的场景是什么绝对不能触发它的场景是什么有哪些参数每个参数的具体含义和格式是什么执行结果的返回格式长什么样失败时可能的原因和提示话术是什么写描述时我强烈建议用“用户原话的近似表达”去举例而不是抽象归纳。比如一个查库存的技能你写“当用户问还有货吗、库存够不够、什么时候能补货时触发”比写“用于查询库存状态”要靠谱得多。因为模型在生成调用时是在做意图匹配你的描述越贴近真实用户表达匹配越准。自检清单是给技能上线前用的。我每次提交一个新技能或改版技能都会过一遍清单内容不多但每一条都拦过真实问题参数默认值是否安全是否有样例输入输出技能内部有没有硬编码的临时路径返回结构是否对齐了统一格式如果技能内部依赖外部服务是否处理了超时和异常这些检查看起来琐碎但是能做到位的团队几乎都能把生产事故消灭在发布前。4. 让技能库长期健康运行4.1 版本管理与灰度发布技能库和代码库一样必须做版本管理。我见过不少项目直接原地修改技能文件改完就生效旧会话还在执行结果技能行为在时间线上出现了断层。正确做法是给每个技能打语义化版本号大版本号代表接口或行为不兼容的变更小版本号代表兼容性修正。所有调用记录里必须带上版本信息这样线上出了问题可以快速定位是哪个版本的哪个技能导致。灰度发布在个人项目里听起来很重但其实可以用很轻的方式实现。我会先把新版本的技能注册到测试环境用一批历史对话记录做回归看触发率和调用准确率有没有明显变化。确认没问题之后再按比例放量到线上比如先让百分之十的请求走新版本观察错误率和超时率稳定了再放开。新旧版本共存期间调度器需要用路由规则控制流量。我的做法是注册表里保留两份技能配置线上流量默认走老版本通过链路标记切换部分请求到新版本。这样既不用一次性冒险全量切换又能在出问题时一秒回滚。4.2 技能评测与淘汰机制技能多了之后最危险的不是数量大而是“僵尸技能”。有的技能上线时很香后来业务逻辑变了它隐含的前提已经失效但注册表里还挂着Agent偶尔还会选中它输出结果莫名其妙。所以我强制自己每个季度做一次技能健康巡检。巡检动作包括从过去三十天的调用日志里找出每个技能的调用次数、调用成功率、平均耗时、用户对结果的后续反馈、以及模型触发它之后的纠错频率。调用次数持续走低、成功率长期不达标、或者用户经常对它的输出追加纠正要求的技能就要降级为beta状态并从默认注册列表中隐去或者直接进入重新设计流程。这套淘汰机制的价值在于它会逼着你为每个技能找到“存在的理由”。没有理由的技能留着只会在模型做选择时增加干扰项。毕竟对Agent来说技能列表里有一百个选项和十个选项决策难度完全不在一个量级保持列表足够精简本身就是一种性能优化。评测里面最难的是什么是“输出质量”的自动化判断。因为Agent技能的结果很多是自由文本没办法完全靠断言去测。我的折中方案是让每个技能在返回结构里加入“自评置信度”再结合调用后续是否有用户纠错来判断。同时定期抽一批真实case放到人工评价集里让项目同学按统一标准打低中高分用这个分数修正技能方向。全部依赖线上日志容易失真全部依赖人工又撑不住速度两边配合着来才是可持续的。5. 常见问题与排查技巧实录5.1 技能冲突与调用错乱最典型的症状Agent明明该用A技能却调了B技能或者一次任务里反复横跳。这种问题排查时先别骂模型回去看技能描述。我遇到过一例一个技能叫“生成会议纪要”另一个技能叫“总结对话内容”。从人类视角看一个偏产出文档、一个偏提取要点挺清楚。但对模型来说触发场景高度重叠都是“给我总结一下这段对话”于是经常选错。解决方案也很朴素要么合并成一个技能要么在描述里把边界写到极致比如明确写明“当用户要求输出会议纪要文件格式时使用本技能当用户只需要口头要点时使用另一技能”。另一个常见错乱来源是技能名称太像。两个技能一个叫fetch_report一个叫get_report_data模型在生成函数调用时真的会搞混。我的建议是技能命名遵循“动词 业务对象 复用后缀”的格式比如generate_daily_report、search_order_records并确保任意两个技能名称的首词和核心词都不重复。5.2 请求超时与性能瓶颈技能内部一旦涉及外部API调用超时问题就会冒出来。Agent等待技能返回的过程是在消耗模型的推理窗口和用户耐心。我处理高频调用技能的耗时一般用三层策略。第一层给每个外部依赖单独设短超时比如三秒不把整个技能的执行时间押在一个慢接口上。第二层对读类操作做缓存相同参数的结果在短时间内直接复用这个优化能把报表生成类技能的平均耗时砍掉一半以上。第三层对确实无法快速完成的长任务不要把同步阻塞的结果丢给Agent而是直接返回“任务已受理”状态和进度查询方式让Agent告诉用户稍后查询避免一次调用卡死整轮对话。还有一个容易忽略的性能点技能返回的文本长度。有的技能把一堆原始接口数据原封不动塞给模型上下文直接爆炸后续对话全被稀释。我要求每个技能至少做一次字段裁剪和摘要只返回对当前任务有用的信息必要时把完整数据写入临时文件并返回文件路径让Agent按需读取。5.3 场景复原与调试手段技能调得多了你会发现最难的不是写代码而是“复现现场”。同一个技能用户在特定上下文里触发得到错误结果但程序员本地复现时又一切正常。原因是本地调试环境里根本没有用户那几十轮上下文。我的调试套路是把线上出问题的会话完整导出包含全部历史消息和技能调用细节单独成一个回放用例然后把这个用例喂给技能调度器让技能在沙箱里重跑一遍同时在技能代码里加上结构化日志把入参、分支选择、外部响应、最终返回全部记录。这样问题就能一步步定位到具体环节而不是靠猜。结构化日志格式我习惯统一用Json行每行包含时间戳、会话ID、技能名、版本、入参摘要、状态、耗时。出问题时直接在日志平台里按会话ID拉出完整链路一眼就能看出是哪个节点慢、哪个节点报错、哪个节点返回了脏数据。这个习惯早建立早省心技能少时好像无所谓等技能数超过二十个再补那工程量可就大了。技能开发调试过程中还有一个比较隐蔽的问题模型的工具调用跟技能实际执行结果可能不一致。比如技能内部已经做了容错把失败包装成了空结果但模型并不理解这个空结果照样煞有介事地往下编。这种问题的根治办法就是我在接口设计里强调的——返回结构必须带上机器可读的执行状态字段调度器在返回给模型之前把失败状态统一改写成明确的提示语模型就不会硬着头皮编了。结尾做了这么多项目我个人最深的体会是Agent的能力边界其实是靠技能体系圈出来的。模型负责临场发挥技能负责兜住底线。混乱往往不是模型的错而是你没有给能力一个规矩的存放方式。每当我遇到Agent行为飘忽、工具越加越难用我第一反应永远是回头检查技能列表而不是一味调Prompt。最后再分享一个小技巧技能变多之后定期做一次“删除演练”。假设明天必须砍掉三个技能哪些项目还能正常转如果砍掉谁都无所谓那说明它们就是冗余项。少而精的技能库比大而全的杂货铺稳定得多。这个习惯帮我省掉了无数个“守护线上Agent”的深夜。
