1. 引言从“能做”到“会做”Agent差的就是这一层薄薄的技能做AI Agent越久越会发现一个扎心的事实让大模型“知道”一件事很容易让它“办成”一件事很难。模型可以信手拈来地写出预定API的调用格式但真让它去查库存、发工单、操作后台系统时十次里可能翻车八次。问题几乎从来不在模型能力上而在于我们交付给Agent的“技能”不够靠谱。所谓agent-skills简单说就是给Agent设计、封装、组织和调度的一套可复用动作能力集合。它比单一工具调用高一个层次比完整工作流低一个层次介于“模型会用工具”和“模型会干活”之间。这两年大家在Agent落地上踩过的坑十有八九不是卡在提示词而是卡在技能体系的缺失——工具一堆、任务照样跑不通就是因为中间的技能层没有做好。这篇内容适合正在构建Agent应用、准备把原型推向生产环境、或者被工具调用稳定性折磨得头疼的团队。我会把技能设计、接口定义、注册调度、调优排错这几个环节逐个拆开讲清楚每个设计背后的取舍也把我实际踩过的一些坑直接摆出来。2. Agent技能体系为什么工具越多反而越不干活2.1 工具与任务的断层技能层到底解决什么问题我们先做个思想实验。给你两个东西一个工具箱一堆说明书。现在让你去修一台空调。你会发现知道螺丝刀怎么用、也知道说明书上写了“拆开面板、检查电容”但你依然不会干——因为缺少一步把工具和动作组合成“拆空调”这个具体技能的过程。Agent也是同样的逻辑。你给模型注册了50个工具函数每一个都写清楚了参数和用途模型依然会在真正执行任务时搞错。举个我自己项目里遇到的例子一个客服Agent明明有“查询订单”“修改地址”“申请退款”三个工具模型在处理“我买的东西寄错了给我换个地址”这个请求时居然先调了退款接口把订单直接给退了。工具没有错参数没有错错的是模型不知道“修改地址”这个技能应该匹配什么意图、按什么顺序执行、以及什么情况下不能动退款。技能层解决的就是这个问题。它把“能用工具”和“会执行任务”之间的断层补上通过一组结构化的能力包告诉Agent什么时候可以用什么动作组合、每一步要满足什么前置条件、失败之后怎么办。2.2 工具、技能、工作流的边界怎么划很多团队在概念上就混在一起导致设计出来的东西既不是工具也不是流程四不像。我的划分标准很简单看执行单元的粒度工具Tool单个原子操作对应一个API、一个函数输入输出明确。比如“调用天气接口”没有状态不需要记忆。技能Skill围绕一个目标场景封装的一组动作序列与决策规则内部可以包含工具调用和分支判断。比如“处理订单地址变更”里面有校验、查单、调API、结果确认四个步骤。工作流Workflow跨多技能、多系统、有人为审批或状态流转的流程编排。比如“售后全流程”包含地址变更、退款审核、物流跟踪多个技能并且涉及人机协同。对大多数Agent场景来说工具太碎、工作流太重技能是性价比最高的封装粒度。它既是模型可理解的指令集又是开发可维护的代码单元还能沉淀复用。3. 技能如何设计与实现从写一个技能开始3.1 技能定义的结构化拆解我在项目里把每个技能定义成四块意图描述intent给大模型看的一句话说清楚这个技能解决什么问题、在什么场景下触发。触发条件triggers哪些用户请求关键词、哪些前置状态满足时才允许激活该技能。执行步骤steps有序的操作列表步骤之间可能有条件跳转。完成判定success criteria怎样算执行成功怎样算失败要回滚或上报。这四块少一块都会出问题。特别是触发条件最容易忽略。你给Agent配了“查询余额”技能却没说明“仅当用户身份为已登录会员时才可调用”它就会在访客身份下硬调撞出个鉴权错误还要编个理由糊弄过去。下面是我常用的一种技能描述模板用YAML写的skill: name: order_address_update description: 修改订单收货地址。适用于用户要求更换收货人、手机号或详细地址的场景。 version: 1.0.0 triggers: - 用户表达地址变更意愿改地址、换收货信息、重新填地址等 - 当前订单状态必须为未发货或待发货 steps: - call_tool: verify_order_status args: order_id: $order_id check: - status in [PENDING_SHIPMENT] - call_tool: get_user_identity check: - user.verified true - call_tool: update_delivery_address args: order_id: $order_id address: $new_address - call_tool: notify_address_change success_criteria: - update_delivery_address 返回成功 - 用户侧可见收货地址已变化 fallback: - 任一校验不通过则终止返回可解释的原因文本这个文件格式实际上既给模型看也给程序用。模型通过description与triggers理解何时用程序通过steps来校验与追踪。两方共用一套定义是避免“模型自创流程”的关键手段。3.2 参数流转与上下文绑定第一个最容易翻车的地方技能内部步骤之间的参数传递是集成时最容易被低估的问题。大模型不会像代码函数那样老老实实把变量传下去它经常“脑补”参数。比如更新地址这个技能模型可能自己造一个user_id字段把登录用户的ID填错了。我的应对经验是两层第一层运行层做参数锁定。技能定义里每个步骤的参数值来源只允许三种对话中用户明确给出的、前置步骤的返回值、外部会话上下文存储的字段。除此之外的任何来源都视为非法。实现上就是在技能执行引擎里加一个参数校验器模型给的参数只能从白名单字段中取。第二层提示层做显式约束。在Agent的系统提示里写明你可以选择技能但不能自行发明传递给技能参数的值。所有参数必须来自用户原话或已确认信息。这条提示看起来简单实际能减少一半以上的参数幻觉问题。3.3 技能的失败处理回滚不是可选项很多初版Agent技能根本没有失败处理。遇到接口超时、返回格式不对、参数校验不过就直接把原始错误抛给用户。用户看到的是“系统异常请稍后再试”这体验不但差而且让整个Agent可信度崩塌。我给每个技能都标配了三段式失败处理重试对网络类错误或超时最多重试两次间隔用指数退避。重试前重新从上下文读取参数防止第一次调用时参数被篡改。降级核心接口失败时切换同语义的备用方案。比如主API挂了走消息队列异步上报或者在提示里引导用户转人工。宣告以上都不行输出一个“可解释的失败结果”说明是哪个步骤、什么原因导致的失败同时给出建议。绝不允许Agent编造一个成功。这套机制之后生产环境的技能失败率从11%降到了2%左右。对比之下牺牲的是多几百毫秒延迟换来的是用户信任度的大幅提升这笔账非常划算。4. 技能库的构建与调度别把所有技能平铺一锅炖4.1 技能注册中心与命名规范当你的技能数量超过20个之后就会发现另一个问题模型开始把A技能当成B技能用了。原因是技能名和描述太相似或者命名没有层级、没有区分度。我见过一个团队技能库里有create_order、create_ticket、create_invoice三个技能描述都写着“创建一个新的XX”结果模型选的时候频繁混淆。解决方式不是改提示词而是要建立一套技能注册规范动词对象的命名方式动词必须动作明确避免handle、process这种尿不尽式说法。描述信息里强调差异点写清楚“和XX技能的区别是什么”。版本化管理每个技能是一个独立包修改接口必须升版本不能原地改。技能间显式声明冲突关系比如执行了refund_order之后就不能执行change_address。技能注册中心说白了就是一个带元数据的管理仓库每加一个技能都必须回答三个问题这个技能解决什么场景它依赖哪些前置技能或工具它和已有技能是否冲突。4.2 模型如何选择技能召回、重排与校验三步法把技能全部塞进上下文让模型自己去挑在一两个技能时没问题到二十个之后就废了。大模型上下文是有限的技能描述太多会稀释注意力。我在生产里用的是“召回-重排-校验”三段式。召回用用户的当前请求和技能名、描述做一次轻量语义匹配先从技能库里捞出Top5候选技能。这一步可以用Embedding相似度也完全可以靠模型自己选择我给它塞进上下文的那批技能。重排让模型从Top5里挑一个或两个并且输出选择的理由。注意我要求模型必须给理由哪怕是一句“因为用户提到了退款且订单状态已关闭”。给理由不是为了解释给用户听而是为了在下一层校验时用。校验程序检查模型选出的技能是否有触发冲突、是否前置条件满足、用户的原始诉求是否确实与该技能匹配。校验不过就拒绝执行并且把拒绝原因返回给模型让它重新选择。这个环节救回来很多次本该出的生产事故。4.3 技能之间的编排与互斥流程技能调度上很多场景需要编排但我不推荐一开始就用重型工作流引擎。我的经验是用户的语言天然暗示了技能链路“我要退货然后重新下单”就是一个天然的链路先用协议明确表达再用路由来执行。具体做法是引入一个轻量级的“技能路由”它本身不做复杂流程建模只做三件事识别用户请求中包含的多个技能意图、判断技能之间的先后依赖、把多技能执行翻译成一个有序列表交给Agent。这里贴一个技能路由的伪代码async def route_skills(query: str, context: dict): intents await detect_intents(query) # 返回 [refund, create_order] if refund in intents and create_order in intents: # 强制顺序先退款再下单且状态要连接 force_order(intents, [refund, create_order]) for i, intent in enumerate(intents): skill get_skill_by_intent(intent) if skill.requires_previous_done and not context.get(previous_done): return SkillRouteError(f{skill.name} requires previous step) result await execute_skill(skill, context) context[previous_done] True return context另外互斥设计很重要。有些技能不能连续执行比如“关闭订单”和“新建工单”一旦先关了订单工单里的订单号就成了无效引用。互斥规则我会直接配置在注册中心里在执行前检查一次防止模型抽风把互斥的技能编排成一条链。5. 让技能真正好用评估、反馈与持续调优5.1 技能质量怎么评估三个指标技能上线半年后我总结出三个值得盯的核心指标比准确率实在得多触发准确率被调用的次数里真正适合该技能的场景占比。这个指标低说明技能描述有歧义或者召回阶段就有问题。执行成功率调用后顺利走完所有步骤并满足success_criteria的占比。低于90%的技能不要进入主干流程。回退率Agent选该技能后被校验拦截的比例以及被用户在后续对话中纠正的比例。回退率高意味着技能边界设计不清。这三个指标不够每个技能上线前应该有一批人工标记的测试用例。我用的是行为树风格的测试集类似这样测试用例: “用户要求把收货电话改成138xxxx” 断言: 调用 skillorder_address_update, 参数 phone138xxxx 期望: 执行成功, 返回“已更新”这类测试集可以自动化回归每次更新技能定义就先跑一遍防止新版本把旧场景搞坏。没有回归测试的技能库迟早会在某个凌晨四点的版本更新后集体崩溃。5.2 反馈闭环用户纠正就是最好的训练数据一个常被忽视的信号是用户纠偏。用户对Agent说“我不是要改地址我是要取消订单”这句话比任何评测集都金贵。我把这类反馈全都记录下来分析方式很简单触发用户纠偏前Agent调了哪个技能纠偏后用户期望的是哪个技能。将这种配对数据沉淀下来用来调整技能库的召回与描述。长线看这些反馈还能微调模型但短期内最高收益的做法是改技能描述。很多时候模型选错技能就是因为描述里没有覆盖用户这个说法。比如用户说“我不要这个了”他其实是想取消订单。你在cancel_order的triggers里写上“我不要了”这个口语说法立刻就能纠正一大片误触发。5.3 动态技能开关灰度发布与熔断技能并不是越多越好。生产环境里我坚持每个新技能都要有独立开关。所谓开关不只是一键下线而是一套灰度机制技能先在影子模式跑一周结果只记录不执行。切5%流量观察触发准确率和回退率。指标达标后放量到50%再观察执行成功率。全部通过才进主干流程。熔断规则也很简单粗暴如果某技能在5分钟内连续失败超过一定阈值自动从可用列表里摘除模型将看不到它。这能防止某个上游接口故障时Agent还在反复调用然后给用户抛出连环错误。我有一次就是靠这个熔断机制在外部短信服务宕机时保住了整个订单系统的不至于被异常流量拖垮。6. 常见问题与排错手册6.1 模型就是不用我定义的技能怎么办先别急着加提示词。检查一下技能的description和triggers有没有出现模型根本理解不了的抽象词。比如你写“处理订单状态流转”模型不知道这是什么你写“订单状态从待支付变为已支付”模型立刻明白。还有一种情况是模型用了技能但技能不在召回名单里。我刚跑通那会儿天天遇到这个后来发现是Embedding召回时把order_address_update这样的长名相似度过低导致召回阶段就被过滤掉了。解决方式是给技能再加一组alises别名比如改地址、换收货人并且提高召回阈值优先保证召回率。6.2 技能执行时参数被模型乱改怎么办这个在前面提到过最有效的是在运行时做参数锁定而不是在提示词里一遍遍求模型“不要乱改”。原理很简单模型生成的是文本不是结构化指令。你能控制的是把它生成的文本解析成参数时做一层强校验。凡是不在可信来源里的参数全部打回。不要怕性能开销这里省一步后面就少一次生产事故。6.3 多技能执行顺序错乱我先退款又下单了这是技能编排最常见的错误根源是模型一次会话里要处理多个意图时自己决定了一个不合理的顺序。上面提到路由里强制排序能解决大部分问题。另一个是给技能定义加上postcondition字段前置技能执行完要显式把状态写入上下文后续技能再从这个状态做校验没有对应状态前直接拒绝执行。6.4 技能多了之后模型越来越“笨”当技能库膨胀到上百个描述占的上下文越来越多模型的主任务反而被干扰了。这时要做两件事一是对技能做分组比如“订单域”“用户域”“支付域”每次请求先判断域再拉对应技能集二是把不常用的技能从在线上下文全部移除只留一个“技能索引”给模型看模型确定要用了再把具体定义动态加载进来。这套“懒加载”模式极大的缓解了技能库膨胀带来的注意力稀释。7. 收尾一点个人体会做了这么久的Agent技能系统我最大的感悟是技能层不是一个可有可无的中间件而是Agent应用能不能从demo走向稳定生产的分界线。模型选工具、生成参数的能力会一代比一代强但技能这个层级的抽象不会消失反而会越来越重要——因为它是“模型世界”和“业务系统”之间唯一的契约层。如果你正在开始构建Agent技能库我的建议是别急着追求技能数量先把你最核心的三五个流程做成高质量技能跑通评估、灰度、熔断这套闭环再谈扩容。我在现场踩过太多“一百个工具、一个都跑不稳”的坑这个教训希望你不用再踩一遍。