agent-skills 项目实战把智能体从“单次问答”升级为“可持续沉淀的技能库”最早有这个项目念头是因为我们在某智能助手项目里连续碰到同一个窘境业务方提需求永远是一句话——“让Agent学会报销”“让Agent学会查库存”“让Agent学会发周报”。一开始我也是老老实实加工具、加提示词结果每加一个能力就要动一遍主流程模型稍微换个版本之前调好的行为就漂了。后来我们干脆做了一个名为“agent-skills”的内部技能库体系把智能体的各项能力全部拆成可注册、可编排、可评估的独立技能单元。这套思路跑通之后新增一个业务功能基本不用再碰核心代码只靠注册新技能和配置编排规则就能完成。这篇文章我来完整复盘一下这套设计。适合谁看如果你正在做Agent类应用或者你维护的对话系统已经出现“提示词越堆越长、行为越来越不可控”的情况那这篇文章应该能帮你少走不少弯路。我会从技能和工具的本质区别讲起一直聊到技能库的数据结构、执行引擎、编排方式和评估迭代最后把我们在落地时踩过的坑和最终采用的方案一并交代清楚。1. 从“加工具”到“建模技能”Agent能力组织的第一次观念转换1.1 工具和技能到底差在哪儿先说一个最容易混淆的问题市面上很多框架里都在讲“Function Calling”“Tool Use”为什么我还要单独搞一套“技能”体系两者的差别不在于名字而在于能力的封装深度。工具Tool通常只是一个可被调用的函数描述它的本质是“能执行某个操作”。比如“查询天气”“发送邮件”你给模型一个函数签名和参数说明模型决定要不要调用、传什么参数。它解决的是“模型怎么触发外部动作”的问题。技能Skill则是在工具之上加了两层东西第一层是触发条件与使用策略也就是在什么场景下该用这个能力、什么场景下不该用这个判断不只是靠模型临场发挥而是靠技能自身的描述和约束来引导第二层是执行上下文与结果处理也就是调用完这个能力之后结果如何被消化、如何影响后续的对话或任务流程。我打一个生活化的比方工具是一把螺丝刀技能是“会拧螺丝”这件事。螺丝刀只是物件而“拧螺丝”包含了选择螺丝刀型号、判断旋转方向、掌握拧紧力矩、知道什么时候停手。Agent如果只挂一堆工具就像你给一个人一堆工具但没教他工序他也许能逐个操作但组合不成一件完整的事。1.2 技能边界的定义先回答四个问题我们在设计技能注册规范的时候要求每个技能在上线之前必须回答四个问题回答不清楚就不允许进技能库这个技能解决什么类型的任务是信息查询、状态判断、动作执行还是多轮对话中的信息收集这个技能的成功标准是什么比如查库存技能的成功标准不是“返回了库存数字”而是“返回的数字能直接用于后续的补货决策”。这个技能在什么条件下不应该被使用这一点很多人会漏掉。比如“发送邮件”技能如果用户只是在问“能不能帮我看看之前发的邮件”就不该走发送流程而应该走查询流程。给技能加上“禁用场景”能大幅减少模型的误调用。这个技能产出的结果如何被下一个环节消费如果技能输出的是结构化JSON但下一个环节期望的是自然语言摘要中间就要设计适配层不能让它裸奔对接。这四个问题听起来简单实际做起来特别考验对业务的理解。我们第一版技能库里有个“新建工单”技能当时只回答了前两个问题结果模型经常在用户还没说完故障描述的时候就把工单建了导致大量只有标题没有内容的垃圾工单。后来补上第三个问题在技能描述里加了一条硬约束“当用户仍在描述问题详情或尚未表示需要创建时禁止调用”误触发率立刻下降了一半以上。2. 技能库的数据结构与注册机制让能力能被检索、被调度、被升级2.1 技能元数据一份技能该长什么样技能库的核心是元数据。我们最终沉淀下来的技能注册结构大概是下面这个模板虽然不是标准规范但对我们来说已经足够稳定字段类型说明示例skill_idstring技能唯一标识stock_query_v1namestring技能名称库存查询descriptionstring技能职责、适用场景、禁用场景用于查询实时库存仅在用户明确询问库存数量或可用量时调用input_schemaobject参数定义含类型、是否必填、取值范围{sku_id: {type: string, required: true}}output_schemaobject返回结果结构定义{available: integer, warehouse: string}prompt_templatestring/text技能内置的执行提示模板你是一个库存查询助手请根据参数查询…execution_typeenum执行方式模型直答、调用函数、组合子技能function_callfallback_strategyenum失败回退策略重试、转人工、返回兜底话术retry_and_degradeversionstring技能版本号v1.2.0ownerstring技能负责人供应链组metricsobject质量指标如成功率、误调用率{success_rate: 0.97}这个表不只是为了规范更重要的作用是让技能检索变得靠谱。我们前期调研过很多开源项目发现很多Agent项目做不好不是因为模型不够强而是技能描述和技能本身对不上号。比如某个技能内部逻辑明明只支持中文物料编码描述里却写“支持物料查询”模型被误导去处理英文编码到了执行层才报错。2.2 注册中心与版本管理技能也要走发布流程技能不是写好了就能用的。我们给技能库加了一个轻量级注册中心类似微服务里的服务注册表但又比它多了“语义注册”的部分。每个技能提交流程分四步开发与自测技能开发者按照元数据模板写好技能内容和测试用例在本地模拟环境跑通。评审至少一名非开发者来做评审重点看技能描述是否会产生歧义、input_schema是否覆盖常见边界情况。灰度技能注册后不立刻全量生效先按5%的流量验证观察误调用率和成功率。全量发布与持续监控发布后每天自动跑回归测试指标低于阈值的技能会自动标记为“低健康度”并触发告警。版本管理方面我们没有做得特别重因为Agent技能的迭代频率其实比普通服务高很多。模型升级、业务规则调整、数据口径变化都会逼着技能改版。我们规定技能版本号遵循语义化命名主版本号变化表示行为不兼容次版本号变化表示对原行为进行了增强或修正。技能注册中心会保留最近N个版本所有线上会话记录都带上技能版本号方便出问题的时候回放定位。2.3 技能分层原子技能、组合技能、业务技能的清晰分工技能库里如果所有技能都放在一个平面很快就会乱成一锅粥。我们在实践中把技能分成三层这也是我认为agent-skills体系里最关键的结构设计之一原子技能L0不可再分的基础能力通常对应一个API调用或一个确定性操作比如“查询库存”“发送HTTP请求”“计算运费”无内部状态输入输出规则简单。L0技能追求的是稳定和可复用。组合技能L1由多个原子技能按规则拼接例如“检查订单能否发货”需要先“查询库存”再“检查风控规则”最后“查询物流范围”。组合技能内部可以定义条件分支但对上层暴露的还是统一接口。业务技能L2直接面向业务场景的完整能力内部可能混合了模型推理、多轮对话、多个L1组合技能的调用。比如“客服处理退货申请”就是一个典型的业务技能它要理解用户诉求、判断是否符合退货政策、调用物流与退款接口最后生成回复话术。这个分层的价值在于上层技能的改动不需要动到底层原子技能底层能力的优化又能被上层自动继承。比如我们改进了某个L2客服技能里的沟通话术完全不影响L1、L0层反过来如果底层某个库存查询接口从REST升级成GraphQL只需要重写L0技能内部实现所有依赖它的上层技能全部自动兼容。3. 执行引擎从意图到技能再到结果反馈的完整闭环3.1 规划器它不是在“猜”意图而是在“选”技能技能库建好之后下一个核心问题是给了模型一堆技能它凭什么在特定时刻选中正确的那一个我们在agent-skills项目里实现了一个轻量级规划器本质上是一套“技能选择路由”。它的工作分为三步意图粗筛用模型的语义理解能力把用户当前这句话映射到候选技能集合。这一步不追求精准但要求召回率高宁可多给几个候选也不要把正确技能漏掉。参数预填从对话上下文中抽取技能需要的参数。比如“帮我把红色的L码衬衫留一件库存”这句话规划器要识别出sku维度是“红色L码衬衫”动作是“锁定库存”候选技能是“库存锁定”。条件过滤与打分结合技能描述里的适用场景和禁用场景对候选技能做过滤再按匹配分数排序。这一步我们不仅用模型的排序能力还会叠加一套规则引擎来兜底——比如“用户处于黑名单状态时任何涉及下单的技能直接降权”。这里有一个非常关键的设计细节规划器输出的不是一个技能ID而是一个带置信度的技能候选列表真实执行时允许模型在Top-3里二次选择。这样做是为了兼顾速度和准确规划器保证了大方向不出错模型在候选集内做最终决策时则保留灵活性。3.2 上下文管理和参数注入为什么技能执行经常“差口气”技能执行失败很大一部分原因不是技能本身写得差而是上下文喂得不对。我们第一版设计里执行引擎会把整段对话历史都塞给技能内部的提示模板。结果发现两个问题一是上下文过长导致关键信息被稀释模型注意力被闲聊内容带跑二是参数隐式传递技能内部并不清楚哪些信息是用户明确说的、哪些是系统推断的导致参数判断混乱。后来改成“显式参数上下文”机制执行引擎在调用技能前会先按input_schema形成一份“参数填充单”把从对话中抽出的参数值、参数的置信度、参数的来源用户原话还是系统推断全部列出来。技能里用到的提示模板只能基于这份参数填充单和少量任务说明来生成不再把整段对话历史直接拼进去。如果某些参数缺失执行引擎不会硬着头皮调用技能而是触发“参数澄清”分支先向用户追问缺失项补齐后再进入执行。还是用“库存锁定”举例子用户说“把那个蓝色的锁一下”这句里“蓝色的”指代不明参数填充单里“蓝色衬衫”的置信度只有0.5执行引擎就会先反问“您说的蓝色是指L码的蓝色衬衫吗”把实体消歧完成再继续。这样做会让交互变长一点但实际成交率和用户满意度都变高了因为Agent不再做无意义的动作。3.3 结果验证与重试给技能执行装上“逃生舱”技能执行完成后结果如果没有经过验证就直接反馈给用户早晚要出事。我们在执行引擎里加入了三层结果校验结构校验返回结果是否符合output_schema。比如约定返回字段available必须是integer结果却返回了一个字符串那就要重试一次仍失败则降级。语义校验结果和用户的问题是否在语义上对应。比如用户问“明天天气”结果返回的是“大后天”这里就需要通过校验器对结果做一个快速合理性校验。业务校验某些高风险技能比如支付、删除、发送执行前要过业务规则引擎执行后要做事务回滚确认。校验失败后的重试策略也很重要。我们设置了“至多重试一次且重试前必须调整策略”的硬规则不能盲目重跑同一个技能。例如库存接口超时重试时优先切换备用数据源而不是继续打同一个接口。如果二次执行仍失败就走fallback_strategy里的降级方案比如返回“暂时查询不到实时库存显示的是两小时前的数据”这类话术避免让用户干等。4. 技能编排从单个技能到复杂工作流织出真正的业务能力4.1 为什么不建议让模型直接“编排一切”很多Agent项目喜欢把编排逻辑完全交给模型让它自由决定调用哪些技能、以什么顺序调用。这种做法在小规模演示时很惊艳可一旦技能数量超过二三十个问题就来了模型会在不必要的时候串联多个技能导致响应变慢而且串联产生的中间错误很难追溯。我们的做法是“模型在预设轨道内做决定”把长流程拆成可控的编排模板。编排模板描述清楚“这个业务流程由哪些步骤组成、每一步依赖什么输入、哪些步骤可以并行、哪些步骤出错了怎么跳过”模型只负责在每个步骤里做具体决策比如选择用哪个技能、怎么填参数、要不要跳出当前流程。4.2 三类典型编排模式链式编排上一个技能的输出直接作为下一个技能的输入。典型场景是“查询订单状态→判断物流节点→生成待办提醒”。链式编排最关键的是中间结果的schema要稳定否则A技能输出字段稍微改个名字下游全部崩掉。我们要求所有技能在定义output_schema时必须带上字段注释和值域说明避免“看起来能用一接就挂”。并行编排多个独立技能在同一轮执行。典型场景是“查看店铺今日销售额库存预警待处理售后”三个查询互相不依赖并行发起能明显降低整体延迟。我们实现并行编排时专门做了超时控制单个技能最大等待时间统一约束任意一个技能超时不会拖垮整个流程等不到结果就走缺失策略。条件编排根据中间结果决定后续走向通常配合业务规则引擎使用。典型场景是“订单风控检查”用户申请改地址先判断订单是否已发货若已发货则走“请先联系快递拦截”分支若未发货则走“直接修改收货地址”分支。条件编排里的判断条件写在哪很讲究我们的经验是能用规则引擎判断的条件尽量不进提示词让代码来判断避免模型二选一时出错。4.3 一个完整的编排案例跨系统信息查询与动作执行用一个我们已经上线的场景来完整展示编排逻辑——“客服处理售后改址请求”。用户说“我的订单还没发货能把收货地址改成新公司吗”流程在编排模板里是这么走的第一步意图识别与技能入口匹配进入“订单售后处理”业务技能。第二步并行执行两个技能“查询订单详情”确认订单状态和“查询地址变更规则”确认当前订单是否允许修改。第三步条件判断订单状态为“未发货”且地址变更规则允许则进入步骤四否则转入“说明限制条件并询问用户是否联系快递拦截”分支。第四步调用“修改收货地址”技能入参是订单号和新的地址。第五步执行结果校验确认返回成功后再调用“发送变更通知”技能把修改结果同步给用户。第六步整个编排流程结束后统一输出给用户的自然语言回复。这个案例里特别值得注意的一点是模型并没有直接调用“修改收货地址”技能它是按照编排模板一步步走的。用户意图中并没有说“我要修改”但业务技能内部的逻辑已经默认“改址请求修改动作”。模型在整个过程中只充当了每个步骤里的判断者和参数理解者真正的流程控制权掌握在编排引擎手里。5. 技能评估、回归与迭代技能库不是写完就完了而是要持续养护5.1 技能测试集核心是把“边界情况”变成可回归的用例技能库能不能长期稳定完全取决于测试集够不够扎实。我们给每个技能都配套了一个专属测试集包含三类用例正向用例输入明确、意图清晰的正常案例用于验证技能的基本成功率。比如“帮我查下SKU 12345 的库存”对应库存查询技能。边界用例参数边界、上下文缺失、指代模糊的案例。比如用户只说“还有货吗”没有任何产品上下文这时候技能应该澄清而不是直接查询。负向用例不应该触发该技能的案例。比如用户问“库存怎么用Excel导出”这跟查询技能无关模型不应该调用查询接口。我们维护测试集的方式参考了自动化测试的思路每次技能改版先跑回归测试通过率低于95%的一律不允许合并上线。同步的每次线上出现误调用案例我们都会把它补进负向用例集里让测试集跟着真实世界一起进化。5.2 线上指标别只盯着成功率要看误调用率和服务降级率评估技能质量时我强烈建议多关注三个指标成功率技能调用成功并且结果通过校验的比例这是基础指标。误调用率在不该触发技能的场景下触发技能、或技能返回了与用户需求无关的结果的比例。这个指标直接反映技能描述的质量和规划器的判断能力。服务降级率技能出错后走了降级策略的比例。降级率太高说明技能的稳定性已经不可接受需要开发者介入修复。我们内部每个技能都有一张周维度的健康度看板把三个指标放在一起看。某个技能如果成功率还行但误调用率很高我们首先会怀疑技能描述写得有歧义如果成功率走低而误调用率不高则会优先排查技能调用外部接口的稳定性以及参数填充逻辑。5.3 失败样本的根因分析一次真实的漂移问题复盘这里分享一次实际排查的经验帮助大家理解技能迭代里最常见的坑。某天线上监控发现“报销单创建”技能的误调用率从前一天的3%涨到了11%但成功率没有明显变化。第一反应是排查技能描述是否被改过结果显示描述没变。接着查看了技能注册记录的版本历史才发现问题根源是大语言模型底模版本升级了新版本模型在识别用户意图时倾向于把“提报销需求”的表述理解成“创建报销单”。举个例子用户说“我有几笔打车费想报销”旧模型认为这是“咨询报销流程”新模型认为这是“直接创建报销单”于是大量应该只被引导到“报销规则问答”的场景全被错误触发。这个问题的彻底解决不是靠改技能描述能搞定的我们在“报销单创建”技能里增加了一条硬性禁用约束——只有当用户给出了至少一笔具体金额或报销事由时才允许触发且首次触发前必须与用户二次确认。加上这条约束之后误调用率回到了2%。这个案例也印证了我前面反复强调的一点技能体系里所有环节都需要持续监控单纯指望提示词写得好一劳永逸是不现实的。6. 落地过程中的坑与经验那些文档里不会写的东西6.1 技能描述里的“过滤器”问题技能描述不是越详细越好描述里塞太多信息反而会干扰模型检索。我们踩过一个很典型的坑某个技能描述里写了“该技能支持查询库存、价格、库位、批次、效期”结果模型在任何涉及商品信息的对话里都优先选它可真正能查的只有库存和库位剩下的字段并没有实现。用户问“价格是多少”时技能返回了一个空字段体验极差。后来我们把技能描述拆成两部分一部分是对外宣称的能力边界只写真正能做的事另一部分是内部约束比如哪些参数组合不支持、哪些输入需要先标准化。对外描述用了“范围收缩”从“支持多种商品信息”改成“仅支持库存与库位查询”误调用率才降下来。6.2 模型幻觉导致的参数错位怎么兜底Agent技能执行中最头疼的问题之一是模型在填参数时会产生幻觉把一个不存在的值虚假地传入技能接口。比如用户问“查一下A001和B002的库存”模型可能在没有A001这个物料的情况下仍然生成一个看似合理的请求接口查无此数据后返回空用户还以为是系统坏了。我们的兜底方案是两层过滤第一层参数填充单里的每个参数都要求带上“参数来源标记”如果某个参数不是从用户原话里抽取出来的而是模型推断出来的那么该参数的置信度会被视为较低某些敏感技能允许直接拒绝执行并反问用户第二层技能接口层做了统一的实体校验物料编码等枚举型参数必须先过一遍字典合法性校验不合法就直接返回“无效参数”而不是沉默。6.3 权限边界和安全规范必须留给代码而不是模型最后一个坑是权限问题。在Agent技能体系里模型天然有“过度执行”的倾向因为它的目标是完成用户请求。但业务场景里不是所有请求都该被执行。我们给技能库接了一个统一授权层核心原则是所有涉及“写操作”的技能创建、修改、删除、发送都必须显式经过权限校验校验规则由代码层强制实施而不是让模型自觉遵守。普通用户试图调用仅限管理员操作的技能时会在编排引擎这一层被拦截返回“当前账号无权限执行此操作”。同时任何对外发送类技能在执行前都需要拿到明确的用户确认信号不允许模型在流程里自动“顺便发送”。这类安全设计不是可有可无的一旦Agent进入实际业务技能的执行后果就等同于生产操作。我自己在实际落地中的体会是越早把安全校验加进执行引擎后面越不用在线上提心吊胆。6.4 最后的小技巧给技能库加一个“废弃技能”标记长年累月迭代下来技能库里难免出现一些已经没人调用、但又不舍得立刻删除的技能。它们躺在技能库里最大的危害是干扰规划器的选择。我们最后做了一个“废弃技能”标记机制连续30天零调用的技能自动被标记为deprecated不再参与意图匹配但代码和注册记录还保留方便后续业务可能需要时快速恢复。这个小改动看起来不起眼却让技能检索的准确率提升了不少因为候选池里没有“僵尸技能”了。如果你也在搭自己的Agent技能库我建议从一开始就考虑好技能的整个生命周期不要只想着往里塞新能力也要考虑怎么把人去楼空的老技能安全地雪藏起来。
