聊到Agent开发绕不开的一个词就是Skills。我最近在折腾一个内部项目agent-skills核心是想把散落在各个业务系统里的能力统一封装成一套Agent可调用的技能体系。做完这一轮最大的感受是Agent的智商上限很大程度上取决于技能体系的设计水平——模型能力再强技能定义得稀烂跑起来照样像无头苍蝇。这篇文章我不打算写那种特别空的概念科普而是把从技能定义、粒度拆解、编排调度到技能库管理这一整套链路里的实际操作思路和踩坑记录拿出来晒一晒。适合正在做Agent应用、想把手头工具升级成技能体系的团队参考也适合刚接触Agent开发、想知道技能和普通的工具调用到底差在哪儿的开发者。1. Agent技能到底是什么先厘清概念再动手很多团队一上来就写代码结果做着做着发现自己和API封装较了半天劲压根没摸到技能体系的边。我先用大白话把概念捋清楚。1.1 从工具调用Function Calling到技能体系的演进最早做Agent大家用的都是Function Calling也就是模型根据对话上下文从预设函数列表里选一个来执行。这种方式解决让模型会用工具的问题但用多了就会难受函数越来越多、描述越来越长、参数越来越复杂到了上百个函数的时候模型选择准确率唰唰往下掉上下文也被塞得满满当当。技能体系本质上是对工具调用的结构化升级。它不再是零散罗列单兵作战的函数而是把函数按业务能力归集成技能块——每个技能自带清晰的能力描述、输入输出约束、执行策略和版本信息。模型只需要先选用哪个技能再由技能内部路由到具体执行逻辑选择压力一下小了很多。我用一个类比来说明Function Calling像是给模型递上一本厚厚的电话簿让它自己翻页找人技能体系则像给模型配了一个前台它只需说我要解决支付问题前台自动把对应的处理人、处理流程接好。1.2 技能、工具、工作流三者之间的边界开始设计之前必须把三个容易混淆的概念划清楚工具Tool最小可执行单元一般对应一个API调用、一段函数逻辑没有内部状态。技能Skill面向场景的能力封装内部可能包含多个工具调用有状态流转、有前置条件、有异常处理。工作流Workflow技能之上的流程编排层描述多个技能以何种顺序、何种条件串联完成一个完整业务场景。拿订单系统举例查快递接口是工具查订单物流是技能内部包含调用查询接口、解析状态码、处理异常单号这些逻辑售后全流程处理是工作流可能串联查订单判断售后类型生成退款单通知用户等多项技能。搞清楚边界有个实际好处团队在讨论设计时能准确判断某段逻辑应该放在哪一层。我见过很多项目把工作流的逻辑塞进技能里结果技能越写越重最后变成四不像。真正合理的设计是技能保持单一业务能力的纯度流程编排交给上层工作流去管。2. 技能拆解的核心粒度决定的不仅是复用性还有成功率技能粒度是我这次实战中花时间最长琢磨的一件事。粒度定得太大技能像一台笨重的机器Agent只想拧个螺丝它却给你启动整条生产线粒度定得太小Agent又要频繁组织多个微技能协作每一步都有选择误差整条链路跑下来成功率呈指数下降。2.1 最小原子技能的设计原则我在项目里定了一条规则一个原子技能必须能在一句话内说清楚它完成了什么可独立验证的结果。说不清楚就说明粒度有问题。比如发送短信可以说清用户触达说不清——它到底是发短信、发邮件还是Push生成周报文件可以说清处理周报说不清——是生成、汇总还是审批定好可独立验证的结果之后还要过两关这个技能是否会被至少两个上层场景复用如果只会被一个场景用到暂且不封装成独立技能先放在场景内部实现等出现第二个调用方再抽出来避免过度设计。这个技能的输入输出是否稳定如果每次调用时入参结构都在变说明技能边界没划好背后可能混入了不属于它的变化因素。2.2 复合技能与DAG编排原子技能之上是复合技能用有向无环图DAG把多个原子技能串起来。我一开始直接用代码硬编码流程后来改成声明式的DAG配置灵活度提升很大。一个比较典型的复合技能结构如下skill: order_after_sale_process version: 1.2.0 description: 售后订单全流程处理从校验订单到生成退款单 nodes: - id: query_order type: atomic_skill skill_ref: order_query - id: check_after_sale_valid type: atomic_skill skill_ref: after_sale_validator - id: create_refund type: atomic_skill skill_ref: refund_create edges: - from: query_order to: check_after_sale_valid condition: order.status COMPLETED - from: check_after_sale_valid to: create_refund condition: valid true声明式配置最大的好处是调整流程顺序、加判断条件、替换某个节点都不用动代码改配置重载即可。而且每个节点只依赖上一个节点的输出字段Debug的时候链路清晰出了问题看日志能直接定位到具体是哪个节点的哪个条件没过。需要提醒的是DAG编排尽量控制节点数量单个复合技能最好不超过8个原子节点。节点一多中间状态管理的复杂度暴涨Agent上下文重述的成本也会跟着涨。3. 让Agent选对技能描述和参数才是真正的接口技能实现得再漂亮如果Agent选不到、不会调一切都是白搭。项目跑了一段时间后我深刻体会到技能对Agent暴露的接口不是代码签名而是自然语言描述 参数Schema。组件内部怎么实现模型根本不关心它只看得到这个技能描述说什么、参数要我填什么。3.1 技能描述怎么写才不容易被Agent忽略写技能描述最大的坑是写得太抽象。我看过团队里有人这样写本技能提供订单查询能力可根据输入参数查询系统内订单信息。这句话属于典型的无效描述。Agent面对多个技能时需要靠描述判断该不该用这个而订单查询能力这种话没有任何区分度。实践中我建议描述采用触发场景 能力边界 返回值概览三段式触发场景用户提到哪些关键词、处于什么上下文时应该调用本技能。能力边界本技能能做什么、不能做什么不能做的也要写避免Agent误调用。返回值概览返回结果包含哪些关键信息方便Agent判断下一步动作。举一个改好的例子当用户询问我的订单到哪了物流多久能到帮我看看快递状态时使用本技能。 技能会返回订单当前状态、承运商、最近一条物流轨迹及预计送达时间。 本技能仅支持查询近90天内的订单不包含价格变更与退货进度信息。这种描述看起来啰嗦但实测中Agent的选择准确率能提高两到三成。本质原因是模型在做意图匹配时非常依赖描述与用户表达之间字面及语义上的重叠度。你写得越接近真实用户的表述模型越容易命中。3.2 参数Schema的约束与默认值设计参数Schema是另一个容易被低估的环节。大多数刚上手的人会把技能参数定义得和底层API入参一样这是错误示范。Agent填充参数时的思考成本很高每多一个必填字段就多一次出错的可能。我总结的参数设计原则能合并的字段就合并。比如省市区三个字段合并成一个region字段让Agent一次性填杭州市西湖区底层再自行解析。能给默认值就给默认值。比如分页大小默认20排序默认按时间倒序。这样Agent不填也能拿到合理结果。枚举值必须写明可选项和含义。比如售后类型填refund还是return要明确说明refund仅退款return退货退款不然模型很容易混淆。对依赖字段用description解释关联关系。有些字段之间是有条件依赖的属性里写清楚仅当typerefund时必填。参数Schema还有一个隐性作用它在帮Agent降低自由度。自由度高意味着模型输出的参数五花八门解析层要花大量精力做兼容而好的Schema能够在入口处就约束住大部分无效输入让下游逻辑写得非常干净。4. 技能编排的几种模式串行、分支、并行与容错技能编排层是Agent能否稳定完成复杂任务的关键。我最初以为编排就是写流程图实际做下来发现比流程图更重要的是一套异常情况下的决策逻辑。4.1 串行编排与状态传递串行编排是最基础的模式技能A执行完把输出交给技能B再交给技能C。这里最考验设计的是状态传递。我在项目里维护了一个统一的执行上下文Context每个技能从Context里取需要的字段执行后把结果字段写回Context。这么做可以避免技能之间直接函数调用产生强耦合。context ExecutionContext() # 技能A执行并写回字段 order_info await skill_a.execute(context.input(order_id)) context.set(order_info, order_info) # 技能B读取字段 refund_eligibility await skill_b.execute(context.get(order_info))一次实战中串行链路中间突然出现脏数据——技能A返回的订单状态字段带了个空格技能B做精确匹配时直接失败。后来我在状态传递层统一加了一个轻量数据清洗逻辑所有从外部API拿到的字段进入Context前都要过一遍trim、类型转换和默认值填充。这个处理救了很多次后续任务的命。4.2 条件分支与并行执行条件分支相对直接用上一节提到的DAG配置就可以实现。但有一个点容易被忽略分支条件的判断字段要从Context中显式声明而不是让Agent自己判断。比如根据订单金额决定走A还是B流程金额大于阈值走A、否则走B。这段逻辑必须由编排引擎硬编码判断不能把两个流程都摆在Agent面前让它选——模型做数值比较的稳定性和确定性远不如代码逻辑。并行执行则要注意场景适用性。只有技能之间完全无依赖时才建议并行比如同时查天气、同时查航班、同时查酒店三者互不依赖。但大部分业务场景中的技能是隐性依赖的比如查完订单才能查该订单的发票这种绝不能并行否则会出现竞态条件产出错误结果。4.3 超时、重试与降级策略技能编排跑到线上的复杂度远超本地Demo的演示体验。我碰到最头疼的问题就是外部服务超时——技能调用的下游接口偶尔卡顿一旦出现整个编排链路挂着不动Agent迟迟不返回答复。后来给每个技能节点统一挂了三个策略超时策略单个技能最长执行30秒超时则抛异常给编排引擎。重试策略对于允许重复执行的幂等技能最多重试2次采用指数退避。降级策略如果核心技能失败判断是否有可替代的低保技能。比如精确查询失败降级为模糊查询实时数据失败降级为缓存数据并提示信息可能不是最新。降级策略的价值不仅是保流程不中断更重要的是让Agent能把不完美但可用的结果正常反馈给用户而不是干等或直接报错。这一点对用户体验影响巨大属于性价比极高的投入。5. 从单体技能到技能库命名空间、版本与权限当技能数量超过20个就会进入库管理阶段。零散的技能是资产但这么多技能堆在一起如果不做管理沉淀下来的不是复用资产而是技术债。5.1 技能仓库的组织结构我的技能库按业务域 → 技能组 → 技能三层组织。以电商系统为例skills/ order/ query/ # 订单查询技能组 detail.yaml list.yaml logistics.yaml after_sale/ # 售后技能组 apply.yaml query.yaml payment/ refund/ create.yaml status.yaml user/ profile/ get.yaml这种组织方式的直接收益是Agent感知技能时能按照命名空间做分组筛选同一个场景的多个技能聚在一起命中率比平铺的列表明显更高。另外团队的权限控制也更好做——业务A的团队只维护它自己目录下的技能不会误改动别的模块。5.2 版本兼容与灰度发布技能库上线后迭代是常态版本管理必须配套。我采用的策略是每个技能必带语义化版本号主版本不兼容变更、次版本向下兼容、补丁版本修Bug。技能引用处记录它声明依赖的具体版本区间比如依赖order_query 1.2.0, 2.0.0避免主版本升级时上游流程悄悄崩掉。新版本技能先在灰度环境验证只有验证通过才批量生效。灰度环境验证时有个容易被忽视的细节不仅要让新技能跑通还要用一批历史典型的困难输入做回归——把之前导致Agent选错技能、参数填错的对话样本抽出来重新跑一遍。如果新版本连这些困难样本的准确率都保持住了才敢放心切换。这套做法帮我拦下了至少两次看起来没问题、实际会退化的发布。5.3 技能的可观测性技能多了之后还需要可观测性。我在每个技能的执行入口和出口埋点记录技能名、版本号、入参摘要、出参摘要、耗时、成功与否、上游上下文ID。有了这些数据你能很轻松回答这些问题哪个技能被调得最多哪个技能经常报错哪个技能的入参经常缺失关键字段这些问题单靠感觉是永远说不清的但有了埋点优化方向就清晰了。6. 实测中踩过的坑每一处都在教做人技能体系搭完连跑三周线上流量之后留下了几处刻骨铭心的实战记忆。6.1 描述里没写负向边界Agent频繁抢活上线第一周售后技能被疯狂误调用。用户只是问了一句退款多久能到账模型直接调用了生成退款单技能差点没闹出事故。查下来根因就是技能描述里只写了正向触发场景没写能力边界。修复方式是在描述里明确加上一段本技能仅用于执行退款创建操作不用于查询退款进度查询请使用refund_status技能。加上负向边界之后误调用率直接降了一个数量级。6.2 参数Schema给太宽脏数据往下游渗透另一个教训来自参数校验。早期我在Schema里把用户备注这种字段设为可自由输入结果Agent在备注里塞了一堆非结构化内容下游做自动审核时正则匹配全部失效。后来我设了参数最大长度、字符类型限制并且在技能内部对自由文本类字段一律先做关键词清洗再往下游传。生产环境的经验就是免费的自由度最后都得用稳定性的代价来还。6.3 并行执行导致的共享状态覆盖我在并行执行上踩过一次比较典型的坑两个并行技能都往Context的同一字段result里写结果后写完成的把先写完成的覆盖了导致下一步取数取到错误来源的数据。现在代码里强制规定每个技能的写回字段必须是带命名空间前缀的独立键比如logistics_resultrefund_result严禁多个技能共同写入同一个裸字段。这个约定简单粗暴却根治了并行状态覆盖的问题。6.4 技能版本升级后的线上静默失效最后一次教训是版本升级引发的。当时给订单查询技能升了个主版本从v1升级到v2查询逻辑做了重构。但有几个老的工作流配置里还硬编码着v1版本的技能IDv1下线后这些流程没有报错——它们在运行时走的是另一个兜底查询接口返回的数据格式不一样导致下游解析出空值。那之后我加了一条硬性规定技能版本下线前必须先扫一遍所有线上依赖确认没有任何配置引用旧版本并且在技能注册表里添加下线保护——只要还有活跃依赖就禁止下线。凡是流程改造先查依赖图再动手这已经是团队约定俗成的规矩了。7. 技能体系后续的几个演进方向基础能力和稳定性有了但我觉得这套体系仍有很多值得折腾的余地。如果你也准备在项目里搞技能体系可以提前考虑这几个方向的坑和空间。7.1 动态技能发现与自动装载目前我采用的是静态注册加载模式——所有技能在服务启动时一次性装载进技能列表。这在技能量少的时候没问题一旦技能库膨胀到几百个启动时长、上下文占用都会失控。我下一步计划做动态技能发现根据用户当前会话的意图只把可能相关的一组技能装载到Agent的候选列表里。比如用户在聊售后只装载售后域的技能在聊物流只装载物流域的技能。这么做既能保持模型的选择准确率又能控制上下文预算。实现上可以给每个技能增加一个激活条件字段用轻量分类器做初筛后再精确匹配。初筛不追求百分百准只要保证候选集中包含正确技能即可真正的选择由模型完成。7.2 技能链路的自动编排尝试人工编排复合技能虽然稳定但维护成本高。市面上已有一些尝试让Agent根据目标自动生成编排链路的框架实测效果参差不齐。我的态度是在低风险场景如信息查询类可以试水在涉及资金、售后等高风险场景必须保留人工编排兜底。核心原因是自动编排的可解释性和可控性还不够成熟一旦链路出错顺着一条Agent自己生成的路径排查问题成本极高。安全第一效率第二这个排序不应该变。7.3 技能效果的数据闭环最后说一个容易被忽略的环节——技能效果评估。很多团队把技能做完上线就完了不追踪这个技能在真实对话中到底被调用对不对、效果好不好。我建议每个技能都沉淀一套评估样本把真实用户的对话记录脱敏后标注出应该调用哪个技能、应该填什么参数形成评估集。每次技能迭代都跑一遍评估集用准确率、参数合理率两个指标把关。有了这个闭环技能体系的优化就不是凭感觉而是看数据说话。落到具体做法上先把线上Agent调用技能的日志完整记录下来包括触发对话、模型选择过程、最终执行结果然后定期抽样人工校对模型选的技能是否正确、参数填写是否合理把校对后的数据回填到评估集里形成持续滚动的基准测试集。这个机制看起来朴素但对技能质量的长期保障价值极大。这是我这次做完agent-skills项目后最想分享的一套思考。技能体系的本质是给Agent提供一副清晰、稳定、可信赖的手和脚。把技能定义清楚Agent才能真正跑得稳。希望这篇里的经验对同样在这条路上摸索的你有用尤其是那些前期看不出来、后期越想越重要的设计决策。