做Agent接入真实业务时卡住我的从来不是大模型本身而是那些“会做事的手”——一次查询、一次写库、一次调用第三方接口。大多数入门教程都在讲tool calling怎么把函数列表喂给模型但真到了几十个工具、多轮调用、多角色权限的规模这套做法会先崩。这篇文章聊的是我在模拟项目X里落地的一套agent-skills设计把技能当成与Agent生命周期绑定的第一公民从定义、注册、发现到执行、编排、审计全链路遇到的问题以及我手上的解法。如果你正准备把Agent从Demo推向生产这篇文章应该能帮你少走不少弯路。1. 从函数列表到技能系统为什么单靠tool calling会先崩1.1 tool calling的现状与瓶颈先说说最原始的做法。早期我给Agent接工具时就是把所有函数塞进system prompt让模型在请求里返回一个JSON指定调哪个函数、传什么参数。这种方式在小规模下很爽写个Python装饰器注册进列表完事。但规模一上来就出问题。第一个问题叫上下文爆炸。我给每个工具写描述、枚举、示例一个工具少说两百token。拢共二十个工具光工具定义就占掉四千多个token。如果每个工具的description再写得详细一点几千token就没了。你别小看这个开销Agent任务往往需要多轮对话每次都要把这堆工具定义重新发给模型Lantency和成本同步上涨。第二个问题是决策质量下降。工具多了以后模型经常选错。尤其是两个工具语义接近的时候比如“查询用户积分”和“查询用户优惠券”模型可能选错。不是模型笨而是工具描述本身长得很像没有足够区分度。我在模拟项目X里就遇到过用户问“我还有几张券”模型调了积分查询接口返回一堆积分流水LLM往对话里编了一个“您有XX张券”。很尴尬。第三个问题更隐蔽是逻辑碎片化。权限校验、限流、重试、日志、审计这些横切逻辑散落在各个函数handler里。今天A函数加了鉴权明天B函数忘了加。等安全问题爆发时你根本不知道哪些技能裸奔过。一句话总结工具是“函数级”的东西而Agent在真实业务里需要的是一整套“能力治理框架”。1.2 skills这个抽象到底补了什么技能系统和裸工具列表的最大区别在于它把“能力”做成了独立治理的对象。一个技能不再只是函数签名和描述它包含自然语言说明、结构化参数契约、执行实现、运行策略超时、重试、隔离级别、权限要求、审计配置、版本信息。技能是可注册、可发现、可审计、可编排、可灰度下线的一等公民。具体来说技能系统做了三件事一是把工具描述从“全量注入”变成“按需检索”。Agent在运行时先基于用户意图检索技能库选出最相关的3到5个技能再注入上下文。剩下几十个技能躺在仓库里不占token。二是把横切逻辑收拢到平台层。权限检查、限流、预算控制、日志上报全部由技能执行框架统一处理。技能作者只写纯业务逻辑不需要关心鉴权怎么做——这在一堆技能由多个小组共建时尤其重要。三是让组合复用成为可能。单技能是原子操作但很多用户需求是复合的查订单状态如果状态是“待付款”就提醒付款如果是“已发货”就再拉物流轨迹。把这种“判断动作”的组合封装成可复用技能整个Agent的表达能力会上一个台阶。1.3 什么场景才需要技能系统这里说句大实话不是所有项目都需要上技能系统。如果你的Agent总共只有三五个工具、单机部署、用户就你自己调试裸tool calling完全够用。硬上一个复杂的技能框架反而让简单事情变复杂。我判断要不要上技能系统就看三个条件是否命中技能数量已经超过15个或者预计半年内会超过有多个人、多个团队要往同一个Agent里贡献能力有权限、审计、合规要求不能“谁都能调一切”三个条件里中了两个就该把技能系统纳入设计。我当时在模拟项目X里就是三个全中技能一度膨胀到47个参与者横跨两个小组还要对接内部数据权限体系。裸工具列表真扛不住。2. 一份技能该怎么定义元数据、参数契约与语义描述2.1 技能元数据到底有哪些字段说到技能定义很多人的第一个反应是“写个函数再加个description”。但技能系统里一个技能是结构化的元数据对象。我在项目里用的技能定义大概是这个结构skill: name: query_user_points display_name: 查询用户积分 description: 查询指定用户的当前积分余额和近30天积分变动。 version: 1.2.0 visibility: internal owner_team: user-service tags: [user, points] parameters: type: object properties: user_id: type: string description: 用户唯一标识 required: [user_id] returns: type: object properties: total_points: { type: integer } recent_changes: { type: array } policies: timeout_seconds: 5 max_retries: 1 isolation: process rate_limit: 100 permissions: require: [user_service.read]字段看起来多但每个都有用途。name和display_name前者是机器唯一标识后者给模型和用户看description给LLM看的核心语义version技能也是软件也会有变更和回滚visibility控制谁能发现这个技能内部/外部/灰度可见owner_team出问题了找谁returns这个字段很多人忽略但它对结果归一化特别关键后面详细说我坚持的一点技能定义必须走代码仓库经过评审合并而不是在数据库界面里手工改。技能是运行时Asset得有版本历史。2.2 参数契约JSON Schema的“宽进严出”设计参数契约是技能系统里最容易做过头、也最容易做塌的部分。做过头是指用JSON Schema的additionalProperties: false把参数卡得死死的还套一堆oneOf、嵌套anyOf。大模型按你的schema填参数十次有几次填出非法结构。尤其嵌套场景模型即使只犯了字段名大小的错解析器直接报错技能调用失败。我的做法是“宽进严出”入参schema尽量宽松执行层内部再做强校验和默认值兜底。具体来说除必需字段外都允许缺省对外暴露简单扁平结构尽量不搞多级嵌套选择性地关闭additionalProperties: false但代价是在执行处理器里主动忽略未知字段数字字段不要用enum严格枚举除非这个字段确实只接受固定值否则给模型留解释空间举个例子。一个“发站内信”技能input如果要求{ user_id: string, template: string, variables: object }这就够了。不要强迫模型把variables展开成一个极其严格的模板结构。模板参数缺了某个变量执行层捕获后补默认值并把告警写入日志。这样技能成功率会明显提升。2.3 description的写法直接决定模型选不选得对这一节我要多写几句。在技能系统里你给LLM看的description质量几乎决定了它的选择质量。我在实践中总结了几条基本规则。第一用动词开头第一句就点明能干什么。比如“查询指定用户的积分余额和近期变动记录”比“这是一个用户积分服务”好得多。模型是拿description去匹配用户意图的动词开头的句式匹配效率高。第二明确写“这个技能不干什么”。听起来很怪但我用过很成功。比如查询用户积分余额。注意只支持查询不支持修改不做兑换、不做扣减如需查询优惠券请使用query_user_coupons。为啥要写反面因为两个技能描述如果都很正面模型无法区分边界。你直接把边界写清楚模型选错的概率大幅下降。我做了一批技能description的对比测试加入“不要做什么”之后技能选择准确率从82%提到93%。第三给一个使用样例。模型对例子的理解通常比抽象描述好。样例可以是“例如user_idu12345时返回该用户的积分总额”。这个样例不需要很长一两行就够。第四控制长度。description不是越长越好。太长会稀释重点。我控制在一个中等的区间技能的全部提示描述包括参数说明加起来不超过几百token。超出部分要么拆成另一个技能要么挪到执行文档里。3. 技能注册与发现让Agent在运行时“找得到、选得对”3.1 注册中心与schema校验技能定义写好了下一步是进注册中心。注册中心本质上就是一个带索引的技能仓库我把它分成三层存储层、校验层、索引层。存储层我用的是普通关系库技能元数据存JSONB字段方便整体读写。校验层在写入前做几件事name是否重复、name是否符合命名规范、description是否为空或过短、parameters是否合法JSON Schema、required字段是否都在properties里声明过。这些校验看起来基础但能拦下不少低级错误。我印象里有一次技能上线直接把整个发现服务的内存打爆原因是某技能描述里塞了一个超长的base64样例。后来加了长度校验问题就没再出现。索引层负责把技能转成可检索的形式为description、display_name、tags做一些分片文本索引同时调用embedding接口为向量索引计算向量。3.2 检索式技能发现embedding不能解决所有问题技能数量一多全量注不行所以触发方式变成“检索”。我一开始以为embedding检索就够实测发现单独只有它并不可靠。问题出在embedding的语义边界。用户问“我还有几张优惠券”技能库里有“查询优惠券”和“查询积分”两者的向量距离有时还挺接近。只靠top-k召回可能把两个都捞上来把上下文让给了不相关技能。我的最终方案是“混合检索”文本关键词召回加向量召回然后合并排序。关键词负责精确匹配比如技能name、tag里的user、coupon等词向量负责语义泛化。排序时引入一个小的意图分类器做粗排先在候选技能里筛出与当前对话意图明显相关的再用规则精排比如用户明确提到“积分”时“查询积分”的权重直接拉高。这听起来复杂但落地上很简单候选集基本只有几十个技能在这上面做规则排序毫秒级完成不会有性能压力。还有一层容易被忽略检索必须带上权限和可见性过滤。一个普通用户查询技能时发现服务在检索前就把visibility: internal的技能过滤掉模型根本不会“看到”它。这比执行时再拦截更干净因为模型压根不会提出非法调用。3.3 命中结果怎么塞进上下文检索召回之后不能直接把全部字段倒进system prompt。上下文是稀缺资源我控制最终注入技能数在3到5个之间。注入前做一次裁剪每个技能只保留name、缩短后的description、参数JSON Schema、以及一两个关键示例。owner_team、policies这些治理字段不进入模型上下文。description我有一套截断逻辑先取第一句话动词开头那句再视剩余预算决定要不要补充“不做什么”部分。有一点我特别想提醒注入顺序也有讲究。模型倾向于调用列表里排在前面的技能。所以我把排序分数最高的技能排在最前面并且用分隔符把每个技能块隔开。实测这样比把所有技能凑成一坨让模型自己挑的效果好得多。4. 技能的执行链路参数校验、权限检查与结果归一化4.1 执行前的三道闸技能被模型选定了接下来进入执行链路。这一段是生产环境里最容易出事故的地方。我在模拟项目X里总结出执行前必过的三道闸。第一道schema参数校验。虽然前面说“宽进”但基础结构还是要验必填字段是否都有、类型对不对。这层校验执行在框架层不依赖模型判断。校验失败时框架会组装一个结构化错误返回给模型让它重新提参而不是直接失败。第二道权限与审批。技能执行前框架拿当前会话的身份上下文与技能声明的permissions做匹配。权限不足时看技能配的是“拒绝”还是“申请审批”。高危技能比如删除、发钱、改密默认走审批审批消息直接推到人工工作台。第三道限流与预算。每个技能有自己的限额同时整个Agent会话也有总预算。如果技能属于内部高频而且没有限流一次并发尖峰可能把下游服务打挂。我给所有技能都加了一个统一的熔断器QPS超过阈值直接返回“当前技能繁忙请稍后再试”。4.2 沙箱与隔离技能执行不是简单调用函数它需要隔离策略。我按危险级别分三档低危纯查询、纯计算在线程池里跑就够了加超时中危涉及文件读写、网络请求但范围受限放进独立子进程高危执行不可信内容、需要完全隔离直接跑在容器里线程、子进程、容器三种模式的代价差别很大。线程快但隔离差子进程每次启动有开销容器最安全但最重。我大多数查询技能走线程池只有涉及数据变更的才升级为子进程。超时和重试是另一个坑。不要对所有技能用统一超时。查数据库接口5秒可能就够但调用第三方外部接口可能30秒都不够。我在技能元数据里加了timeout_seconds字段每个技能单独配。重试也要考虑幂等性。查询类技能重试没问题但“创建订单”这类技能重试可能产生两笔订单。我的规则是只有声明了idempotent: true的技能才允许框架自动重试否则直接把失败抛给模型让模型决定要不要换个方式处理。4.3 结果回传把非结构化输出折算成模型能用的信号技能执行完结果怎么回给模型决定了Agent最后一轮回答的质量。我看到很多项目直接把函数返回值原样塞回去比如一个JSON对象嵌套五六层。模型拿到后要么理解不了要么把字段名报给用户毫无体验。我的做法是结果归一化。在技能元数据里定义returns结构执行框架把原始返回包成统一的响应信封{ status: success, data: { total_points: 1200, recent_changes: [] }, error: null, note: 查询成功 }如果出错则{ status: error, data: null, error: { code: BOOM_003, message: 用户不存在或已注销 }, note: 无法查询该用户积分请向用户解释用户可能已注销 }重点在note字段它是给LLM的自然语言提示告诉模型遇到了什么问题、该怎么收场。这就是“把程序语言翻译成模型语言”的过程。结果数据过大也要截断。一次查询可能返回几千条流水全塞给模型既不经济也没必要。我统一在返回层做聚合和截断只保留前20条明细并在note里说明“还有XX条未显示”。5. 多技能编排从单一技能到可复用工作流5.1 主动式编排Agent自主选择技能序列技能系统的能力不只是单个调用还包括多技能组合。最自然的组合方式是“主动式编排”模型自己决定先调哪个、再调哪个、根据结果判断下一步。这种方式的优点是灵活处理意外情况的能力强。用户在Agent里来一句“帮我查一下订单到了的话提醒我取件”模型会自己拆解查询订单状态如果已到站则调用“生成取件提醒”技能。缺点也明显模型自主编排容易碰壁。一是时序错乱比如先查物流再查订单两步反过来问题不大但“先查询后更新”如果顺序反了数据一致性就出问题。二是对话上下文过长后模型可能会遗忘早期步骤的结果导致编造数据。我对主动式编排的底线是允许模型自主选择技能但禁止它调用带副作用的技能写库、发送、删除作为编排中的“尝试性步骤”。带副作用的技能只有经过明确的用户确认才会放行。5.2 被动式编排预定义DAG/顺序链真正的多技能组合任务我更推荐用被动式编排预先定义一张DAG每个节点是一个技能边代表依赖关系。模型只选择执行哪个工作流模板而不是完全自由发挥。比如“售后工单处理”工作流workflow: after_sales_handler nodes: - name: verify_user skill: query_user_info - name: get_order skill: query_order_status depends_on: [verify_user] - name: decide_refund skill: evaluate_refund_policy depends_on: [get_order] - name: apply_refund skill: create_refund_order depends_on: [decide_refund] condition: ${decide_refund.eligible true}我在这里会把工作流本身也注册为一个“组合技能”。用户问“我要退货”发现服务召回的可能是after_sales_handler这个组合技能而不是五个原子技能。模型只需要记住工作流的入口和结果具体内部逻辑由执行引擎按DAG处理。这种方式的收益是稳定工作流中间任何一个环节失败流程可以精确反馈到模型A技能成功但B技能失败时错误信息清晰可见不会让模型在黑暗中瞎猜。5.3 技能之间共享数据做了编排之后“技能之间的数据怎么共享”立刻变成绕不开的问题。简单方案是一个会话级的内存数据区工作流执行器把上一个技能的data字段塞进共享上下文下一个技能按key取用。但这里有一个矛盾技能不该隐式依赖全局共享否则技能A改了全局变量技能B的路由全乱套。我采用的折中方案工作流节点之间只通过显式声明传递数据。在上面YAML里每个节点可以加inputs映射比如get_order的user_id来自verify_user输出的user_data.user_id。执行器在节点间做一次显式的参数传递技能本身不知道全局上下文存在。这样做的好处是每个技能仍然是一个黑盒只管自己的输入输出便于单独测试、单独复用。坏处是编排定义会啰嗦一点但这点配置成本换来的是可排查性和稳定性值。数据血缘也顺带解决了任何一个工作流的会话都能查得出某条最终结果是由哪些技能、哪些原始数据推导出来的。出了问题链路一眼可见而不是在日志里捞针。6. 实测踩坑记录权限、并发与技能漂移6.1 权限粒度技能级、操作级、行级权限这块是我在生产环境里踩得最深的一个坑。最初我给技能只定义了“谁能调”这一层但真实业务很快告诉我这远远不够。举个例子。“查询用户信息”这个技能客服角色和用户自己都能调。但客服查用户A的信息和用户A查自己的信息能看到的字段完全不同。客服可以看到手机号、历史订单用户自己只能看到昵称、头像。如果权限只做到技能级那用户一旦被允许调用这个技能可能间接摸到他人的隐私数据。于是我把权限拆成三层技能级该角色能不能调这个技能操作级同一技能在特定参数模式下角色能做什么。比如查询技能客服模式允许查全量用户模式只允许带自己的user_id行级返回数据里哪些字段对当前角色可见。敏感字段在结果归一化前直接被抹掉行级过滤是我强烈建议从第一天就做的。不要指望模型帮你做脱敏模型没有可靠性可言。框架层在技能返回后、回传模型前做一次字段级过滤才是最稳妥的防线。6.2 并发与状态冲突技能不能偷偷持有可变状态这个坑源自一次线上事故。某个技能在内部维护了一个字典缓存用来存上次查询结果。单线程调试一切正常但并发上来后两个会话的查询结果互相污染A用户问积分返回的却是B用户的数字。排查过程比较曲折最后定位到问题不是出在LLM的提示词而是技能实现里偷偷保留了模块级可变状态。这给我立了一条硬约束技能必须是无状态的。状态要么来自入参要么来自工作流上下文技能自身不允许持有多轮会话缓存。如果确实需要缓存也要把缓存键绑定到会话ID和用户ID并且在上层框架统一管理而不是散落在技能内部。这条约束写进团队的技能开发规范之后并发类问题基本绝迹。6.3 技能漂移与回归测试技能系统上线后最阴险的坑是“技能漂移”技能对应的下游接口升级了字段变了但技能元数据里的description和returns还是老样子。模型按旧的描述调用传了旧的参数名执行层解析失败Agent表现断崖式下跌。解决漂移靠人工排查是不现实的。我给模拟项目X配了一套自动回归测试每个技能配一组预置测试用例输入、期望输出、期望状态码每天晚上自动跑一遍全量技能回归哪几个技能导致失败立刻生成告警并定位是description问题还是参数契约问题这轮回归还顺手解决了一个问题技能description过时。我有一次发现某技能选准确率骤降跑回归测试后发现下游接口把“账单编号”改成了“账单ID”但description里没更新导致模型按老字段生成参数。回归测试一跑这类问题当夜就能发现而不是等用户投诉。另外技能发版也要走灰度流程。凡是涉及参数契约改动的技能我先让它在灰度可见范围内运行几天确认命中率和错误率没有劣化再全量放开。技能系统本身就是可灰度、可回滚的这比裸工具列表强得多。6.4 最后想留给大家的一句话文章写到这差不多把我在技能系统上踩过的重要坑都讲完了。要问我个人最深的体会是什么其实就一句不要把技能系统当成一个“工具管理后台”它是Agent工作流的核心数据面。技能定义得越规整、发现机制越健壮、执行链路越有纪律Agent的聪明程度才能真正转化为业务成果。如果你正准备从裸tool calling迁移到技能系统我的建议是从小处动手先挑三五个高频技能完成注册、检索、执行、归一化的最小闭环跑通再逐步把更多工具迁进去。不要一上来就想做完美平台先让它跑起来再让它变稳。最后分享一个小技巧技能上线前花十分钟用一个固定问题集跑一遍“选择准确率”评测。把每个技能的description反复打磨到评测集上稳定通过再放开给Agent。这个简单习惯比你在上线后调十次prompt都管用。
做Agent接入真实业务时卡住我的从来不是大模型本身而是那些“会做事的手”——一次查询、一次写库、一次调用第三方接口。大多数入门教程都在讲tool calling怎么把函数列表喂给模型但真到了几十个工具、多轮调用、多角色权限的规模这套做法会先崩。这篇文章聊的是我在模拟项目X里落地的一套agent-skills设计把技能当成与Agent生命周期绑定的第一公民从定义、注册、发现到执行、编排、审计全链路遇到的问题以及我手上的解法。如果你正准备把Agent从Demo推向生产这篇文章应该能帮你少走不少弯路。1. 从函数列表到技能系统为什么单靠tool calling会先崩1.1 tool calling的现状与瓶颈先说说最原始的做法。早期我给Agent接工具时就是把所有函数塞进system prompt让模型在请求里返回一个JSON指定调哪个函数、传什么参数。这种方式在小规模下很爽写个Python装饰器注册进列表完事。但规模一上来就出问题。第一个问题叫上下文爆炸。我给每个工具写描述、枚举、示例一个工具少说两百token。拢共二十个工具光工具定义就占掉四千多个token。如果每个工具的description再写得详细一点几千token就没了。你别小看这个开销Agent任务往往需要多轮对话每次都要把这堆工具定义重新发给模型Lantency和成本同步上涨。第二个问题是决策质量下降。工具多了以后模型经常选错。尤其是两个工具语义接近的时候比如“查询用户积分”和“查询用户优惠券”模型可能选错。不是模型笨而是工具描述本身长得很像没有足够区分度。我在模拟项目X里就遇到过用户问“我还有几张券”模型调了积分查询接口返回一堆积分流水LLM往对话里编了一个“您有XX张券”。很尴尬。第三个问题更隐蔽是逻辑碎片化。权限校验、限流、重试、日志、审计这些横切逻辑散落在各个函数handler里。今天A函数加了鉴权明天B函数忘了加。等安全问题爆发时你根本不知道哪些技能裸奔过。一句话总结工具是“函数级”的东西而Agent在真实业务里需要的是一整套“能力治理框架”。1.2 skills这个抽象到底补了什么技能系统和裸工具列表的最大区别在于它把“能力”做成了独立治理的对象。一个技能不再只是函数签名和描述它包含自然语言说明、结构化参数契约、执行实现、运行策略超时、重试、隔离级别、权限要求、审计配置、版本信息。技能是可注册、可发现、可审计、可编排、可灰度下线的一等公民。具体来说技能系统做了三件事一是把工具描述从“全量注入”变成“按需检索”。Agent在运行时先基于用户意图检索技能库选出最相关的3到5个技能再注入上下文。剩下几十个技能躺在仓库里不占token。二是把横切逻辑收拢到平台层。权限检查、限流、预算控制、日志上报全部由技能执行框架统一处理。技能作者只写纯业务逻辑不需要关心鉴权怎么做——这在一堆技能由多个小组共建时尤其重要。三是让组合复用成为可能。单技能是原子操作但很多用户需求是复合的查订单状态如果状态是“待付款”就提醒付款如果是“已发货”就再拉物流轨迹。把这种“判断动作”的组合封装成可复用技能整个Agent的表达能力会上一个台阶。1.3 什么场景才需要技能系统这里说句大实话不是所有项目都需要上技能系统。如果你的Agent总共只有三五个工具、单机部署、用户就你自己调试裸tool calling完全够用。硬上一个复杂的技能框架反而让简单事情变复杂。我判断要不要上技能系统就看三个条件是否命中技能数量已经超过15个或者预计半年内会超过有多个人、多个团队要往同一个Agent里贡献能力有权限、审计、合规要求不能“谁都能调一切”三个条件里中了两个就该把技能系统纳入设计。我当时在模拟项目X里就是三个全中技能一度膨胀到47个参与者横跨两个小组还要对接内部数据权限体系。裸工具列表真扛不住。2. 一份技能该怎么定义元数据、参数契约与语义描述2.1 技能元数据到底有哪些字段说到技能定义很多人的第一个反应是“写个函数再加个description”。但技能系统里一个技能是结构化的元数据对象。我在项目里用的技能定义大概是这个结构skill: name: query_user_points display_name: 查询用户积分 description: 查询指定用户的当前积分余额和近30天积分变动。 version: 1.2.0 visibility: internal owner_team: user-service tags: [user, points] parameters: type: object properties: user_id: type: string description: 用户唯一标识 required: [user_id] returns: type: object properties: total_points: { type: integer } recent_changes: { type: array } policies: timeout_seconds: 5 max_retries: 1 isolation: process rate_limit: 100 permissions: require: [user_service.read]字段看起来多但每个都有用途。name和display_name前者是机器唯一标识后者给模型和用户看description给LLM看的核心语义version技能也是软件也会有变更和回滚visibility控制谁能发现这个技能内部/外部/灰度可见owner_team出问题了找谁returns这个字段很多人忽略但它对结果归一化特别关键后面详细说我坚持的一点技能定义必须走代码仓库经过评审合并而不是在数据库界面里手工改。技能是运行时Asset得有版本历史。2.2 参数契约JSON Schema的“宽进严出”设计参数契约是技能系统里最容易做过头、也最容易做塌的部分。做过头是指用JSON Schema的additionalProperties: false把参数卡得死死的还套一堆oneOf、嵌套anyOf。大模型按你的schema填参数十次有几次填出非法结构。尤其嵌套场景模型即使只犯了字段名大小的错解析器直接报错技能调用失败。我的做法是“宽进严出”入参schema尽量宽松执行层内部再做强校验和默认值兜底。具体来说除必需字段外都允许缺省对外暴露简单扁平结构尽量不搞多级嵌套选择性地关闭additionalProperties: false但代价是在执行处理器里主动忽略未知字段数字字段不要用enum严格枚举除非这个字段确实只接受固定值否则给模型留解释空间举个例子。一个“发站内信”技能input如果要求{ user_id: string, template: string, variables: object }这就够了。不要强迫模型把variables展开成一个极其严格的模板结构。模板参数缺了某个变量执行层捕获后补默认值并把告警写入日志。这样技能成功率会明显提升。2.3 description的写法直接决定模型选不选得对这一节我要多写几句。在技能系统里你给LLM看的description质量几乎决定了它的选择质量。我在实践中总结了几条基本规则。第一用动词开头第一句就点明能干什么。比如“查询指定用户的积分余额和近期变动记录”比“这是一个用户积分服务”好得多。模型是拿description去匹配用户意图的动词开头的句式匹配效率高。第二明确写“这个技能不干什么”。听起来很怪但我用过很成功。比如查询用户积分余额。注意只支持查询不支持修改不做兑换、不做扣减如需查询优惠券请使用query_user_coupons。为啥要写反面因为两个技能描述如果都很正面模型无法区分边界。你直接把边界写清楚模型选错的概率大幅下降。我做了一批技能description的对比测试加入“不要做什么”之后技能选择准确率从82%提到93%。第三给一个使用样例。模型对例子的理解通常比抽象描述好。样例可以是“例如user_idu12345时返回该用户的积分总额”。这个样例不需要很长一两行就够。第四控制长度。description不是越长越好。太长会稀释重点。我控制在一个中等的区间技能的全部提示描述包括参数说明加起来不超过几百token。超出部分要么拆成另一个技能要么挪到执行文档里。3. 技能注册与发现让Agent在运行时“找得到、选得对”3.1 注册中心与schema校验技能定义写好了下一步是进注册中心。注册中心本质上就是一个带索引的技能仓库我把它分成三层存储层、校验层、索引层。存储层我用的是普通关系库技能元数据存JSONB字段方便整体读写。校验层在写入前做几件事name是否重复、name是否符合命名规范、description是否为空或过短、parameters是否合法JSON Schema、required字段是否都在properties里声明过。这些校验看起来基础但能拦下不少低级错误。我印象里有一次技能上线直接把整个发现服务的内存打爆原因是某技能描述里塞了一个超长的base64样例。后来加了长度校验问题就没再出现。索引层负责把技能转成可检索的形式为description、display_name、tags做一些分片文本索引同时调用embedding接口为向量索引计算向量。3.2 检索式技能发现embedding不能解决所有问题技能数量一多全量注不行所以触发方式变成“检索”。我一开始以为embedding检索就够实测发现单独只有它并不可靠。问题出在embedding的语义边界。用户问“我还有几张优惠券”技能库里有“查询优惠券”和“查询积分”两者的向量距离有时还挺接近。只靠top-k召回可能把两个都捞上来把上下文让给了不相关技能。我的最终方案是“混合检索”文本关键词召回加向量召回然后合并排序。关键词负责精确匹配比如技能name、tag里的user、coupon等词向量负责语义泛化。排序时引入一个小的意图分类器做粗排先在候选技能里筛出与当前对话意图明显相关的再用规则精排比如用户明确提到“积分”时“查询积分”的权重直接拉高。这听起来复杂但落地上很简单候选集基本只有几十个技能在这上面做规则排序毫秒级完成不会有性能压力。还有一层容易被忽略检索必须带上权限和可见性过滤。一个普通用户查询技能时发现服务在检索前就把visibility: internal的技能过滤掉模型根本不会“看到”它。这比执行时再拦截更干净因为模型压根不会提出非法调用。3.3 命中结果怎么塞进上下文检索召回之后不能直接把全部字段倒进system prompt。上下文是稀缺资源我控制最终注入技能数在3到5个之间。注入前做一次裁剪每个技能只保留name、缩短后的description、参数JSON Schema、以及一两个关键示例。owner_team、policies这些治理字段不进入模型上下文。description我有一套截断逻辑先取第一句话动词开头那句再视剩余预算决定要不要补充“不做什么”部分。有一点我特别想提醒注入顺序也有讲究。模型倾向于调用列表里排在前面的技能。所以我把排序分数最高的技能排在最前面并且用分隔符把每个技能块隔开。实测这样比把所有技能凑成一坨让模型自己挑的效果好得多。4. 技能的执行链路参数校验、权限检查与结果归一化4.1 执行前的三道闸技能被模型选定了接下来进入执行链路。这一段是生产环境里最容易出事故的地方。我在模拟项目X里总结出执行前必过的三道闸。第一道schema参数校验。虽然前面说“宽进”但基础结构还是要验必填字段是否都有、类型对不对。这层校验执行在框架层不依赖模型判断。校验失败时框架会组装一个结构化错误返回给模型让它重新提参而不是直接失败。第二道权限与审批。技能执行前框架拿当前会话的身份上下文与技能声明的permissions做匹配。权限不足时看技能配的是“拒绝”还是“申请审批”。高危技能比如删除、发钱、改密默认走审批审批消息直接推到人工工作台。第三道限流与预算。每个技能有自己的限额同时整个Agent会话也有总预算。如果技能属于内部高频而且没有限流一次并发尖峰可能把下游服务打挂。我给所有技能都加了一个统一的熔断器QPS超过阈值直接返回“当前技能繁忙请稍后再试”。4.2 沙箱与隔离技能执行不是简单调用函数它需要隔离策略。我按危险级别分三档低危纯查询、纯计算在线程池里跑就够了加超时中危涉及文件读写、网络请求但范围受限放进独立子进程高危执行不可信内容、需要完全隔离直接跑在容器里线程、子进程、容器三种模式的代价差别很大。线程快但隔离差子进程每次启动有开销容器最安全但最重。我大多数查询技能走线程池只有涉及数据变更的才升级为子进程。超时和重试是另一个坑。不要对所有技能用统一超时。查数据库接口5秒可能就够但调用第三方外部接口可能30秒都不够。我在技能元数据里加了timeout_seconds字段每个技能单独配。重试也要考虑幂等性。查询类技能重试没问题但“创建订单”这类技能重试可能产生两笔订单。我的规则是只有声明了idempotent: true的技能才允许框架自动重试否则直接把失败抛给模型让模型决定要不要换个方式处理。4.3 结果回传把非结构化输出折算成模型能用的信号技能执行完结果怎么回给模型决定了Agent最后一轮回答的质量。我看到很多项目直接把函数返回值原样塞回去比如一个JSON对象嵌套五六层。模型拿到后要么理解不了要么把字段名报给用户毫无体验。我的做法是结果归一化。在技能元数据里定义returns结构执行框架把原始返回包成统一的响应信封{ status: success, data: { total_points: 1200, recent_changes: [] }, error: null, note: 查询成功 }如果出错则{ status: error, data: null, error: { code: BOOM_003, message: 用户不存在或已注销 }, note: 无法查询该用户积分请向用户解释用户可能已注销 }重点在note字段它是给LLM的自然语言提示告诉模型遇到了什么问题、该怎么收场。这就是“把程序语言翻译成模型语言”的过程。结果数据过大也要截断。一次查询可能返回几千条流水全塞给模型既不经济也没必要。我统一在返回层做聚合和截断只保留前20条明细并在note里说明“还有XX条未显示”。5. 多技能编排从单一技能到可复用工作流5.1 主动式编排Agent自主选择技能序列技能系统的能力不只是单个调用还包括多技能组合。最自然的组合方式是“主动式编排”模型自己决定先调哪个、再调哪个、根据结果判断下一步。这种方式的优点是灵活处理意外情况的能力强。用户在Agent里来一句“帮我查一下订单到了的话提醒我取件”模型会自己拆解查询订单状态如果已到站则调用“生成取件提醒”技能。缺点也明显模型自主编排容易碰壁。一是时序错乱比如先查物流再查订单两步反过来问题不大但“先查询后更新”如果顺序反了数据一致性就出问题。二是对话上下文过长后模型可能会遗忘早期步骤的结果导致编造数据。我对主动式编排的底线是允许模型自主选择技能但禁止它调用带副作用的技能写库、发送、删除作为编排中的“尝试性步骤”。带副作用的技能只有经过明确的用户确认才会放行。5.2 被动式编排预定义DAG/顺序链真正的多技能组合任务我更推荐用被动式编排预先定义一张DAG每个节点是一个技能边代表依赖关系。模型只选择执行哪个工作流模板而不是完全自由发挥。比如“售后工单处理”工作流workflow: after_sales_handler nodes: - name: verify_user skill: query_user_info - name: get_order skill: query_order_status depends_on: [verify_user] - name: decide_refund skill: evaluate_refund_policy depends_on: [get_order] - name: apply_refund skill: create_refund_order depends_on: [decide_refund] condition: ${decide_refund.eligible true}我在这里会把工作流本身也注册为一个“组合技能”。用户问“我要退货”发现服务召回的可能是after_sales_handler这个组合技能而不是五个原子技能。模型只需要记住工作流的入口和结果具体内部逻辑由执行引擎按DAG处理。这种方式的收益是稳定工作流中间任何一个环节失败流程可以精确反馈到模型A技能成功但B技能失败时错误信息清晰可见不会让模型在黑暗中瞎猜。5.3 技能之间共享数据做了编排之后“技能之间的数据怎么共享”立刻变成绕不开的问题。简单方案是一个会话级的内存数据区工作流执行器把上一个技能的data字段塞进共享上下文下一个技能按key取用。但这里有一个矛盾技能不该隐式依赖全局共享否则技能A改了全局变量技能B的路由全乱套。我采用的折中方案工作流节点之间只通过显式声明传递数据。在上面YAML里每个节点可以加inputs映射比如get_order的user_id来自verify_user输出的user_data.user_id。执行器在节点间做一次显式的参数传递技能本身不知道全局上下文存在。这样做的好处是每个技能仍然是一个黑盒只管自己的输入输出便于单独测试、单独复用。坏处是编排定义会啰嗦一点但这点配置成本换来的是可排查性和稳定性值。数据血缘也顺带解决了任何一个工作流的会话都能查得出某条最终结果是由哪些技能、哪些原始数据推导出来的。出了问题链路一眼可见而不是在日志里捞针。6. 实测踩坑记录权限、并发与技能漂移6.1 权限粒度技能级、操作级、行级权限这块是我在生产环境里踩得最深的一个坑。最初我给技能只定义了“谁能调”这一层但真实业务很快告诉我这远远不够。举个例子。“查询用户信息”这个技能客服角色和用户自己都能调。但客服查用户A的信息和用户A查自己的信息能看到的字段完全不同。客服可以看到手机号、历史订单用户自己只能看到昵称、头像。如果权限只做到技能级那用户一旦被允许调用这个技能可能间接摸到他人的隐私数据。于是我把权限拆成三层技能级该角色能不能调这个技能操作级同一技能在特定参数模式下角色能做什么。比如查询技能客服模式允许查全量用户模式只允许带自己的user_id行级返回数据里哪些字段对当前角色可见。敏感字段在结果归一化前直接被抹掉行级过滤是我强烈建议从第一天就做的。不要指望模型帮你做脱敏模型没有可靠性可言。框架层在技能返回后、回传模型前做一次字段级过滤才是最稳妥的防线。6.2 并发与状态冲突技能不能偷偷持有可变状态这个坑源自一次线上事故。某个技能在内部维护了一个字典缓存用来存上次查询结果。单线程调试一切正常但并发上来后两个会话的查询结果互相污染A用户问积分返回的却是B用户的数字。排查过程比较曲折最后定位到问题不是出在LLM的提示词而是技能实现里偷偷保留了模块级可变状态。这给我立了一条硬约束技能必须是无状态的。状态要么来自入参要么来自工作流上下文技能自身不允许持有多轮会话缓存。如果确实需要缓存也要把缓存键绑定到会话ID和用户ID并且在上层框架统一管理而不是散落在技能内部。这条约束写进团队的技能开发规范之后并发类问题基本绝迹。6.3 技能漂移与回归测试技能系统上线后最阴险的坑是“技能漂移”技能对应的下游接口升级了字段变了但技能元数据里的description和returns还是老样子。模型按旧的描述调用传了旧的参数名执行层解析失败Agent表现断崖式下跌。解决漂移靠人工排查是不现实的。我给模拟项目X配了一套自动回归测试每个技能配一组预置测试用例输入、期望输出、期望状态码每天晚上自动跑一遍全量技能回归哪几个技能导致失败立刻生成告警并定位是description问题还是参数契约问题这轮回归还顺手解决了一个问题技能description过时。我有一次发现某技能选准确率骤降跑回归测试后发现下游接口把“账单编号”改成了“账单ID”但description里没更新导致模型按老字段生成参数。回归测试一跑这类问题当夜就能发现而不是等用户投诉。另外技能发版也要走灰度流程。凡是涉及参数契约改动的技能我先让它在灰度可见范围内运行几天确认命中率和错误率没有劣化再全量放开。技能系统本身就是可灰度、可回滚的这比裸工具列表强得多。6.4 最后想留给大家的一句话文章写到这差不多把我在技能系统上踩过的重要坑都讲完了。要问我个人最深的体会是什么其实就一句不要把技能系统当成一个“工具管理后台”它是Agent工作流的核心数据面。技能定义得越规整、发现机制越健壮、执行链路越有纪律Agent的聪明程度才能真正转化为业务成果。如果你正准备从裸tool calling迁移到技能系统我的建议是从小处动手先挑三五个高频技能完成注册、检索、执行、归一化的最小闭环跑通再逐步把更多工具迁进去。不要一上来就想做完美平台先让它跑起来再让它变稳。最后分享一个小技巧技能上线前花十分钟用一个固定问题集跑一遍“选择准确率”评测。把每个技能的description反复打磨到评测集上稳定通过再放开给Agent。这个简单习惯比你在上线后调十次prompt都管用。
