说起 Agent 开发很多人第一步会去调模型、调 prompt模型跑通了又发现整条链路像一团乱麻一会儿让模型直接调用工具一会儿在代码里写死逻辑改一个需求要动好几个地方。这套东西我断断续续折腾了小半年最后发现真正让 Agent 从“能跑”变成“好用”的不是模型本身而是背后那层技能体系。这个项目叫“agent-skills”说白了就是给 Agent 配置一套可注册、可编排、可测试的技能库把模型的能力边界、工具的调用方式、业务的处理流程全部做标准化。这次就把这套体系从设计到落地的完整思路写出来适合正在做 Agent 应用、被多工具调度和复杂任务拆解搞到头大的开发者参考。1. 先想清楚Agent 技能体系到底在解决什么问题1.1 从一场翻车事故说起去年我参与过一个客服场景的模拟项目X初期方案特别粗暴把所有业务逻辑写进一个大 prompt让模型“看着办”。模型需要查订单、退换货、算运费、转人工全凭它现场发挥。结果上线第一周就翻车几个典型问题至今记忆犹新。模型把“查询订单”和“修改地址”两个动作混在一起用户说“帮我改一下昨天那个订单的收件人”它直接调了查单接口查完发现没有修改权限又绕回来问用户要订单号。一来一回多耗了好几轮对话用户体验很差。更麻烦的是排查问题的时候根本看不出来模型哪一步想错了因为所有逻辑都在模型脑子里日志里只有一串 prompt 和一段完整输出中间发生了什么全靠猜。这次事故让我意识到一个关键问题模型本身不是一个稳定可靠的任务执行器它强在理解和生成弱在按固定流程执行。如果让模型直接面对所有工具和所有业务规则它一定会出错而且出错方式千奇百怪。正确做法是把“模型擅长的理解决策”和“系统擅长的稳定执行”拆开中间加一层技能层。1.2 技能库和一条 prompt 写到底差别在哪很多人觉得技能体系不就是把工具函数包装一下吗其实差别很大。工具函数只是给模型一个可调用的函数而技能是一个完整的任务单元它包含触发条件、输入输出协议、执行逻辑、异常处理、权限说明甚至包含给模型看的“使用说明书”。这两者的本质区别在于职责边界。工具函数是“模型说调就调”参数错了就报错模型自己想办法技能则是一个半自主的执行单元它会校验参数、做前置检查、处理部分异常甚至在不明确的时候主动向模型反馈需要补充哪些信息。技能层存在的意义就是把模型的能力圈在一个可控范围内让模型只做它擅长的事理解用户意图、拆解任务、选择技能、组织答案。另外还有一层好处是复用性。工具函数和业务逻辑耦合在代码里换个场景就得重写技能定义是独立于业务之外的同一个“查订单”技能可以放在客服场景、售后场景、内部工单场景里复用只要把底层数据源接好就行。项目里我们最后沉淀了三十多个技能覆盖了大概百分之八十的常规操作新场景接入时基本不用写新代码。提示判断一个操作该不该做成技能可以简单套两个标准模型对这一类任务的准确率是否稳定、这一类任务是否会被多个场景复用。两个都中就值得做一个技能。2. 技能定义规范让模型“看得懂”技能的关键细节2.1 技能元数据不只是名字和描述技能的元数据设计是整个体系的地基。最早期我偷懒技能描述随便写两句比如“查订单”。结果模型经常选错技能或者参数填不对。后来参考了成熟方案后反复迭代总结出一套相对稳定的模板。一个完整的技能定义大概包含这些字段技能名称、一句话简介、详细使用说明、触发条件、参数列表、执行前置条件、返回值格式、典型示例。名称和简介好理解关键是详细使用说明和触发条件这两块最容易被忽视但恰恰是模型选对技能的关键。另外还有两个容易遗漏的字段技能之间的冲突说明和技能的限制条件。比如某技能和另一个技能看起来很像就要写清楚“当你需要计算运费时使用本技能不要使用订单查询技能”这种负向引导在实测中对选型准确率提升很明显。我处理过最典型的一个例子两个技能分别是“查询库存”和“创建采购单”对一个做进销存助手的 Agent 来说用户说“这个货还有吗”应该触发查询库存用户说“这个卖完了怎么办”才涉及创建采购单。如果没有冲突说明模型很容易在“缺货”场景直接去创建采购单这就有风险了。加上负向引导之后误触发率从大概百分之十八降到了百分之三左右。2.2 描述和参数设计的实操写法描述怎么写才能让模型准确理解和调用我的经验是一件事一句话讲清楚然后展开给模型具体指引。好的技能简介应该包含这个技能做什么、在什么场景下使用、能达成什么结果。然后详细使用说明补充这些内容适用的业务对象、执行逻辑的关键步骤、常见的边界情况、输入输出示例。举个例子这是我在项目里做过的一个“订单改址”技能的描述结构name: modify_order_address description: - 修改未发货订单的收货地址。仅适用于订单状态为「待发货」或「已付款」的订单。 当用户要求变更收货人、联系电话、收货地址时使用本技能。已发货订单请使用 logistics_intercept 技能处理。 parameters: order_id: type: string required: true description: 订单编号通常以 PO 开头如 PO20250312-001 new_address: type: object required: true properties: receiver: { type: string } phone: { type: string } region: { type: string } detail: { type: string }参数设计这里有个关键点参数描述也要当成给模型的说明来写必须要写清楚这个参数的格式、取值范围、常见格式示例。比如 order_id你只写“订单号”三个字模型可能会把用户说的话原文扔进来你写清楚“通常以 PO 开头如 PO20250312-001”模型就知道从对话里提取订单号时要做格式化。另一个容易出问题的地方是参数冲突。比如一个界面查询技能的参数里既有“起止时间”又有“最近 N 条”模型可能两个都填或者填了这个忘了那个。解决方式是在参数描述里写互斥说明也可以在技能实现层做参数优先级处理。我在实际项目中两种都用描述里写清楚“二选一优先使用最近 N 条如果用户提到具体时间范围则忽略最近 N 条”代码层再加一道校验两个同时传了就丢弃时间范围参数。注意参数校验代码里要对必填参数做显式检查。模型经常漏传参数与其让底层接口报错不如技能层统一拦截并返回清晰的提示信息引导模型追问缺失参数。3. 技能引擎落地注册、路由、编排与容错3.1 技能注册中心与模型路由技能定义写好后需要一个运行时来管理它们。我是拆成两层来实现的注册中心和路由层。注册中心负责加载全部技能定义生成一个技能清单路由层负责把用户的输入结合对话上下文交给模型去选择要调用的技能把模型选中的技能标识和参数传给执行器。路由的实现方式有两种思路一种是纯模型决策把全部技能描述和用户问题一起交给模型让模型输出技能名和参数 JSON。另一种是预处理加模型决策先把用户输入做意图分类或者关键词匹配缩小技能候选集再让模型从候选里挑。纯模型决策的好处是灵活坏处是技能数量一多就乱。实测下来技能数量超过二十个的时候模型的选择准确率明显下降大概是每增加十个技能准确率掉五到八个百分点。我在项目里最终用的是混合方案先跑一个轻量分类器把技能按业务域分组用户输入先匹配到两到三个候选域再让模型在候选域的技能里做精确选择。这样准确率基本能稳定在百分之九十五以上。路由层还有一个细节要注意模型输出的技能名要容错。模型经常会把技能名写错比如多了下划线、少了前缀、用了简称。我的做法是在匹配时先做精确匹配匹配不上就做归一化匹配把下划线、中划线、大小写全部统一后再比对再匹配不上就用编辑器距离距离小于等于二就视为命中。这一层小小的容错让很多奇葩输出都能被正确处理。3.2 技能编排串行、并行与条件跳转单个技能能解决的任务很有限复杂业务场景需要多个技能配合。技能的编排方式是整个体系里最需要设计的部分。我把编排抽象成了三种基础模式串行、并行、条件路由。串行最简单就是做完一步再做下一步。比如退款流程先查订单状态再查退款规则再执行退款。并行适合多个互不依赖的查询同时做比如用户问“我昨天买的两个订单分别到哪了”两个查询订单技能可以并发执行然后合并结果。条件路由就是根据上一步的结果决定下一步走哪个分支比如查询订单返回“已发货”就走物流跟踪返回“待付款”就走支付引导。编排在代码层面的实现我一开始用的硬编码状态机每个业务流程写一个类流程一变就要改代码。后面重构成了声明式编排用配置描述流程而不是写代码描述流程。这样就可以在不改代码的前提下调整技能调用顺序和分支逻辑。flow_name: after_sale_flow steps: - id: step1 skill: check_order_status next: step2 - id: step2 skill: check_return_rule condition: - if: {{step1.status}} 待收货 next: step3 - if: {{step1.status}} 已签收 next: step4 - id: step3 skill: create_return_order - id: step4 skill: notify_manual_service这个配置式编排的好处除了不改代码还能让流程可视化。项目里我做了个简单的流程解析器把 YAML 配置渲染成流程图给业务同学看他们能直接提意见而不需要看懂代码。这算是额外收获对协作效率提升明显。3.3 技能执行中的容错和降级技能执行过程中出错是常态关键是怎么让错误不影响整个 Agent 的稳定性。我归纳了三类常见错误和对应处理策略参数错误、执行异常、结果异常。参数错误一般发生在模型传给技能层的参数不合法比如时间格式错了、金额为负、订单号不存在。这类错误技能层直接拦截返回固定格式的错误提示让模型看了提示之后重新组织参数再调用。这里有个细节错误提示要写清楚错在哪、怎么改比如“time_start 格式应为 YYYY-MM-DD当前值为 2025/03/01”模型看到之后基本能一次改对实测二次调用成功率很高。执行异常指的是底层服务报错比如数据库连不上、第三方接口超时。这种情况技能层要做重试。重试策略我一般用指数退避加最大次数限制比如最多三次间隔一秒、两秒、四秒。重试都失败就返回一个业务兜底提示让模型告诉用户“系统繁忙请稍后再试”同时这条错误要记录到日志里方便事后排查。结果异常是更隐蔽的一类执行成功了但返回的数据明显有问题。比如查询订单返回空列表但订单号明显存在或者金额字段返回负数。一般底层服务不会这么离谱但只要出现了模板渲染就会出现问题。我的处理方式是在技能实现里加一层结果校验对关键字段做合法性检查不合法就按异常处理走降级分支避免脏数据直接透传到模型那里让模型基于错误数据给出错误答案。4. 从测试到上线技能体系的评测与迭代闭环4.1 技能评测集的建设方法技能做出来是要测的但怎么测很多人没有头绪。我给项目建了一套评测集核心思想是每个技能都要有专属的评测数据不能只靠人工点几个用例就算完。评测集包括两部分单技能评测和全链路评测。单技能评测针对每个技能造一批该技能的典型输入覆盖正常情况、边界情况、异常情况。全链路评测则是模拟真实用户对话从用户第一句话开始看整套技能编排是否正确走通。以“订单改址”技能为例单技能评测的正常情况包括“改了收件地址”“改了电话”“同时改地址和电话”边界情况包括订单已发货、订单已签收、订单号不存在异常情况包括用户没说清要改什么、改的地址不完整。每种情况都要准备十条左右的变体模型选技能和填参数的表现分别打分。评测打分我用的方法是把每一步的中间结果都保存下来包括模型选中的技能、填写的参数、技能执行结果然后逐项比对预期。这个评测集跑一次全量大概要十几分钟每次改技能描述、改路由逻辑之后都跑一遍能及时发现哪个技能的准确率掉了。如果没有这套评测改了一个地方导致另外几个技能选择错乱这种回归问题很难注意到。4.2 性能优化与超时控制技能体系引入之后Agent 的响应链路变长了用户输入 → 路由模型调用 → 技能执行 → 结果返回 → 组织答案。每一步都有耗时整个链路很容易超时。我把链路上每个环节的耗时做了埋点最早期的一次完整调用平均耗时接近八秒完全不可用。主要耗时在三个地方路由模型调用、技能内部多个串行子请求、最终的答案生成。优化从三个方向同时下手路由模型改用小模型速度快不少对选择准确率影响很小技能内部的串行请求改成并行比如查询订单基本信息后可以并行查询物流和商品详情能省掉一半时间答案生成改用流式输出用户不用等全部生成完才能看到内容。超时控制也很关键我在整个链路里做了逐级超时设置模型路由单次最多三秒技能执行单次最多五秒全链路总计最多十五秒。设置超时预算可以让系统在异常情况下尽快回退而不是傻等。比如底层接口很慢五秒内没返回技能层就返回超时提示模型收到之后引导用户稍后再试至少不会让用户干等。4.3 上线前后的十个踩坑记录这个项目里踩过的坑很多都是线上环境才暴露出来的我把其中最典型的十个整理一下第一个坑是技能描述写得太文艺模型理解不了。一开始写“本技能用于处理用户对订单收件信息的修改诉求”模型经常误触发。改成“当用户要求变更收货人、联系电话、收货地址时使用本技能”准确率立刻上来。技能描述不是作文宁可啰嗦也不能含糊。第二个坑是参数描述缺少示例值。模型不知道订单号长什么样就不知道怎么从对话里提取。加了“如 PO20250312-001”之后提取准确率提升非常明显。第三个坑是技能数量膨胀。一开始见什么加什么到了三十几个技能之后模型选型已经混乱了。后面狠心砍掉低频技能把一些相似技能合并数量降到二十个左右效果反而更好。第四个坑是缺少负向引导。两个技能功能相近时模型很容易选错。在描述里明确写“不要使用 XX 技能处理本类问题”能明显改善误触发。第五个坑是默认参数处理随意。有些技能有几个常驻参数每次调用都要从上下文里提取模型经常提取不准。改进方式是技能层维护一个上下文缓存上一轮已经确认过的参数自动代入省去重新提取。第六个坑是错误信息太笼统。模型调用技能失败后返回“参数错误”四个字模型根本不知道错在哪。改成具体错误说明加修正建议之后二次调用成功率从五成提升到八成以上。第七个坑是不做结果校验。底层服务偶尔返回异常数据模型拿到之后可能一本正经地生成答案用户就会看到明显错误的信息。加了一层字段校验之后这方面的投诉基本归零。第八个坑是忽略超时。技能内部串行调用太多接口慢的时候整体响应时间爆表。改了并行调用和分级超时之后P95 响应时间降低了大概百分之四十。第九个坑是日志记录不足。早期出问题只能看到模型输出看不到技能执行中间过程。后来在路由层和执行层都加了结构化日志每次调用记录技能名、参数、耗时、返回码、错误信息排障效率高很多。第十个坑是评测集跟不上迭代。技能改了描述或者底层逻辑评测数据不更新回归测试形同虚设。后来养成习惯每次技能变更必须同步更新评测集先跑题再合代码。5. 常见问题速查表与排查思路现象可能原因排查方法模型频繁选错技能技能描述不清晰、缺少负向引导、技能数量过多检查技能描述是否说清楚触发条件增加“不要使用本技能处理 X”的说明减少功能重叠的技能技能参数频繁填错参数描述缺少格式说明和示例值在参数描述中补充参数格式、取值范围、典型示例技能内部接口超时底层服务慢、技能内部串行调用过多优化技能内部为并行调用设置单技能超时上限增加重试策略技能执行成功但返回数据异常底层服务返回脏数据、缺少结果校验在技能实现层增加关键字段合法性校验异常数据走降级分支修改一个技能后其他技能表现变差技能描述间互相干扰、模型上下文被挤占精简技能描述长度检查技能描述中的冲突说明跑一遍全量评测集定位回归全链路响应时间过长路由模型慢、技能串行调用多、生成阶段长路由改用小模型技能内部并行化结果生成流式输出模型二次调用仍失败错误提示信息不具体模型无法修正错误提示写清楚错在哪、期望值是什么、当前值是什么排障时信息不足日志缺失技能执行中间过程在路由层和执行层增加结构化日志记录参数、耗时、返回码、错误信息排查问题的时候我的习惯是先看日志从路由决策开始逐步往后查。如果模型选错了技能优先检查描述如果技能选对了但参数错优先检查参数说明如果参数对但执行失败优先查底层服务和异常处理。按这个顺序一步步来大多数问题都能定位到根因。个人体会是技能体系的调试很像写 API 文档模型就是调用方你的技能定义写得越清楚、越具体、越有例子调用方的表现就会越稳定。很多人抱怨模型能力不行其实往往是说明文档不到位。6. 写在最后的几条实战心得做“agent-skills”这个项目我最大的感受是Agent 开发的复杂度和模型能力是两回事模型再聪明没有一套可维护的调用框架最后也会乱成一锅粥。技能体系本质上就是把业务经验结构化把该交给模型的交给模型把不该交给模型的留在系统里。有一条经验想再强调一下技能描述一定要根据评测数据持续迭代不要觉得写完就可以。我在项目中做过统计同一套技能描述迭代三轮之后模型的综合准确率从百分之七十四提升到了百分之九十二。这个数据说明技能描述还有很大的优化空间值得花时间打磨。这套技能体系也可以继续扩展比如给技能加版本管理做 A/B 测试对比不同描述的实际效果比如把技能执行数据反馈回评测集自动发现新的边界情况这些方向后续如果做了我再来分享具体方案。