1. 为什么Agent需要一套技能体系1.1 从装进提示词到装进技能库的转变先说个很直观的现象。早期大家做Agent基本都是把工具说明、调用方式、返回格式一股脑塞进系统提示词然后让大模型自己看着办。这种做法在小规模Demo里确实能跑通但一旦业务场景复杂起来比如要做多轮客服、要操作多个内部系统、要处理几十种任务类型提示词里塞的内容会迅速膨胀到离谱的程度。我见过不少团队的系统提示词动辄几千甚至上万token光是维护这段提示词就够呛更别提每次修改工具定义都要跟着改一遍。这时候你需要的不是继续往提示词里堆内容而是一套能够独立管理、按需加载、可复用、可测试的技能体系。这也是agent-skills这类思路最近特别受关注的根本原因——它把Agent的能力从模型记忆里释放出来放到了外部可维护的模块里。我理解一个Agent技能本质上就是对某一类任务处理能力的封装。它既包含模型需要知道的这个技能是干什么的、什么时候该用也包含执行层面需要的具体逻辑、依赖、参数定义和返回规范。说得通俗一点如果把大模型比作一个能力很强但记忆力有限的新员工技能库就是一个按需翻阅的标准化操作手册而不是把整本手册背在脑子里。1.2 技能体系到底解决了什么核心问题我总结了一下一套好的技能体系主要解决四个核心问题。第一是上下文长度与调用精准度的矛盾。模型上下文窗口虽然在不断变大但塞得越满注意力分散越严重对单次调用的理解精度反而会下降。技能体系可以做到按需注入——模型先判断该用哪个技能系统再把对应的描述和参数schema动态加载进来而不是所有技能常驻在上下文里。第二是能力复用与产品迭代的问题。如果每次做新业务都要重新写一套工具调用逻辑那Agent的能力就永远是项目私有资产沉淀不下来。有了统一的技能描述和注册机制不同项目之间可以共享技能库新增业务只需要做技能的重新编排和组合效率高很多。第三是测试与调试的复杂度。提示词式的Agent调试起来非常痛苦因为改一句话可能影响所有任务的表现。技能模块化之后每个技能可以单独测试、单独设计验证用例甚至可以做A/B对比。我在实际项目中感受特别深未模块化之前线上问题定位基本靠猜模块化之后问题可以被精准定位到某个技能模块定位和修复的效率完全不在一个量级上。第四是权限和模型能力的安全边界。技能可以做粒度级别的权限控制什么角色能调用什么技能、技能默认是否允许操作外部系统都能在体系层面统一管控而不是靠模型自觉。如果你只是做一个小玩具Demo那确实直接用提示词就够了没必要引入技能体系的复杂度。但只要是准备上生产的项目我建议从第一天就把技能体系这个架构方向定下来。1.3 技能模块的核心要素构成一个标准化的Agent技能模块在我目前的工程实践中通常包含这么几个要素。首先是职责说明也就是这个技能做什么、不做什么接收什么类型的输入常见的使用场景是什么。这部分是给模型看的帮助它做技能选择。其次是触发条件包括显式触发和隐式触发。比如查询天气这个技能用户直接说今天北京天气怎么样是显式触发用户说帮我安排明天出差行程时Agent需要推理出可能需要查天气、查航班、查酒店等技能的组合调用这就是隐式触发。触发条件设计得好不好直接决定了Agent的调度灵敏度和误调用率。第三是调用接口即技能对外暴露的输入输出格式。配套的还有参数说明、必填和可选字段、枚举值的范围等。这里的接口设计越规范大模型做参数填充的成功率越高。第四是依赖项比如技能需要哪些环境变量、需要调用哪些外部API、有没有需要预加载的数据或模型。依赖项做得清晰技能的跨环境可迁移性就强。第五是失败反馈与扩展信息即技能执行失败时返回什么样的错误结构以及是否允许模型针对错误做重试或降级处理。这五个要素缺一不可。我接下来会在实操章节里给出一个可以直接参考的JSON结构示例。2. 设计Agent技能体系的关键思路2.1 先分清技能、工具、工作流的边界很多人在设计技能体系时遇到的第一个困惑是技能Skill、工具Tool、工作流Workflow到底有什么区别我自己的划分方式是看能力复用和组合复杂度这两个维度。单个工具是最细粒度的原子能力比如发送HTTP请求查询数据库调用某个API。技能则是围绕某一任务目标封装的能力单元它内部可能会用到多个工具并且带有一定的决策和反馈逻辑。工作流更偏重固定流程的编排比如新用户注册流程由身份校验、信息采集、权限分配三个步骤串起来流程基本固定不需要模型实时参与决策。技能处于中间层这个定位非常关键。拿做饭来类比工具是锅、铲、刀、砧板技能是红烧肉的做法工作流是今天晚餐全流程。红烧肉的做法这个技能需要用到刀、锅、调料等多个工具而执行过程有一定的步骤但又允许根据实际情况调整。在设计Agent技能时如果你发现一个技能里只包了一个API调用那它应该直接下沉为工具如果发现一个技能里写了大量固定步骤且不允许模型变通那它更像工作流。把这个边界划清楚后面就不会出现体系设计过重或过乱的问题。2.2 技能编排的三种基础模式技能体系确定之后下一个问题就是多个技能怎么组合。我在实际项目中最常用的是三种编排模式。第一种是条件路由即不同技能之间的选择关系。模型根据用户意图的判断结果把任务分配给不同的技能执行。这种模式对触发条件定义的要求很高否则容易出现两个技能边界重叠、互相抢任务的情况。第二种是串行流水线即上一个技能的输出作为下一个技能的输入。这种模式需要格外注意输出结构的稳定性因为模型生成的技能输出偶尔会格式漂移如果下游解析太严格整条流水线很容易断。我的做法是在技能间的数据传递里统一走一个中间结构并允许一定程度的字段缺失补默认值。第三种是并行扇出即一个任务同时交给多个独立技能执行最后把结果汇总。这种模式最典型的场景就是市场调研类任务比如分析竞品时同时获取价格、评价、销量三个维度的数据。并行模式需要注意技能之间的资源竞争比如共享的API配额、数据库连接池在Agent已经跑起来之后这些都会被放大。除了这三种基础模式之外比较前沿的做法是让Agent自己做动态规划模型自主决定技能的拆分和编排但这种模式对模型的推理能力要求很高也需要极其完善的容错机制。我的建议是从前三种模式开始把基础打扎实再去追求动态编排。2.3 一套可落地的技能描述规范这里给出一套我比较推荐的技术中立型技能描述结构用JSON承载不绑定具体框架。{ name: fetch_competitor_report, version: 1.3.0, description: 抓取指定竞品在目标电商平台上的价格、评价数及热销SKU信息并汇总为对比报告, scenarios: [ 用户要求对比分析竞品价格, 用户要求调研某品类Top商品的销量表现 ], not_for: [ 用户要求的是非电商平台数据, 用户只想要单个商品详情而非竞品对比 ], input_schema: { type: object, properties: { competitor_names: { type: array, items: { type: string }, description: 竞品品牌或店铺名称最多不超过5个 }, category: { type: string, enum: [3C, home_appliance, beauty], description: 目标品类 }, platform: { type: string, enum: [tmall, jd, douyin], default: tmall } }, required: [competitor_names, category] }, output_schema: { ... }, dependencies: [PRICE_SERVICE_API_KEY, RATE_LIMIT_CFG], failure_strategy: retry_once_then_degrade }这里最关键的不是字段定义得多么花哨而是scenarios和not_for这两个字段。这两个字段是帮助模型做技能选择的锚点写得好能大幅降低技能误触发的概率。我发现很多团队的技能描述里只有一句description模型在多个相似技能之间做选择时就容易飘加上了典型场景和反例场景之后准确率提升非常明显。2.4 技能生命周期管理要点技能不是写完就完事的它有创建、调用、监控、更新、下线这样一个完整生命周期。创建阶段要重点关注技能描述与实际行为的一致性。很多技能是描述得很美执行得稀碎模型根据描述选了它结果干出来的活完全不是那么回事。所以我建议每个技能在注册上线前都要做至少一轮描述-行为一致性评审就是拿描述去要求另一个Agent根据它执行几个用例看能不能跑出预期结果。监控阶段要关注的是技能的调用成功率、平均执行时长、返回结构异常率。技能毕竟是给模型用的模型在调用时会产出各种各样的参数组合有些组合是你的schema里根本没定义过的这些情况都要被记录下来。更新阶段最重要的是做版本管理。技能的更新不能直接覆盖因为模型上下文中可能还缓存着旧版本的描述和参数schema直接替换会导致模型按旧的理解来调用新接口很容易出兼容性问题。正确的做法是保留版本历史并在技能注册中心里做灰度切换。最后是下线阶段要确保没有正在执行的会话还引用旧技能最好在做完下线通告之后隔一个完整会话周期再物理删除。3. 从零搭建一套Agent技能模块实操环节3.1 明确技能边界与依赖清单我先说说技能边界怎么梳理。实操中的第一步是从历史对话和任务日志里拉出所有用户请求按任务目标聚类。比如查天气和查空气质量看起来是两件事但从用户视角都是天气相关的信息查询可以统一到一个技能里做意图内分流而查天气和根据天气规划出行虽然相关但后者涉及行程编排逻辑就应该拆成两个技能。边界划完之后要做依赖清单。依赖不只是外部的API和密钥还包括运行时依赖。比如技能执行需要Python 3.10以上的环境需要安装某个第三方库需要在当前机器上有可用的GPU资源。依赖清单做得越完整这个技能在别的团队、别的项目里复用时踩的坑就越少。这里我强烈建议给每个技能配一个环境自检脚本技能加载时先跑一遍自检确认依赖可用再往下走。我在一些生产项目里看到过很惨的案例技能在测试环境一切正常上线之后连接数据库的账号没有权限导致Agent一连几天返回固定错误。如果有自检脚本这个问题第一分钟就会被发现。3.2 技能注册中心的实现思路技能注册中心是整个技能体系中基础设施中的基础设施。它的核心职责是保存所有技能的定义、版本、依赖信息和启用状态并提供按需查询能力。实现上不一定要搞得特别复杂我的建议是先用一个独立的内存索引加定时同步然后是带持久化能力的中央注册中心。如果你的团队已经有了配置中心或服务注册中心把它们扩展一下就能用。注册中心里存储的每条技能记录应该包含技能名、版本号、注册时间技能描述、触发场景、反例场景输入输出Schema依赖项清单和环境要求当前启用状态和灰度策略历史版本列表及回滚点注册中心还要提供按语义相似度搜索的能力。这一步很关键因为Agent技能选择的本质不是精确匹配而是基于模型embedding向量的相似度搜索。我通常的做法是给每个技能预先计算一个描述向量在模型需要技能选择时先通过向量检索召回前5个候选技能然后把这5个候选技能的完整描述交给模型做最终决策。这样既能控制上下文注入量又能保证候选集的质量上限。3.3 模型与技能模块之间的语义匹配这是整个技能体系中最核心、也最容易翻车的一环值得详细说说。模型在接到用户任务之后需要自己决定要不要调用技能、调用哪个技能、用什么参数调用。这个过程本质上是一个语义匹配加参数填充的双重任务。第一阶段语义匹配是把用户请求向量化之后在技能注册中心里搜索最相似的技能描述集合。这里我学到的一个教训是不要只靠一个embedding模型最好准备两个互补的检索策略。一个用语义向量另一个用关键词和近义词扩展然后把两个召回结果做融合排序。如果你的场景里有很多用户习惯说法跟技能描述措辞差异大比如用户说帮我盯着点竞品而技能描述里写的是定时抓取竞品价格那么向量检索召回率可能不稳加上关键词共现的召回结果会更稳。第二阶段参数填充是把用户请求中的相关信息映射到技能的输入schema上。这一阶段最大的坑是模型的参数幻觉即它可能会自己编造schema里不存在的参数。我在后面的常见问题章节里会展开讲。一个比较直接的建议是不要把所有的参数填充都交给模型。对于枚举值、数值范围、正则格式有明显约束的参数可以在技能描述中把约束条件说得更详细之外还需要在执行层再补一层参数校验逻辑。模型给过来的参数先过了校验器再走执行逻辑不合法就返回一个结构化错误让模型自行修正。这手双层保险能极大降低脏数据进入业务系统的概率。3.4 完整技能加载流程我总结了一套比较成熟的技能加载流程每一步都有明确的产出物和校验节点。第一步接收任务并进行意图初判。系统先决定这是一个需要技能的任务还是一个模型可以直接回答的问题。这个判定通常可以由一个轻量级分类器完成。第二步候选技能召回。通过向量检索和关键词检索组合的方式召回top K候选技能。第三步系统提示词组装。把当前任务相关的候选技能描述动态注入到系统提示词里。我倾向于同时注入候选技能的输入输出schema给模型的参考做得越具体后面出错概率越低。第四步模型决策与参数生成。模型输出技能选择结果和JSON格式的参数。第五步参数解析和合法性校验。这一步由独立的参数校验器完成校验不通过就返回错误代码和修正建议给模型让模型重新生成参数最多重试两次。第六步技能执行引擎调度。技能被拉起后按技能内部定义好的逻辑运行可能是调外部API、查数据库、执行本地脚本等。第七步执行结果反馈。结果回到模型上下文由模型组织语言生成对用户的最终回答。这一步要格外注意防止模型在转述结果时瞎发挥能直接引用结构化结果的最佳。这七步我建议做成一个可观测的流水线每一站都输出日志。实际排障时有没有这一整套日志排查效率是天壤之别。3.5 技能执行后的反馈链路反馈链路是整个体系里容易被忽视、但极其重要的一环。一个技能执行完成之后返回的不仅仅是执行结果还应包括执行元信息调用耗时、依赖资源消耗情况、是否有降级行为发生、返回结构是否完整。这些元信息有两个去向。一个去向是模型上下文。模型需要知道自己刚才的技能调用是否成功是否需要进一步追问用户或补跑其他技能。比如技能执行成功但数据为空模型需要据此判断是真的没有数据还是需要引导用户换个关键词再试一次。另一个去向是监控遥测系统。技能调用成功率、失败原因分布、参数校验拒绝率这些指标直接指导后续的优化方向同时也要作为告警检测的核心指标。比如某个技能连续五分钟调用失败率超过50%应该立即触发告警并考虑自动熔断降级。我在实践中还会给反馈链路加一层用户信号追踪。当技能执行完成并输出结果之后观察用户是表示满意、继续追问还是直接结束会话。这个信号可以用来评估技能描述和用户期望的匹配度是一个非常隐蔽但好用的效果指标。4. 常见问题与排查技巧实录4.1 参数幻觉模型编造了schema里不存在的参数这绝对是我在Agent技能体系上遇到过的第一大坑。现象是模型输出的JSON参数里出现了技能schema里完全没有定义的字段或者是给了错误类型比如schema里规定category是枚举值模型传了tmall_and_jd这种组合值。这个问题的根源在于模型在做参数填充时会依赖自己对文本的理解进行补全与联想而不是死板地照搬schema。当你给了模型足够长的上下文它填充参数的自由度就越大幻觉概率也随之上升。排查和应对我分三招。第一招是给参数schema提供更严密的描述。不只是枚举值列表还要把每个枚举值的准确含义写清楚。比如category: tmall是什么意思tmall_and_jd为什么不是合法值都可以写在description里。模型理解了约束边界幻觉率就会降下来。第二招是设参数白名单校验。所有模型生成的参数必须在执行前过一遍JSON Schema校验器。不合法参数绝不直接执行而是把校验错误消息返回给模型让它基于错误提示进行自我修正。这里关键是错误消息要写清楚哪个字段不合法、期望的类型/枚举值是什么、当前给了什么模型根据这个信息修正的成功率能到八成以上。第三招是限制参数自由度。如果某个参数在一定条件下有唯一推导规则就不要交给模型生成。比如平台参数如果当前用户的IP已经能判定来源区域那平台参数完全可以由系统侧填充不需要模型决策。所有能由规则决定的东西尽量不要交给模型。4.2 技能膨胀技能库越来越多召回越来越飘第二个常见问题是随着业务发展技能数量越加越多多到两三百个甚至上千个技能随之而来的是召回准确率明显下降。这背后有两层原因。第一层是向量检索在高相似度技能增多之后召回结果的区分度变差。第二层是技能描述之间有互相污染比如价格查询和历史价格查询两个技能描述高度重叠模型在做最终选择时也会更犹豫。我的处理办法是分三层缓解。第一层是缩维度就是做技能分类目录。每个技能在注册时都要挂载到一个分类节点下模型先选分类再在分类内部选技能把一次大范围选择拆成两级小范围选择。这能显著缩小候选集。第二层是做技能描述差异化。同类技能的描述避免共用模板要为每个技能提炼真正独特的触发场景和边界条件并明确not_for的场景这样模型才有足够的信息做区分。第三层是定期做技能合并与下线。如果两个技能的实际命中重叠度持续超过某个阈值比如连续两周都在70%以上应该考虑合并或者做同一技能的不同分支。技能数量不是越多越好保持精简比堆积数量更重要我一直用这个判断标准。4.3 版本冲突与灰度切换的坑技能做了版本更新之后最容易出现的问题是模型调用技能时的行为与新版本不兼容但模型拿到的还是旧版技能的描述。出现这类问题通常是你调整了接口schema但模型上下文里缓存的信息没有同步刷新。我为此专门规范了技能更新的流程。技能发新版本先引入兼容校验逻辑。新版本的schema要能够兼容旧版本的调用输出如果做不到兼容那么旧版本的调用应该在注册中心被标记为停用而不是已更新。灰度切换方面我不会硬编码指定某版本生效而是引入一个version-probe的参数在新版本号后面加上一个环境标记让不同会话上下文拿到不同版本的技能描述。等新版本的各项指标稳定跑满一段时间之后再把流量全部切到新版本。版本号的语义规则也要事先定义清楚我的习惯是遵循语义化版本规范。大版本是指接口不兼容的变更中版本是行为调整但接口兼容小版本是描述性文字更新。因为技能描述参与模型决策所以小版本的更新本身也会影响模型的调用行为这一点和普通软件版本更新的影响面不同。4.4 上下文被技能描述撑爆第三个实际问题是——技能体系做完了每个技能描述都很完备但如果你把所有候选技能的完整描述都塞进上下文那上下文体积会非常大几轮会话之后就可能撑爆窗口。我实测下来一个技能的基础描述加输入输出schema通常需要800到2000个字符如果是更复杂的技能加上详细说明三四千个字符都挡不住。如果一次会话要管理8到10个候选技能光技能描述这一块就要消耗一两万token再叠加多轮历史对话和中转信息上下文很容易顶着上限跑。解决方案是给技能描述做分层存储。注册中心里保存的是完整详细版但在模型上下文里注入的是经过压缩的摘要版。摘要版只包含这样几部分技能名、一句话职责、主要触发场景、输入参数的必填字段和关键约束、输出结构简要说明。如果模型在摘要版里无法完成选择它可以选择展开技能详情来获取更多信息这时才把完整版加载进来。这个机制能有效控制上下文占用把更多空间留给历史对话和结果推理。4.5 技能层面的权限与安全设计最后是安全我把安全话题放到了排查章节里讲因为大多数团队都是出事之后回头补的。技能体系里最典型的安全隐患是技能权限过大。比如一个查询数据库的技能如果它的执行账号对所有库表都有读权限模型就有可能在参数填充时把一些不该被查询的表名给传进来。这种问题的可怕之处在于它不是黑客攻击而是模型的无心之失但后果可能很严重。我的应对思路是技能最小权限原则。每个技能在注册时都要申报自己需要的权限范围执行引擎在拉起技能做具体操作之前先做一次权限校验确保技能的实际行为和申报能力一致。数据库访问的场景要追加行级和列级权限控制外部API调用要确保调用密钥指到专用的隔离账号。另外凡是涉及下单、删除、转账、推送这类高影响的技能强制设计二级确认机制。Agent可以先执行预计算并展示结果给用户用户确认后再正式执行同时稽核接口留痕。这一设计没有任何负面作用只是让高危操作多了一道保险阀门。5. 结尾一点实操体会整个技能体系搭建过程中我最大的体感变化是从调模型变成了设计能力库。模型的能力是一个已知量能变的是外部技能模块的边界、质量和配合方式。每次新业务进来我不再焦虑要不要改提示词而是思考该沉淀一个什么样的新技能。如果你现在刚起步我的建议是不要急着把体系建得特别重。挑一个你实际业务中最高频、最痛的任务把它封装成第一个技能跑通描述-选择-执行-反馈的闭环然后把中间遇到的问题记录下来再迭代下一版设计。技能体系这件事是在一次次真实任务的打磨中慢慢长出来的不是照搬一个框架就能一步到位的。最后分享一个小技巧给技能描述写完之后试着扔给一个大模型看让它不看你的业务代码只看描述来判断这个技能什么时候该用、什么时候不该用。如果它能准确判断这个技能描述就合格了如果它犹豫或出错你就有机会在真实用户遇到同样困惑之前把描述修得更准。