先聊点实际的。最近大半年agent-skills这个概念在圈子里的讨论度一路走高已经不是我刚接触时那种停留在论文里的时髦词了。很多做AI应用落地的朋友手头都有几个基于大模型的智能体项目跑几天 demo 没问题一旦塞进真实业务流问题就全冒出来了——工具调用经常出错、模型乱选动作、上下文越拖越长、同一套能力换个场景又要重新调。我慢慢意识到问题不在模型推理多聪明而是整个智能体缺失了一套技能化的组织方式。agent-skills就是干这个的它把智能体面对的一堆原始工具和自由动作收敛成有规范、有约束、可复用、可观测的技能体系模型不再靠猜来行动而是按技能库的规则去选择和执行。这篇东西我会把技能化背后的原理、我实际搭建和调试过程中的步骤、踩过的坑以及一组适合直接抄作业的配置思路完整写出来适合那些手上已经有Agent原型、准备往生产环境推的开发者也适合刚接触智能体开发、想避开弯路的新手参考。1. 技能化的核心思路为什么智能体需要技能而不是一堆工具1.1 从工具到技能的思维转变很多Agent项目初始阶段的做法很简单把所有能调的外部接口都塞给模型让它自己挑着用。这种做法的天花板很低典型的症状有三个。第一个症状是选择过载。一旦工具数量超过二十个模型在规划阶段的决策质量就会肉眼可见地下降。OpenAI 的早期实验里有一个很直观的数据工具数量从 5 个增加到 20 个模型的工具选择准确率下降接近 20 个百分点。原因不难理解所有工具描述拼在一起会占用大量上下文且描述之间会有语义重叠模型需要在噪声很大的信息里做精细区分。第二个症状是动作粒度不匹配。我们想要的其实是完成用户注册后自动发送欢迎邮件这种干净利落的操作但底层工具是写入用户表调用邮件接口生成邮件模板三步。让模型自由编排这三个步骤每多一个步骤就多一次出错的机会。真实生产环境里三步里任何一步失败了整个链路就要回滚而回滚逻辑本身又得靠模型自己处理复杂度会爆炸。第三个症状是行为不可控。业务方会问如果这个动作涉及高风险操作能不能先拦住人审一下或者这个动作只能由特定角色的用户发起。如果所有动作都是裸奔出来的 system prompt 加工具列表权限、审批、审计这些要求几乎没法落地。技能化就是为了解决这三个问题。所谓技能简单说就是把完成一个完整目标所需的数据输入、处理步骤、工具调用逻辑、输出规范、权限要求全部封装成一个独立单元。模型不需要知道技能内部怎么实现它只需要知道这个技能管什么、输入什么、会产出什么。这跟人类团队打工人一样——你说帮我整理一份上周的销售报表你不需要告诉助理销售数据存在数据库的哪张表里助理自己有一套熟知的流程去处理。1.2 Agent的运行循环感知、规划、调用、反馈要理解技能在Agent里的位置得先看Agent的运行方式。我习惯用一个四段式循环来描述感知阶段把用户请求和新进来的事件转换成模型可处理的意图描述规划阶段模型根据意图选择下一步动作如果是技能系统就从技能列表里挑最匹配的一项调用阶段由Agent运行时负责实际执行所选技能包括参数校验、权限检查、调用外部接口反馈阶段把执行结果传回模型让它决定是继续下一步还是直接回复用户。技能在这条链路里扮演的是规划与调用之间的规范层。没有这一层模型输出的是我要调用工具A、参数是xxx有了这一层模型输出的是我要调用技能新用户欢迎流程参数是user_id和email。表面上看只是表述变化实际上是把原本模型自由发挥的空间压缩成了一个受控的决策点。控制力提升了模型要思考的内容反而变少了——它不需要反复思考接下来调哪个函数只需要在几十个技能里选一个最合适的然后执行它。从我的开发经验看技能体系一旦建立Agent的行为可预测性会得到质的提升。调试难度也会下降很多因为每一条决策路径都被技能的边界约束住了报错时能快速定位到具体某个技能内部的问题。2. 技能结构拆解一个技能到底由什么组成2.1 标准技能包的字段定义我自己的技能包结构经过多轮迭代最后固定成了下面这个模板。这个结构不是拍脑袋定的而是从实际调试经验里逆推出来的id: user.onboarding.welcome_email name: 新用户欢迎邮件发送 version: 2.3.1 description: 在新用户完成注册并验证邮箱后发送包含初次登录指引的欢迎邮件。 如果用户已收到过欢迎邮件则跳过发送。 tags: [用户运营, 邮件, 注册流程] trigger: event: user.registered condition: email_verified true input: fields: - name: user_id type: string required: true description: 用户在系统中的唯一标识 - name: email type: string required: true validation: regex: ^[\\w\\.-][\\w\\.-]\\.\\w$ preconditions: - user.status ACTIVE - not has_received_welcome_email(user_id) visible_to: [user_service, marketing_service] semantics: model: gpt-4o-mini temperature: 0.2 max_steps: 3 allow_fallback: true actions: - type: api name: fetch_user_profile args: user_id: {input.user_id} - type: api name: send_email_with_template args: to: {input.email} template_id: welcome_v3 variables: name: {fetch_user_profile.result.nickname} login_url: https://example.com/first-login output: type: object fields: message_id: string sent_at: datetime on_error: retry: 2 fallback_action: notify_admin timeout_ms: 3000这个结构里最重要的几个字段不是那些看起来复杂的actions部分而是前置约束和可见性控制。前置约束能避免模型把一个不该重复执行的技能反复调用比如针对用户注册没几天就不活跃的情况可以加一个最近七天内没有收到过任何营销触达的条件把无意义的打扰源头掐掉。可见性控制则决定了哪些上层模块能搜到并调用这个技能这个对于大型Agent系统特别关键能规避技能库膨胀后互相干扰的问题。2.2 输入定义与校验防的就是模型乱传参模型调用技能时最容易出的问题不是选错了技能而是传了不符合要求的参数。于是我把参数校验从技能内部挪到了调用入口统一由Agent运行时处理。校验分成三部分第一是格式校验比如邮箱的正则、手机号的长度第二是语义校验比如日期不能早于今天、金额不能大于某个阈值第三是状态校验比如目标用户必须处于活跃状态。格式校验和语义校验可以写在技能定义里状态校验则需要调用内部API实时判断。我一直强调一个理念任何未经验证的输入都必须止步于技能边界之外。实践下来这个规则极大地降低了外部接口报错率。早期我没有做严格校验时外部接口调用失败率大概在百分之十二左右其中一半以上都是参数问题比如把空字符串传给了必填字段、把时间格式传错、把用户ID类型传成了整数而接口要求的是字符串。加了统一校验之后这类问题几乎消亡了。2.3 技能描述的表达技巧让模型一看就懂模型在规划阶段主要依赖技能描述来决定选哪个技能。描述写得好不好直接影响模型的选择准确率。我在这个上面反复调过很多版总结出几个关键点描述要用动词开头说明技能完成的具体动作而不是一组抽象名词。比如发送欢迎邮件优于邮件处理能力。描述里要写清楚什么情况下不该用这比写什么时候该用更防呆。比如仅用于新用户注册完成后老用户主动索取场景请使用技能ID: user.support.resend_email。描述中避免使用语义接近的词语。如果两个技能的描述里都出现了邮件发送这些词模型很容易混淆。我后来做过一次语义消歧专门把描述里的重叠关键词做了拆分准确率升了大约7个点。这个描述过程是纯手工活没法完全靠自动化。但值得花时间因为技能定义是一种资产定义得好不好直接影响后续所有Agent任务的执行质量。3. 技能注册与运行时设计让Agent真正学会用技能3.1 注册中心与动态加载机制技能不是写在某个代码文件里就完事的它需要一个注册中心来统一管理。我采用的是技能注册中心模式每个技能包注册时上报自己的ID、版本、描述、校验规则、可见范围注册中心统一汇总生成一份技能清单供Agent在规划时检索。技能清单本身是分层的。第一层是总索引只有技能ID、简介、版本号第二层是详细定义只有Agent选中这个技能后才会加载。这样做的好处是几十个技能的总索引长度也能控制在几千个token以内不至于撑爆上下文而模型真正需要详细步骤时只加载那一条技能的完整定义信息密度和上下文成本都得到了控制。动态加载还有一个优势技能可以按版本灰度发布。我上线过A/B版本技能比如新用户欢迎邮件从模板2.0升级到3.0不用停服务直接让百分之十的用户走新技能对比一段时间的投递率、打开率再决定是否全量切换。# 技能注册中心的核心逻辑简化版 class SkillRegistry: def __init__(self): self._skills {} self._index [] def register(self, skill: SkillDefinition): if skill.id in self._skills and self._skills[skill.id].version skill.version: raise DuplicateSkillError(skill.id) self._skills[skill.id] skill self._rebuild_index() def match(self, intent: str, context: dict) - list[SkillDefinition]: candidates [s for s in self._skills.values() if s.is_visible_to(context.get(scope))] scored [(s.match_score(intent), s) for s in candidates] scored.sort(keylambda x: x[0], reverseTrue) return [s for _, s in scored[:5]]3.2 技能间的依赖与冲突处理技能不是孤岛。一个生成月度报表的技能内部可能需要调用查询销售数据聚合统计生成图表文件三个子技能。我一开始是让技能内部自己去调也就是在actions里写死调用API但后面遇到一个问题如果底层API变了所有依赖它的技能都要跟着改维护成本陡增。后来我引入了技能依赖声明机制。也就是技能A声明自己依赖技能B运行时自动检查B是否已注册、版本是否兼容并把B的调用方式和鉴权信息通过依赖注入的方式传给A。这样B升级时只需要保证接口返回格式不变A完全不用改。冲突处理就更有意思了。多个技能可能对同一个外部资源有写权限同时执行的时候可能覆盖对方的数据。我的策略是给每个技能加资源锁声明同一时刻只允许一个技能持有某个资源名的写锁。比如更新用户手机号和发送验证码这两个技能会对同一个用户资源操作但它们同时触发的概率不高用粒度比较粗的锁就够了真正高频冲突的场景再细化锁的粒度。3.3 技能状态与回退设计连续调用失败怎么办技能执行必须考虑失败后的状态。我常用的模式是状态机加回退优先级技能状态IDLE - RUNNING - SUCCEEDED \- RETRYING - SUCCEEDED \- FAILED - FALLBACK一个技能最多自动重试两次两次之间做指数退避比如第一次失败等待500毫秒第二次等待2秒。重试仍然失败就进入回退逻辑。回退逻辑取决于业务风险高低风险处理方式完全不同如果动作是给用户发一张优惠券失败后回退为记录日志标记任务失败不打扰用户。如果动作是支付扣款失败后回退为立即冻结订单通知人工客服介入保证资金和订单状态安全。回退逻辑设计的目标不是消灭失败而是把失败限制在可控范围内。这一点在技能设计初期就要想清楚不然等线上出了问题再补回退逻辑往往会漏掉很多边角情况。4. 实践环节从零配置一套可用技能库4.1 技能选型与拆分粒度怎么定我问过很多刚开始做技能化的朋友同一个问题你打算拆多少个技能有人回答三五十个有人回答两百个。我的建议很保守第一版能拆十个就不要拆二十个。技能数量翻倍维护成本和模型决策难度都会跟着涨。拆分粒度有一个判断标准同一个技能内部的步骤之间如果经常是一起执行、并且拥有相同的数据依赖那就应该合并成一个技能如果存在单独被复用的概率才适合拆开。举个例子发送订单确认邮件和发送订单发货通知都是邮件类动作但触发时机和模板完全不一样拆成两个技能没问题而更新库存和记录库存变动日志永远是成对出现的就应该合成一个更新库存并留痕技能。初期技能库我建议从核心业务闭环的五个高频动作开始用户注册后处理流程、订单状态变更通知、权限角色调整、关键数据报表生成、异常告警触达。这五类动作覆盖了大多数业务系统的骨架把这些稳定之后再逐步扩展。4.2 配置一套订单取消退款通知组合技能拿一个最常见的电商场景来完整演示配置过程。假设我要实现一个技能处理用户取消订单后自动触发退款并通知用户。先拆业务规则只有未发货的订单允许取消。取消后原路退款到账时间取决于原始支付渠道。退款触发后向用户发送通知通知里要包含预计到账时间。退款失败时生成工单交给人工处理。再把规则转成技能定义id: order.cancel_and_refund name: 订单取消并原路退款 version: 1.0.0 description: 取消一个未发货订单触发原支付渠道退款并通知用户预计到账时间。 仅用于订单状态为pending的订单已发货订单请走人工介入流程 不要调用此技能。 input: fields: - name: order_id type: string required: true description: 订单号 - name: cancel_reason type: string required: false value: preconditions: - check_order_shippable(order_id) false actions: - type: skill name: order.cancel_order args: order_id: {input.order_id} - type: skill name: payment.refund_by_channel args: order_id: {input.order_id} reason: {input.cancel_reason or 用户主动取消} - type: skill name: notification.push args: user_id: {order.cancel_order.result.user_id} template_id: refund_notice_v1 variables: - name: expected_refund_time value: {payment.refund_by_channel.result.expected_time} output: type: object fields: refund_status: string refund_no: string on_error: fallback_action: order.create_refund_ticket注意一个细节我把订单校验放在了preconditions里而不是action里。这样做的目的是尽早拦截错误调用。如果订单已经发货技能根本就不会启动模型会收到一个明确反馈技能前置条件不满足它就能转而选择人工介入流程技能。如果校验放在内部action里模型可能已经调用了取消接口才发现问题虽然接口层还会再拦一道但多了一次不必要的执行。4.3 技能调试三板斧离线模拟、灰度观测、错误归因技能写完怎么验证我从来不会直接扔到线上让模型随便调用。流程分三步第一步是离线模拟。准备十几组典型的输入样本包括正常输入、边界输入、错误输入直接驱动技能执行框架不经过模型规划层纯看技能内部动作逻辑是否正确执行、返回结构是否正常。这一步能发现百分之七八十的基础错误。第二步是灰度观测。让技能在真实Agent系统里运行但只放量给内部测试账号和低风险用户。这里重点观察两件事模型是否能在需要时准确选中这个技能选中之后执行过程和返回格式是否稳健。这个阶段大概跑一两天积累数据样本。第三步是错误归因。灰度期间出现的每一条失败记录都要区分是模型选型错误该调用没调用或不该调用调用了还是技能内部执行错误。两类问题的修复策略完全不同前者要改描述和索引策略后者要查代码逻辑和外部依赖。5. 测试与可观测性技能这套东西最容易被忽视的一环5.1 技能级测试不只看准确率还要看稳定性技能化之后测试对象从整个Agent下沉到了单个技能加上一小段规划逻辑。这一下沉让测试变得更有可操作性了。我做了一套技能回归测试集每个技能对应若干条基准用例。每次技能描述、校验规则或者依赖的上游接口有变更时都要跑一遍全量回归。基准用例的预期结果不是写死的返回值而是一组约束条件。比如退款技能的预期是返回的refund_status是success或failed、如果success则refund_no格式匹配、如果failed则必须额外生成一张工单。用约束代替死值既保证结果可控又能容忍合法范围内的变化。准确率之外还要看稳定性。某些技能在相同输入下应该尽量返回一致的结果。模型非确定性会带来波动但只要输出结构稳定、核心字段值在业务允许范围内变化就算合格。我把测试报告做成了一张趋势表观察每次迭代后技能指标的波动方便及时发现问题。5.2 运行时观测每个技能都该有埋点技能上线后观测是必需项。至少记录四类数据调用量按技能ID、触发来源统计调用频率。成功率按技能ID统计执行成功、失败、超时、回退的次数。延迟拆成决策延迟模型匹配耗时、执行延迟技能内部动作耗时。参数分布记录实际入参值分布能发现模型在传参时的一些隐性偏好比如某些字段总是被填一个默认值。我遇到过比较奇葩的一个问题某个技能的成功率一直徘徊在95%左右看日志找不到明确报错最后查参数分布才发现模型经常把用户ID的时区后缀当成字符串拼进去。这种问题如果不看参数分布几乎不可能定位。5.3 效果护栏确保障碍技能不会被绕过技能体系的优势是收敛了Agent的行为空间但真要保证行为边界不出格还需要在运行时加护栏。我会在Agent执行循环里嵌入三层护栏。第一层是技能可见性——模型只能看到当前用户、当前场景下有权限的技能列表其他技能对它完全不可见。第二层是输入校验——主要是前面说过的格式和前置条件。第三层是结果审查——技能返回的结果在发送给用户输出或写入业务库之前再做一次规则校验比如退款金额不得超过订单实付金额通知次数每天不得超过N次。这三层护栏加下来Agent能做激进操作的空间基本被压到了最低。6. 常见问题与排查技巧实录这节内容全部来自我自己的踩坑记录。每一条都对应过一次真实的线上问题。6.1 模型总是不选那个正确的技能现象用户说我要取消订单Agent却调用了一个定时发货提醒技能答非所问。排查路径先看技能描述和用户意图的语义关联。多数情况是描述写得含糊比如取消订单技能描述里用了大量退款词而定时发货提醒描述里出现了订单状态变化通知用户那句话里包含的取消信号可能跟状态变化通知在某些Embedding模型里距离更近。解决方式把两个技能描述里的重叠核心词做了互斥声明。在取消订单技能描述里明确写不用于通知/提醒类场景在定时发货提醒里明确写不处理任何用户主动发起的取消请求。模型决策的准确率立刻有了改善。6.2 技能执行成功但整体结果不符合预期现象技能内部每个动作都返回了成功但用户收到了错误的邮件内容比如模板变量没有被替换成功。排查路径问题出在动作之间的数据传递。技能执行框架在传递前一个动作的结果给后一个动作时我最初用的是按变量名自动匹配的方式但上游API返回的nickname字段名和下游模板期望的name变量名对不上数据就丢失了模板渲染了一串空值。解决方式把技能定义中动作间的数据映射改为显式传递明确写出source字段和target变量不依赖自动匹配。这个改动看起来繁琐却把数据传递类错误降到了接近零的水平。6.3 上下文长度快速膨胀怎么处理现象Agent运行一段时间后反应变慢token消耗飙升。排查路径看技能调用链路的反馈信息。我发现每个技能执行完返回给模型的结果都包含了完整日志其中大部分信息对决策没有帮助但白白占了上下文。解决方式为技能新增一个output摘要策略。默认情况下技能只向模型返回结构化的核心结果字段完整业务日志进入存储系统不进入对话上下文。模型的输入长度一夜之间降了差不多40%响应速度和选择准确率同时改善。7. 技能体系的演进方向从静态配置到动态自适应技能体系目前最成熟的模样是静态定义、动态选择即技能包定义好后基本不变模型在运行时从库存里选。但在实际使用中我发现有些技能被反复调用后参数分布和调用频率会发生漂移比如某类用户请求的比例大幅上升既有技能描述可能已经不完全匹配当前的实际使用模式。接下来我打算尝试的方向有两个一个是技能描述自更新根据历史调用样本自动抽取高频意图片段小步更新描述文本并做回归验证另一个是技能自动编排让多个基础技能按模板组合成高阶技能而不是每次都由模型从头规划一整条链路。说到底Agent要变得更可靠真正应该沉淀的就是这套以技能为核心的能力组织方式。这不只是工程优化更是AI应用从会聊天迈向能干活的关键一步。