★ FEATURED ARTICLE 1. 从“技能”这个词说起为什么Agent需要一套技能体系“agent-skills”这个标题乍一看像是某个开源仓库的名字或者某个技术团队内部对智能体能力模块的统称。它没有附带正文、关键词和摘要信息量极少但恰恰是这种极简的标题反而给了我们足够的空间去拆解它背后真正值得聊的东西。我打算从一线开发者的视角把“智能体技能”这件事从头到尾讲清楚——它是什么、为什么需要它、怎么设计、怎么落地、踩过哪些坑。先给不熟悉这个方向的朋友一个最朴素的解释。所谓智能体你可以理解为一个能自主感知环境、做出决策并执行动作的程序实体。它可能是对话式的也可能是任务式的甚至可能是控制物理设备的。而“技能”就是它能够执行的一个个具体能力单元。比如“查询天气”是一个技能“发送邮件”是一个技能“从一段文本里抽取日期”也是一个技能。把这些技能组织起来让智能体在合适的时机调用合适的技能这就是agent-skills要解决的核心问题。为什么这件事值得单独拿出来做一套体系因为早期大家做智能体往往是把所有逻辑写在一个巨大的提示词里或者写在一个巨大的函数里。你告诉模型“你可以做A、B、C、D、E”然后模型自己决定怎么做。这种做法在技能数量少于五个的时候还能凑合一旦超过十个问题就爆炸了。模型会混淆技能边界会忘记某个技能的存在会在不该调用的时候调用会在该调用的时候不调用。更麻烦的是你没法单独测试某个技能也没法复用更没法让不同的人并行开发。所以agent-skills的本质是把智能体的能力做“服务化”和“注册化”。每个技能是一个独立的、自包含的模块有明确的输入输出定义有清晰的触发条件有独立的错误处理。智能体本身只负责一件事根据当前上下文从技能注册表里选出最合适的技能把参数传进去拿到结果继续推理。这个思路和微服务架构非常像只不过服务提供方从远程API变成了本地函数或远程工具。我见过不少团队在这个问题上走弯路。有的团队把技能写成了巨大的if-else分支结果维护成本极高有的团队把技能定义和提示词混在一起导致每次改技能都要重新调提示词还有的团队干脆不做技能抽象所有能力都靠模型“即兴发挥”结果稳定性极差。这些坑我在后面会逐一展开先建立一个基本认知agent-skills不是简单的函数集合它是一套包含注册、发现、调用、监控、版本管理的完整体系。2. 技能注册表的设计让智能体知道“自己能做什么”2.1 注册表的数据结构选择技能注册表是整个体系的地基。它要回答一个核心问题智能体在运行时如何知道自己有哪些技能可用最直接的做法是维护一个列表每个元素包含技能名称、描述、参数schema、调用入口。这个列表可以是一个JSON文件可以是一个数据库表也可以是一个内存中的对象。选择哪种形式取决于你的技能是静态的还是动态的。如果你的技能在部署时就固定了那用一个JSON文件完全够用。我一般会把它放在项目根目录下的skills.json结构大概是这样{ skills: [ { name: get_weather, description: 查询指定城市的当前天气情况, parameters: { type: object, properties: { city: { type: string, description: 城市名称如北京、上海 }, unit: { type: string, enum: [celsius, fahrenheit], default: celsius } }, required: [city] }, endpoint: local://weather.get_weather } ] }这个结构的好处是它和大多数模型平台的工具调用格式是兼容的。你几乎可以直接把这个JSON喂给模型模型就能理解每个技能是干什么的、需要什么参数。但这里有一个容易被忽略的细节description字段的写法。很多人写描述的时候非常随意比如“查天气”三个字。这会导致模型在多个相似技能之间犹豫不决。正确的做法是描述里要包含“什么时候用”和“什么时候不用”。比如“查询指定城市的当前天气情况。当用户询问实时天气、温度、是否下雨时使用。不适用于查询历史天气或未来预报。”2.2 技能发现的两种模式技能发现分为静态发现和动态发现。静态发现就是启动时加载全部技能运行时不变化。动态发现则是运行时根据上下文加载不同的技能子集。大多数场景下静态发现就够了因为技能数量通常不会超过几十个。但如果你做的是一个平台型产品不同租户有不同的技能权限那就需要动态发现。动态发现的实现方式有两种。一种是在注册表里给每个技能打标签比如tenant: a然后运行时根据当前租户过滤。另一种是把技能注册表做成一个服务智能体通过一个“列出可用技能”的元技能来获取当前可用的技能列表。第二种方式更灵活但会增加一次额外的调用开销。我的经验是如果技能数量在五十个以内直接用标签过滤就够了没必要引入额外的服务调用。这里有一个实操中的坑技能名称的命名冲突。如果你允许不同模块注册同名技能那注册表里就会出现重复项。模型拿到两个叫search的技能它根本分不清该用哪个。解决办法是在注册时做唯一性校验如果名称已存在要么拒绝注册要么自动加前缀。我倾向于拒绝注册因为自动加前缀会让模型困惑它不知道module_a_search和module_b_search到底有什么区别。2.3 参数schema的编写要点参数schema是技能和模型之间的契约。写得好模型调用准确率就高写得差模型就会传错参数或者漏传参数。我总结了几个关键点。第一每个参数都要有description而且描述要具体。比如city参数不要只写“城市”要写“城市名称使用中文如北京、上海、广州”。如果参数有枚举值一定要用enum列出来不要指望模型自己猜。第二必填参数和可选参数要分清。required数组里只放真正必须的。有些开发者把所有参数都标成必填结果模型每次都要追问用户体验很差。第三参数类型要尽量简单。模型对string、number、boolean的处理最稳定对嵌套对象和数组的处理容易出错。如果某个技能需要复杂结构考虑拆成多个技能或者让参数接受JSON字符串然后在技能内部解析。第四默认值要显式声明。比如unit参数默认celsius就在schema里写清楚。这样模型在用户没说单位的时候可以自动填默认值而不是反问用户。3. 技能调用的完整链路从模型决策到结果回传3.1 模型如何选择技能当用户输入一句话比如“北京今天热不热”智能体需要决定调用哪个技能。这个决策过程通常由模型完成。你把技能注册表转换成模型能理解的格式大多数平台叫“工具”或“函数”连同用户输入一起发给模型。模型返回一个结构化的调用请求包含技能名称和参数。这里的关键是模型的选择准确率取决于三个因素技能描述的清晰度、技能之间的区分度、以及提示词里对调用时机的说明。我见过很多团队只关注前两个忽略了第三个。实际上在系统提示词里加一段“当用户询问实时信息时优先使用查询类技能当用户要求执行操作时使用操作类技能”这样的引导能显著提升准确率。还有一个细节模型可能会一次性返回多个技能调用请求。比如用户说“查一下北京和上海的天气”模型可能返回两个get_weather调用。你的调用层要能处理这种并行调用而不是只取第一个。并行调用的结果要按顺序回传给模型否则模型会混淆哪个结果对应哪个城市。3.2 参数校验与补全模型返回的参数不一定完全正确。它可能漏传必填参数可能传了错误类型可能传了枚举值之外的字符串。所以调用层必须做参数校验。校验不通过的时候有两种处理策略一种是直接返回错误给模型让模型重新生成另一种是尝试自动补全比如从上下文里提取缺失的参数。我倾向于第一种策略因为自动补全的逻辑很难写全而且容易引入隐蔽的bug。但有一种情况例外如果缺失的参数是“当前时间”或“当前用户ID”这类系统已知信息那可以在调用层自动注入没必要让模型去猜。参数校验的另一个作用是防止注入攻击。如果技能内部要执行系统命令或数据库查询那参数必须经过严格的转义和过滤。这一点在技能涉及外部输入时尤其重要。3.3 技能执行与超时控制技能执行可能是本地的函数调用也可能是远程的API请求。无论哪种都必须设置超时。本地调用超时通常设短一些比如5秒远程API超时设长一些比如30秒。超时之后要返回一个明确的错误信息给模型比如“天气查询服务暂时不可用请稍后重试”。模型拿到这个信息后可以选择告诉用户也可以选择尝试其他技能。这里有一个容易被忽略的问题技能执行失败后的重试策略。如果技能是幂等的比如查询天气那可以自动重试一次。如果技能不是幂等的比如发送邮件那绝对不能自动重试否则用户会收到两封邮件。所以每个技能的定义里应该有一个idempotent标志调用层根据这个标志决定是否重试。还有一个坑是技能执行过程中的日志记录。很多团队只记录调用成功或失败不记录参数和返回值。结果线上出问题的时候根本不知道模型传了什么参数、技能返回了什么。我的做法是每次调用都记录一条结构化日志包含技能名称、参数、返回值、耗时、是否成功。这些日志在排查问题时非常有用。3.4 结果格式化与回传技能返回的结果不能直接丢给模型需要做格式化。格式化的目标是让模型容易理解同时控制token消耗。比如一个查询数据库的技能返回了100行数据你不能把100行都塞给模型那样token会爆炸。正确的做法是在技能内部做聚合或截断只返回摘要信息。结果格式化的另一个要点是错误信息的处理。如果技能执行失败返回的错误信息要足够具体让模型知道下一步该怎么做。比如“城市名称无法识别请确认城市名是否正确”就比“查询失败”要好得多。回传结果的时候要注意和原始调用请求的对应关系。如果模型发起了多个调用回传结果时要标明每个结果对应哪个调用。大多数模型平台支持在结果里带上tool_call_id你要确保这个ID正确传递。4. 技能的生命周期管理版本、测试与灰度4.1 技能版本化的必要性技能不是一成不变的。今天get_weather只支持城市名查询明天可能要支持经纬度查询。如果你直接修改技能定义那正在运行的智能体可能会因为参数变化而调用失败。所以技能需要版本化。版本化的实现方式有两种。一种是每个版本一个独立的技能名称比如get_weather_v1和get_weather_v2。另一种是技能名称不变但在注册表里维护多个版本调用时指定版本号。我倾向于第一种因为模型对名称的变化更敏感它更容易理解get_weather_v2是一个新技能而不是同一个技能的不同版本。版本化之后旧版本不能立刻删除。你要给调用方一个迁移期。在迁移期内两个版本同时存在模型可以根据提示词里的引导选择新版本。迁移期结束后再下线旧版本。4.2 技能测试的三种层次技能测试不能只测“能不能跑通”。我一般分三层来测。第一层是单元测试。针对技能本身的逻辑输入固定参数验证输出是否符合预期。这一层不涉及模型纯粹测代码。第二层是集成测试。把技能注册表加载进来模拟模型返回的调用请求验证调用链路是否通畅。这一层要覆盖参数校验、超时处理、错误回传等分支。第三层是端到端测试。用真实的用户输入让模型自主决策观察它是否选择了正确的技能、传了正确的参数、最终给出了正确的回答。这一层最难自动化因为模型的输出有随机性。我的做法是准备一批标准问题每次测试跑一遍统计技能选择准确率和参数准确率。准确率低于阈值就告警。这里有一个实操心得端到端测试的用例要覆盖“边界情况”。比如用户输入非常模糊的时候模型应该选择追问而不是瞎调用技能。再比如用户输入包含多个意图的时候模型应该按顺序调用多个技能。这些边界情况在单元测试里覆盖不到只有端到端测试才能发现。4.3 灰度发布与回滚新技能上线不能一次性全量。你要先让一小部分流量走新技能观察一段时间。观察的指标包括调用成功率、平均耗时、模型选择准确率、用户满意度。如果指标正常再逐步扩大流量。如果指标异常立刻回滚。灰度发布的实现方式取决于你的架构。如果技能是本地函数那可以用配置开关控制。如果技能是远程服务那可以用路由权重控制。无论哪种方式都要保证回滚是秒级的不能等几分钟。回滚之后要分析失败原因。是技能逻辑有bug还是描述写得不好导致模型选错还是参数schema有问题。找到原因后修复、重新测试、重新灰度。5. 常见踩坑记录与排查思路5.1 模型“幻觉调用”不存在的技能这是最常见的问题。模型返回了一个技能名称但注册表里根本没有这个技能。原因通常是提示词里提到了某个技能但注册表里没注册或者模型把技能名称记错了。排查思路首先检查提示词和注册表是否一致。如果提示词里写了“你可以使用搜索技能”但注册表里技能叫web_search模型就可能返回search。解决办法是提示词里不要列举技能名称让模型完全依赖注册表。其次在调用层加一层校验如果技能名称不在注册表里直接返回错误给模型让它重新选择。5.2 参数类型不匹配导致的静默失败模型传了一个字符串25但技能期望的是数字25。如果技能内部没有做类型转换就可能静默失败返回一个错误的结果。这种问题很难发现因为调用链路是通的只是结果不对。排查思路在调用层做严格的类型校验。如果参数类型不匹配直接返回错误不要尝试自动转换。同时在技能内部也要做防御性编程对关键参数做类型检查。5.3 技能描述过于相似导致选择困难注册表里有两个技能一个叫search_web一个叫search_docs。描述分别是“搜索网页”和“搜索文档”。模型很难区分什么时候该用哪个。结果就是随机选择准确率极低。排查思路重新写描述明确每个技能的适用场景。比如search_web的描述改成“搜索互联网上的公开信息。当用户询问实时新闻、天气、股票价格等外部信息时使用。”search_docs的描述改成“搜索内部知识库中的文档。当用户询问公司政策、产品文档、历史项目资料时使用。”这样模型就能根据用户问题的性质做出选择。5.4 技能执行时间过长导致整体超时某个技能执行了30秒但整个智能体的超时设置是20秒。结果技能还没返回智能体就已经超时了。用户看到的是“服务超时”而不是技能返回的结果。排查思路给每个技能单独设置超时并且技能超时时间要小于智能体整体超时时间。如果某个技能确实需要很长时间考虑把它改成异步执行先返回一个“任务已提交”的响应然后通过轮询或回调获取结果。5.5 技能返回结果过大导致token溢出技能返回了一个巨大的JSON包含几百个字段。模型拿到这个结果后token直接爆了。或者模型只关注了前几个字段后面的信息完全忽略了。排查思路在技能内部做结果裁剪。只返回模型真正需要的字段。如果确实需要返回大量数据考虑分页返回让模型通过多次调用获取完整数据。另外可以在提示词里告诉模型“如果结果包含大量数据先总结再回答”。6. 从单技能到技能编排进阶玩法6.1 技能链式调用单个技能往往不够用。用户说“帮我查一下北京天气如果下雨就提醒我带伞”。这需要先调用get_weather根据结果判断是否下雨如果下雨再调用send_notification。这就是技能链式调用。链式调用的实现方式有两种。一种是让模型自己编排它先调用天气技能拿到结果后再决定是否调用通知技能。另一种是在技能层做编排把“查天气并判断是否提醒”封装成一个复合技能。我倾向于第一种因为灵活性更高模型可以根据实际情况调整。但第一种的缺点是如果中间某一步失败整个链条就断了。所以需要在提示词里告诉模型“如果某个技能调用失败尝试其他方案或告知用户”。6.2 技能组合与复用有些技能是基础能力比如“读取文件”、“写入文件”、“发送HTTP请求”。有些技能是业务能力比如“生成报告”、“发送周报”。业务能力可以由基础能力组合而成。比如“发送周报”可以拆成“读取周报模板”、“填充数据”、“发送邮件”三个基础技能。这种组合复用的好处是基础技能可以独立测试和优化业务技能只需要关注编排逻辑。但缺点是调用链路变长了延迟会增加。所以要在复用和性能之间做权衡。我的经验是如果基础技能非常稳定那组合复用没问题如果基础技能经常变动那组合复用会导致业务技能也跟着不稳定。6.3 技能权限与安全边界不是所有技能都应该对所有用户开放。比如“删除数据库”这种技能只能让管理员调用。所以技能注册表里要包含权限信息调用层要根据当前用户的角色做鉴权。鉴权的实现方式有两种。一种是在注册表里给每个技能打上required_role标签调用层检查当前用户角色是否匹配。另一种是把权限控制放在技能内部技能自己判断当前用户是否有权限。我倾向于第一种因为权限控制是横切关注点放在调用层更统一。安全边界的另一个问题是技能之间的隔离。如果技能A和技能B共享同一个全局状态那A的修改可能影响B。所以技能应该尽量设计成无状态的所有状态通过参数传入和返回值传出。如果确实需要状态那状态应该由智能体本身管理而不是技能内部管理。7. 我个人的一些实操体会做agent-skills这套东西最深的体会是技能的设计质量直接决定了智能体的上限。模型再强如果技能定义得乱七八糟智能体也表现不好。反过来如果技能定义得清晰、边界明确、参数规范即使模型能力一般智能体也能跑得不错。另一个体会是不要试图一次性设计出完美的技能体系。我见过太多团队花几周时间设计技能注册表的schema结果上线后发现根本用不上。正确的做法是先定义三五个核心技能跑通整个链路然后根据实际需求逐步增加。每增加一个技能就回头审视一下注册表的结构是否还合理是否需要调整。还有一点技能描述要当成产品文案来写。它不是给开发者看的是给模型看的。模型的理解能力和人不一样它更依赖明确的边界和具体的例子。所以描述里要多用“当...时使用”、“不适用于...”这样的句式少用模糊的形容词。最后监控和日志一定要做。智能体的行为有很大的不确定性没有监控你根本不知道它在线上的表现。我一般会监控几个核心指标技能调用成功率、平均调用次数、模型选择准确率、用户满意度。这些指标能帮你快速定位问题也能帮你评估每次技能调整的效果。这套体系不是一蹴而就的它需要持续迭代。但只要你把基础打牢后面的扩展就会越来越顺。
阅读完成 · 觉得有帮助？
