最近半年我明显感觉圈子里聊 Agent 的方式变了。去年大家还在比谁的 Agent 能多轮对话不跑偏今年已经开始讨论这个 Agent 拥有哪些技能、技能怎么编排、技能效果怎么评估——一个叫agent-skills的话题在讨论中反复出现。说白了现在做 Agent 已经不再是一个大模型硬撑所有任务的阶段了。你让一个模型自己悟出怎么查数据库、怎么写代码、怎么操作浏览器既不靠谱又难迭代。更务实的做法是把 Agent 的能力拆成一个一个可以被独立开发、独立测试、独立复用的“技能”模块然后像拼乐高一样把它们组装成一个完整的智能体系统。这篇文章我就围绕agent-skills这个方向把我最近踩过的坑、总结出的设计原则、以及一套可以直接落地的搭建方案完整拆给你看。不管你是刚接触 Agent 开发的新手还是已经在生产环境里被各种边界问题折磨过几轮的工程师这篇文章都能给你一些可复用的思路。1. 为什么 Agent 开始强调技能而不是能力1.1 从单模型到技能组合的演进逻辑先聊一个转变。去年我接手一个内部客服项目时第一个版本的做法非常简单把用户问题、相关文档、历史工单全部塞进上下文让一个大模型直接生成回答。初期效果还不错因为问题类型相对集中。但一到多业务线、多场景之后就崩了——不同业务线的术语体系不一样回答风格要求不一样连可用的外部工具都不一样。每次加一个新业务线整个 Prompt 都要重写一遍维护成本直线上升。后来我换了一个思路不要求一个模型什么都会而是把能力拆成最小单元。比如查订单状态计算运费差价生成退款审批单判断用户情绪是否需要升级人工……每一个最小单元就是一个技能。每个技能拥有自己独立的 Prompt、独立的工具配置、独立的评测用例。Agent 要做的事情从回答所有问题变成了根据当前上下文挑选并执行合适的技能。这个转变本质上跟软件开发历史上的单体应用拆微服务是同构的单体大模型不是不能工作而是当业务复杂度上去之后一个模型内部什么都耦合你改一个功能就要重新全量评测风险不可控。技能化之后每一个技能的改动都可以独立验证、独立灰度、独立回滚。1.2 技能化带来的工程收益与复杂度代价技能化的好处非常直观可组合同样一个查天气技能既可以放在旅行规划 Agent 里也可以放在日程管理 Agent 里不用重写逻辑。可单独优化某个技能效果差只需要调整那个技能内部的 Prompt 或工具配置不会影响其他技能。可独立评测每个技能有自己的通过率和失败率指标效果好坏一目了然。可复用团队之间可以通过技能市场共享技能避免重复造轮子。但代价也很现实系统复杂度会明显上升。你多了一个技能注册中心多了一套技能路由与调度机制还多了技能之间的依赖管理问题。如果你只有三个技能这个过程不太值得但当你走到 15 个以上技能时这种复杂度付出是划算的——我自己在实际项目中体会到的临界点是 12-20 个技能。少于这个数量单体设计反而更快超过这个数量单体设计的维护成本会指数级上升技能化才开始真正发挥价值。2. 技能体系的核心组成与关键设计原则2.1 工具调用层Agent 的手从哪来技能的本质是让 Agent 在特定场景下调用特定的工具完成一个具象任务。而工具调用层就是技能的手。我的实践是用一套统一的函数调用接口Function Calling来规范化所有工具的输入输出。把每个工具封装成一个 JSON Schema描述它的名称、参数、返回值、错误码然后让模型根据 Schema 决定要不要调用、传什么参数。这个设计的好处是新增一个工具只需要注册一个 Schema不需要改任何核心代码。举个我实际用过的 Schema 例子{ name: query_order_status, description: 根据订单号查询某个订单的当前处理状态, parameters: { type: object, properties: { order_id: { type: string, description: 订单号例如 SO20250110001 } }, required: [order_id] } }这里有两个关键点容易被忽略一是 description 要写得足够具体包括参数格式的例子因为模型是靠描述来理解何时调用的二是 required 字段务必明确不然后续参数幻觉问题会让你排查到怀疑人生。2.2 记忆系统技能执行的上下文底座很多人在设计技能时只关注这个技能怎么执行却忽略了一个前提——技能需要上下文。比如查订单状态这个技能本身只需要订单号但 Agent 怎么知道用户的订单号是多少可能是用户刚说的可能是历史会话里提到的也可能是通过某个前置技能从数据库里查出来的。因此一个健壮的技能体系必须搭配一套记忆系统。我把它分成三层短期工作记忆指当前对话窗口里的信息。实现上就是你的上下文管理模块负责把最近几轮的用户输入、Agent 内部推理摘要、技能执行结果做有效的组织和压缩。长期语义记忆指跨会话的信息通常用向量数据库存储。例如用户上次在哪个城市、习惯用哪种支付方式、历史投诉记录等。结构化事实记忆指用户档案、业务字典、权限标签这类强结构信息我一般单独存放在一个可快速查询的 KV 存储中不走向量检索。记忆系统的设计直接决定技能的准头。我踩过一个很典型的坑技能本身写得很好但因为没有长期记忆支撑用户第二次进线时 Agent 把所有信息都忘了不得不反复追问用户体验极差。加了一层向量记忆之后重复澄清率下降了接近一半。2.3 规划与拆解技能编排的灵魂有了单个技能下一步就是让 Agent 知道什么时候用哪个技能、多个技能怎么串联。这是规划层要做的事。当前主流的规划范式有两种。一种是 ReAct 式的边想边做模型在每一步根据当前观察决定下一步动作灵活但容易在复杂任务中迷失方向。另一种是 Plan-and-Execute 式的先计划后执行模型先拆出一个多步计划然后再逐步执行每一步。我自己的取舍是任务链路短少于 3 步且状态空间小的情况下用 ReAct 式链路长、状态多的场景必须用 Plan-and-Execute 式否则中期很容易跑偏。举一个实际的例子一个任务帮用户办理商品退货并申请运费补偿我拆成了 5 步调用verify_order验证订单是否在可退期内调用check_item_status检查商品是否已签收调用create_return_order创建退货单调用calculate_refund_amount计算退款金额含运费补贴规则调用notify_user发送结果通知前 4 步之间有严格的依赖关系——第 3 步依赖第 1、2 步的结果第 4 步依赖第 3 步生成的退货单号。如果模型不先规划而直接硬跳很容易出现参数无法补全、流程被跳过等问题。所以我给这套任务内置了一张技能依赖图每次执行时先做拓扑排序确保每一步的前置条件都满足。2.4 自我反思与纠错技能闭环的最后一环一个技能执行失败后怎么办很多初版 Agent 就直接把错误信息抛给用户这体验太糟糕了。一个成熟的技能体系必须有自我反思与纠错机制。我在实际项目里加了一层轻量的反思模块每次技能返回异常后Agent 会先做一次失败归因判断错误类型。错误类型大致有这几类错误类型典型表现处理策略参数缺失模型没传必填参数根据上下文补充后重试一次参数幻觉模型传了不存在的参数值用 Schema 校验拦截重新生成工具异常上游接口报错、超时降级到备用工具或更换方案业务规则冲突订单状态不允许退货终止流程转为人工接管推理错误模型误判了用户意图回溯上下文重新做意图判断这层反思逻辑跑通之后我那个客服 Agent 的技能执行成功率从 68% 提升到了 84%。注意这里不需要做太重的复杂推理链路只需要一个轻量级的失败分析和重试判断即可——太重的话会显著拉长单次请求的响应时间。3. 从零搭建一个技能化 Agent选型与实操3.1 技术栈选型为什么我选了这个组合先交代一下我的技术选型再解释为什么这么选。我采用的组合是Python 后端 一个通用 LLM 框架做对话编排 一套自研的技能注册中心和路由调度器 Redis 做短期会话缓存 一个向量数据库做长期记忆存储。LLM 的模型层面我用了一个支持 Function Calling 的通用模型没有绑定某个封闭平台的专有接口方便后续替换。为什么这样选原因有三点第一Python 在 AI 生态里的工具链最完整无论是函数调用解析、向量检索还是数据处理都有成熟的库可以让我把精力花在技能逻辑本身而不是基础设施上。第二通用 LLM 框架解决的是对话编排这件事它帮你处理好会话管理、工具调用循环等基础能力但技能怎么组织、怎么路由、怎么评测框架层并没有标准答案所以我保留自研的空间。第三Redis 和向量数据库都是经过大量生产验证的组件稳定性优先级高。如果你是从零开始我不建议一开始就用重型的 Agent 编排框架。先手写一套轻量的调用循环理解每一层在干什么之后再迁到成熟框架上会更扎实。3.2 技能注册与调用的最小实现一个技能注册中心需要管理三个东西技能元信息、技能实现、技能的依赖关系。元信息描述这个技能是什么、何时该被调用、参数长什么样技能实现是实际执行逻辑的代码依赖关系用于规划调度。我习惯用一份统一的技能描述文件来管理元信息格式是 Markdown 加 JSON Front Matter像这样--- name: order_issue_handler description: 处理订单相关的退货、退款、物流查询、售后申请等全链路问题 primary_triggers: [退货, 退款, 换货, 订单异常, 售后] requires_skills: [verify_order, check_item_status, create_return_order] timeout_ms: 15000 ---这份描述文件会被加载到技能注册中心然后通过路由调度器在运行时被检索。技能实现的代码无需关心注册逻辑只需实现一个统一的接口class BaseSkill: async def execute(self, context: SkillContext) - SkillResult: raise NotImplementedError这样一个最小闭环就出来了用户发起问题 - 对话编排层做意图识别 - 路由调度器匹配技能 - 技能执行 - 结果返回给模型 - 模型组织最终回答。3.3 让 Agent 学会挑技能路由与匹配策略技能多了之后最核心的问题变成给了一段用户输入怎么挑出正确的技能我的方案是双通道匹配第一通道是关键词和内嵌在技能描述里的触发词精确匹配很轻、很快能覆盖大多数高频场景第二通道是语义向量检索把用户输入和技能描述各自编码成向量用相似度作为补充召回依据。最后把两个通道的结果合并按置信度排序取 Top 1 作为选中技能Top 3 作为候选让模型做最终裁决。这里的细节很关键不要把路由完全交给模型自由选择。模型自由选择在 10 个技能以内还可以超过之后就经常出现凭感觉选一个貌似合理的技能而不是选择真正正确的技能。通过对候选列表做约束把自由选择变成有范围的选择准确率会高很多。我实际跑过一组对比数据纯模型自由选择技能10 个技能时准确率约 82%20 个技能时下降到 65%而用双通道召回 模型在候选里裁决的方案20 个技能时准确率还能维持在 85% 左右。3.4 多技能协作的编排示例我们用一个稍复杂的场景完整演示多技能协作的编排逻辑。场景用户说我刚买的那双鞋尺码小了想换一双 42 码的顺便帮我看下换货后能不能用优惠券抵扣运费。这个请求表面上是换货加运费优惠咨询但仔细拆解实际涉及 4 项技能query_order定位用户刚买的那双鞋对应的订单check_exchange_policy确认该商品是否在换货期内、是否支持改尺码get_coupon_balance查询用户是否有可用的运费优惠券create_exchange_request根据前面三步的结果生成换货申请我的编排器先执行规划生成步骤图首先并行执行第 1 和第 3 步它们之间无依赖然后执行第 2 步依赖第 1 步拿到的订单号最后执行第 4 步依赖 1、2、3 的结果。如果第 2 步发现商品不支持换尺码则整个流程直接终止转到人工客服。这个编排过程看起来像是想当然但真正上线之后你会发现模型经常漏拆步骤或者把第 2 步和第 4 步合并成一步执行结果参数缺失。关键解法是给编排器加一个必选技能校验——在第 4 步执行前检查 1/2/3 的结果是否都已经存在于上下文里不满足就强制补跑缺失步骤。我建议你在做多技能编排时把这个校验机制当作标配。4. 实测中的意外情况与避坑记录4.1 工具参数幻觉Agent 传错参数的根因与修复这是我遇到的最高频的问题没有之一。现象是技能方法名选对了但传入的参数跟用户描述完全不匹配。比如用户说帮我查一下上周买的那个耳机的订单模型却给query_order_status传了order_id 上周买的那个耳机而不是在上下文里查找真正的订单号。根因是模型没有参数物化的能力——它不会自动把自然语言中隐含的信息映射成结构化的参数值。它把用户在句子里的原始文本直接当成了参数值。我的修复方案是分两步第一步在前置上下文里显式放入一个实体抽取步骤把用户的订单号、商品名、金额等实体先抽取成结构化的槽位再让技能调用器从槽位中取值。第二步在技能执行前加一道 JSON Schema 校验拦截明显不符合格式的参数——比如order_id不符合SO开头加数字的格式时直接判断为幻觉参数触发重试。这两步做完之后参数幻觉导致的失败率从 12% 降到了 3% 左右。但注意3% 仍然客观存在线上必须有兜底机制不能让模型直接把这个报错暴露给用户。4.2 长上下文下的技能遗忘另一个让我头疼的问题是多轮对话进行到中后段Agent 会开始忘记自己已经执行过的技能及其结果导致重复执行或者引用过期数据。典型的错误场景是用户在第 5 轮问那我刚才查到的那个订单能退吗Agent 此时应该直接引用第 2 轮查到的订单号和当前状态继续推理但它却重新发起了一次查询拿到了一模一样的数据还多花了时间。这个问题的本质是上下文压缩做得不够好。我在实践中摸索出一套方案每执行完一个技能就把技能名 关键输出摘要以结构化形式写回短期记忆的显式区域并在后续 Prompt 中始终保留这个区域。相当于给 Agent 做了一个“工作台日志”让它随时知道前面发生过什么。对于更长链路的任务还可以在每步推理时附带当前步骤号的进度状态。经过这个改造后重复执行技能的次数明显减少响应时间下降了 20% 左右同时减少了无用 API 调用节省了一部分成本。4.3 并发调用时的竞态问题当多个技能需要并行执行时竞态问题容易冒出来。最典型的案例是两个技能同时尝试修改同一个用户的优惠券抵扣状态结果后执行的那个把先执行的那个状态覆盖掉了最终用户被错误地扣了两次运费。这个问题在初版架构中非常隐蔽因为单看每个技能的单元测试都是通过的。后来我在并发控制层加了一个基于业务键的分布式锁以用户 ID 加资源类型作为锁粒度。比如user:123456:coupon_state在任意时刻只允许一个技能获取写锁。锁的持有时间设置了 10 秒超时避免某个技能卡住导致死锁。加完锁之后这类竞态问题再没出现过。另外一个经验是尽量不要让两个技能同时写同一个业务资源能用读取-计算-合并模式就优先用让多个技能返回中间结果由一个最终技能统一落库。4.4 安全边界权限控制与能力约束技能化的另一面是攻击面扩大了。以前你只有模型 一套 API现在你有几十个技能每个技能都是一个潜在的风险入口。我列出三个必须处理的安全问题一是技能级权限校验。每个技能需要声明自己的最小权限范围路由调度器在调用技能前先检查当前会话的授权级别。比如query_order只允许读取本人订单create_refund需要额外的高权限标记。这块不能在技能代码里做必须在调度层统一拦截否则很容易出现漏判。二是技能暴露的敏感数据脱敏。技能返回给模型的结果里手机号、银行卡号、地址等敏感字段必须先做脱敏处理再进入模型上下文。模型本身不需要知道完整的敏感信息它只需要知道是否有这个信息、是否验证通过。三是工具调用的频率与限额控制。一个技能不应该被无限次调用。我做了双层限额单会话内同一技能的调用次数上限以及全局的每用户每分钟调用频率限制。防止恶意用户通过构造多轮对话反复触发高成本的技能调用把你的 API 预算打爆。这些安全措施不会提升技能的智能程度但没有它们技能体系根本走不到生产环境。5. 技能效果的测评与持续迭代5.1 不是所有技能都该进生产环境技能化一个容易被忽略的好处是你可以非常方便地对单个技能做灰度评估而不是等到全链路集成后才发现问题。我在每个技能进入生产环境之前会要求它通过三道关卡第一道是单技能评测。用 100 条以上的真实历史问题构造测试集要求技能单独执行时达到设定的指标线比如关键字段提取准确率不低于 95%。第二道是链路评测。把这个技能放进真实的任务链路里用端到端的测试样例验证它不会破坏上下游其他技能的执行。第三道是影子环境验证。把一个新版本技能部署到影子环境让它处理线上真实流量的复制流量对比新旧版本的输出质量。这道流程看起来繁琐但确实能把大多数问题挡在生产环境之外。我接手项目早期因为省掉第二道关卡上线了一个新技能结果它和旧的订单查询技能在路由上产生冲突导致有 20% 的流量被错误路由花了整整两天才排查清楚。5.2 评测集设计与回归机制评测集的搭建也有讲究。第一个教训是不能只用标准示例评测必须加入边缘骚扰样本。比如针对查单技能你要准备好以下类型的测试输入用户给了完整且正确的订单号用户只给了模糊的购买时间描述用户给的订单号不存在用户同时问了两个订单但想做不同操作用户使用了错别字、口语化表达第二个教训是评测集必须能沉淀并且每次技能迭代后做回归。我维护一个技能回归样例库假设一个技能需要修改内部 Prompt修改后第一件事就是跑全量回归对比通过率有没有回退。这个机制保证了你不会出现修好一个技能、弄坏另一个技能的连锁反应。5.3 从日志里挖技能短板的方法最后说一个非常实操的环节怎么用线上日志持续发现技能的短板。我的做法是给每个技能的执行结果打上标签分为success、retry_success、fallback_success、failed、escalated_to_human五档。然后每天对failed和escalated_to_human的样本做一次人工抽检按失败原因聚类。常见的聚类结果一般有几类一类是路由匹配错误——用户意图明明存在对应技能但调度器没有匹配上一类是技能内部逻辑问题——比如某业务规则变更后技能没有同步更新还有一类是上游数据质量问题——比如订单状态字段在某些历史订单中为空导致技能判断失误。针对每一类处理方式完全不同。路由匹配错误需要优化召回逻辑或技能描述技能内部逻辑问题直接修 Prompt 或业务规则上游数据质量问题则需要和技术平台沟通做数据清洗。这个日志-聚类-修复-回归的闭环我每周跑一次每次都能发现一到两个可以优化的点迭代速度非常可观。回到agent-skills这个主题本身。我个人的核心体会是技能化不是一个新框架也不是一个新模型而是一种工程组织方式。它把原本混沌的 Agent 开发过程拆成了可以独立迭代的小部件让效果优化从玄学变成了可跟踪、可评测、可回滚的工程实践。如果你现在的 Agent 项目正处于一个 Prompt 满天飞、改一处崩三处的阶段我建议你参考这篇文章里的思路尝试做一次技能化拆分。先从 5 个技能开始跑通闭环再逐步扩展。只要路由、记忆、编排这三个底座稳住了后面的路就会越走越顺。
