从Demo到生产：为AI Agent构建可复用技能库的完整指南

大模型Agent从Demo走向生产最尴尬的阶段不是模型不够聪明而是它什么都会一点点但什么都干不利索。我做过不少Agent项目早期版本都有一个通病把工具调用逻辑全部堆在系统提示词里结果模型经常自己发明函数签名出错了也不知道怎么恢复。后来我意识到问题的核心不在于模型本身而在于我没有给Agent建立一套可复用、可测试、可演进的技能系统——也就是agent-skills的思路把Agent需要的能力拆成独立技能模块每个技能有清晰的描述、参数协议、执行逻辑和错误处理再由Agent动态编排调用。这篇文章就是围绕这套思路展开的。如果你正在做AI Agent相关开发或者准备给现有业务接入Agent但不知道怎么组织工具这篇文章应该对你有用。我会把技能库的设计思路、具体模块实现、质量保障和排障经验都拆开聊尽量给出能直接参考的做法。1. 技能库Agent从能做到做得好的分水岭1.1 为什么提示词堆不出生产力很多团队的第一版Agent是在系统提示词里写你可以调用以下工具get_order、get_user_info、send_sms参数分别是……。这种方式在小范围验证时能跑通但一旦工具数量超过十几个问题会集中爆发。模型会开始混淆相似功能的工具比如把查询订单状态的参数填成查询用户信息的参数会在工具返回空结果时反复重试同一调用还会在同一个对话里把上下文日志越滚越长最后把最重要的指令挤出注意力窗口。我见过最夸张的一次是有个Agent在处理退款时连续调了七次查询接口每次都带着几乎一模一样的参数最后用户等了四十秒才收到一个可能查不到的提示。这种体验显然不能上线。问题的表面原因是提示词组织不够好本质原因是缺乏结构化的技能管理——工具没有边界参数没有约束失败没有预案。1.2 技能Skill的准确定义在agent-skills的框架里一个技能不再是一行函数描述而是一个包含完整生命周期的模块。它至少需要包含以下几个部分技能元信息技能名称、用途描述、适用场景、不适用场景。这些信息直接影响模型的调用决策写不清楚Agent就会乱选。输入协议参数名、类型、必填性、取值范围、默认值。这是最容易被忽略但最容易引入线上问题的部分。执行逻辑实际干活的代码包括API调用、数据解析、内部编排。输出协议成功时的返回结构、失败时的错误码与错误描述。护栏Guardrails前置校验、后置校验、权限检查、敏感信息脱敏。失败策略什么时候重试、什么时候降级、什么时候直接向用户承认做不了。把技能想成一个人类员工接到的岗位说明书 工作手册 应急预案就不难理解为什么要单独设计了。Agent本身是多面手但具体每件事怎么做、做到什么标准、做砸了怎么补救必须由技能模块来约束。1.3 技能库与普通工具列表的差别普通工具列表是一张扁平清单Agent自己摸索着用。技能库则多了一层治理能力技能之间可以组合可以设置依赖可以做版本升级可以单独测试可以配置灰度。相当于从给员工一堆零件升级成给员工一套工具箱和操作规范。另一个关键差别在于召回方式。工具列表模式下模型每轮都要从头看所有工具。技能库模式则可以在每轮任务开始时先根据用户意图做一层技能预筛选只把可能相关的技能描述注入上下文其他技能留待需要时再加载。这一步对降低Token消耗、减少决策干扰非常有帮助。我把这两种方式的差别拉了一个简单对照维度普通工具列表技能库组织方式扁平清单分层 依赖 组合调用决策全靠模型每轮判断预筛选 动态加载失败处理模型自由发挥技能内建重试/降级策略可测试性弱联调困难强可单测可回归迭代成本改提示词容易连锁污染改单个技能独立发布所以我在后续项目中基本放弃了纯提示词工具表方案转为技能库模式。这篇文章后面提到的技能都指这种结构化模块。2. 我从零搭建技能体系时的分层思路2.1 原子技能、组合技能与应用层技能很多人一开始想把技能设计得大而全一个技能解决一类完整问题。我试过结果就是技能之间大量重复改动一处要连带改好几个模块。后来的经验是必须先分层原子技能、组合技能、应用层技能。原子技能是最小颗粒度的能力不能再拆分。比如查询订单状态计算用户年龄发送短信验证码每个原子技能只做一件事参数简单、逻辑直接。组合技能则编排多个原子技能或嵌套其他组合技能完成一个相对完整的业务子任务比如处理退款申请可能包含校验订单归属检查退款状态发起退款通知用户四个步骤。应用层技能通常对应一个用户可见的完整需求比如售后服务技能。应用层技能内部不直接写业务逻辑而是维护一张路由表把不同意图分发到对应的组合技能上。这样分层带来的直接好处是底层原子技能稳定不变组合技能可以灵活调整流程应用层技能只需要关心意图路由。2.2 技能之间如何做依赖管理组合技能一定会调用多个底层技能这就产生依赖关系。我的做法是为每个技能声明一个显式的依赖清单在技能注册时由框架做拓扑校验确保没有循环依赖。比如处理退款依赖校验订单归属和发起退款而发起退款不能再反过来依赖处理退款。依赖声明还有一个额外的作用框架可以在Agent决定调用某个组合技能之前先把全部依赖技能的描述和必要状态预加载出来避免Agent中途发现缺少参数再临时搜索。这样虽然简单但真的能明显降低多轮调用的失败率。2.3 注册中心与技能描述的可检索性设计技能库需要一个注册中心本质上就是一个带索引的技能目录。每个技能在注册时除了代码实现还要写入结构化的描述包括技能ID、名称、意图关键词、输入输出Schema、依赖列表、版本号、负责人、变更日志。描述文本的质量需要单独打磨因为模型的选择大概率取决于描述是否清晰、是否与其他技能有区分度。我总结了一个判断标准把同类的几个技能描述放在一起让一个不了解业务的人或模型能在三秒内选出正确的一个。比如查询订单状态和查询订单物流很容易被写混前者侧重订单生命周期状态待支付、已支付、已取消后者侧重物流轨迹发货地、当前位置、签收状态。描述里必须把这些细微差别写透否则再聪明的模型也会选错。3. 落地最频繁的五个技能模块及实现细节3.1 外部API调用技能参数校验是第一道防线任何Agent只要对接了外部系统就一定会用到API调用技能。这个技能看似简单最容易翻车的地方是参数。用户说帮我查下昨天那个订单模型可能把昨天解析成日期字符串也可能解析成时间戳还可能直接不传。所以我在API调用技能里加入了前置校验环节在校验不通过时输出一个结构化错误而不是直接把缺参请求发给外部系统。下面是一个简化版的参数定义示例{ skill_id: query_order, description: 按订单号查询订单状态适用于用户询问订单进展的场景, parameters: { order_no: { type: string, required: true, pattern: ^[A-Z0-9]{8,24}$, description: 业务订单号仅允许字母和数字 } }, prechecks: [ order_no 存在, order_no 格式正确, 当前账号有该订单的访问权限 ] }前置校验不应该是生硬地拒绝而是给模型一次修正机会。比如检查发现order_no格式不对时返回的错误信息要带上具体期望格式模型拿到就能马上改。如果直接说参数错误模型大概率会懵掉然后开始瞎猜。3.2 记忆管理技能别让上下文变成垃圾桶很多Agent项目的上下文管理是放任式的每次对话把全部历史记录都塞给模型。随着对话变长Token成本猛涨而且旧信息会稀释模型对新指令的注意力。我的方案是把记忆拆成三层工作记忆、会话记忆、长期记忆。工作记忆只放当前任务的关键变量比如订单号、用户ID、当前操作步骤每轮结束自动刷新。会话记忆保留用户本轮对话的完整消息但在超过一定条数后做摘要压缩。长期记忆存储跨会话有用的信息比如用户偏好、历史投诉记录这部分内容不是每轮都加载而是按需检索。这个技能对业务效果的影响非常大。我之前遇到过一个真实案例用户在第一轮说过自己在深圳第五轮问那我现在该怎么办时Agent因为没有长期记忆回答成了面向一般用户的通用建议。加入长期记忆检索后同样的场景下Agent会主动关联地域信息回答质量提升明显。3.3 规划拆解技能把大目标切成可执行步骤当用户提出一个复合需求比如帮我对比三款手机然后推荐一款再帮我下单Agent需要先做任务规划。规划技能的核心输出不是一段自然语言而是一个结构化的步骤列表[ {step_id: 1, skill: search_products, params: {keywords: 手机}}, {step_id: 2, skill: compare_specs, params: {models: [A, B, C]}}, {step_id: 3, skill: recommend_product, params: {strategy: 性价比优先}}, {step_id: 4, skill: create_order, params: {product_id: ...}} ]规划结果不一定要立刻执行它有两个作用一是让模型自己推演一遍流程提前发现缺参数或逻辑冲突二是向用户展示我打算这样做用户可以中途纠正。我认为这第二点在C端场景尤其重要因为直接闷头执行容易出信任问题。3.4 自省校验技能给结果加一道质检Agent的输出不只是一段文本很多时候还包括结构化动作或数据结论。自省校验技能负责在最终输出前做一遍质检检查提取出的实体是否有来源依据、生成的SQL是否符合预期、给用户的金额计算是否准确。本质上就是让模型再想想。我会在自省环节用一次额外的模型推理但对于高精度要求的场景比如财务计算更可靠的做法是把关键结论抽出来用确定性代码重新算一遍。举个例子Agent告诉用户退款金额是108元其中包含运费8元自省代码会重新计算100 8是否等于108并校验金额是否为正数。模型可能有幻觉但数学代码不会。3.5 人工介入技能承认做不了也是一种能力有些任务确实超出了Agent的能力边界比如需要调一个没有对接的系统、需要线下的身份验证或者用户表达出强烈的情绪需要安抚。硬撑反而会把事情搞砸。我专门做了一个移交人工技能触发条件包括模型连续两次无法完成任务、检测到高危操作、用户主动要求转人工。这个技能的关键在于移交时要带走足够多的上下文。不是简单说一句我帮你转人工而是把用户的需求、Agent已执行的步骤、当前卡点、需要人工关注的风险全部打包成一张交接单。这个设计对运营同事非常友好他们不用追问用户一遍您刚才遇到什么问题了体验差距非常明显。4. 给技能库配一套质量保障流程4.1 单技能测试集与回归策略技能是可以单独部署的模块那就应该单独测。我维护了一套分技能测试集每个技能下至少有几十条覆盖正常路径、边界路径、异常路径的用例。测试不只在发布前跑更重要的是每次修改后都跑防止改一个逻辑把另一条依赖链路弄坏。对于涉及模型决策的技能测试断言不能只看最终结果还要看中间调用序列。比如处理退款技能可能要断言必须先校验权限、再发起退款、最后发通知这三步顺序不能乱。这类断言能有效防止模型在某个版本突然开始跳步骤。4.2 线上效果评估不能只看成功率技能上线后要持续观察几个核心指标任务完成率、技能调用准确率、平均调用轮次、单任务Token消耗、平均延迟。我尤其关注两个容易被忽视的指标技能误调率调用了一个不该调的技能和修复率第一次调用失败后Agent通过修正参数在本次任务内成功。误调率高的技能通常描述有问题需要重写描述或增强区分度。修复率低则说明技能的失败策略设计不合理模型不知道怎么从错误中恢复。这些指标不能等用户投诉才看我建议放到每日监控面板上变化超过阈值就告警。4.3 技能的版本管理与兼容性技能迭代会改变输入输出协议如果没有版本管理上游组合技能可能还在按旧协议传参结果全军覆没。我的做法是采用语义化版本号主版本号在协议不兼容变更时递增次版本号在功能增强时递增补丁号在缺陷修复时递增。组合技能在声明依赖时要显式写明可接受的版本范围。比如依赖query_order 2.0.0 且 3.0.0。升级到不兼容的主版本时上游依赖方必须主动适配不能混着用。这个机制保证了技能库能持续演进又不会让线上环境突然崩掉。5. 四类高频事故的真实排查记录5.1 事故一Agent反复调用同一个技能导致超时现象一个用户查询场景中Agent连续调用了5次查询接口参数几乎一样每次返回结果都相同最终超时。排查过程我先看了调用日志确认模型不是收到错误后重试而是在正常返回结果后依然重复调用。进一步检查提示词和技能描述发现技能描述里写了一句如果需要获取更多信息可以多次查询这句模糊的话被模型理解成了可以无限重复查询。同时组合技能的终止条件没有设置上限模型不知道任务在何时算完成。修复手段一是删除技能描述中的模糊表述明确查询成功后无需重复查询二是在规划技能里加入终止条件校验同一个技能在同一个任务子步骤中最多调用两次超出后强制进入汇总阶段。修复后误调现象消失任务轮次从平均7轮降到了4轮。5.2 事故二技能描述区分度不足导致张冠李戴现象用户询问我到哪儿了Agent调用了查询订单状态技能返回订单已签收而用户实际想查的是物流轨迹。排查过程我把两个技能的描述打印出来对比发现查询订单状态和查询物流轨迹都写了查询订单进展字样语义高度重叠。模型只能靠运气去选。进一步翻历史日志发现这个问题已经存在很久只是用户反馈不强烈没有爆发。修复手段重写两个技能的描述将查询订单状态限定为订单生命周期节点待支付、已发货、已签收等将查询物流轨迹限定为物流流转明细转运点、派送员、当前位置。同时在意图预筛阶段增加一轮关键词路由当出现到哪儿派送快递等词时直接命中物流技能。修复后两个技能的选型准确率从72%提升至96%。5.3 事故三上下文过大导致模型忘记了最早的用户诉求现象一个长对话中用户先说了要对账然后聊了5分钟其他话题再回来问那笔钱到底差在哪Agent给出的回答与对账任务毫无关联。排查过程我查看模型调用时的上下文发现工作记忆区已经被大量闲聊内容挤占最关键的对账任务参数被挤出了有效窗口。问题不在模型能力而在于我没有及时清理记忆。修复手段改用分层记忆策略把任务关键变量放在工作记忆区并设置独立优先级只要任务未完成就不被清理。同时会话记忆超过10轮自动摘要压缩把历史细节转化为更精简的概述。修复后同类场景下的任务保持率明显提升效果很好。5.4 事故四失败策略设计不当导致死循环现象外部接口偶发性超时Agent收到异常后不断重试每次重试叠加延迟最终单次任务总计耗时接近两分钟用户直接流失。排查过程查看错误处理日志发现失败重试的退避策略是固定3秒且没有最大重试次数限制。更隐蔽的问题是重试时参数没有变化意味着即使接口恢复也需要重试同样次数。修复手段重写技能失败策略改为指数退避1秒、2秒、4秒同时设置最大重试3次超过后走降级路径——返回部分结果并告知用户当前服务繁忙请稍后再试。另外加入重试前置条件判断当前一次错误是超时而非业务拒绝时才允许重试。修复后该技能的超时类故障处理时间从120秒降到10秒以内。6. 框架选型和自研衡量我的取舍标准6.1 现有Agent技能框架的共通优势与不足现在市面上谈到Agent技能通常会落到LangChain的工具机制、OpenAI的Function Calling/Assistants、以及各类开源Agent框架上。这些框架确实解决了一部分问题函数调用协议标准化、自动生成调用参数、简化了从模型到代码的对接。有团队直接基于这些框架快速搭起Agent服务初期效果明显。但等技能数量上来后框架自带能力的边界也就显现了。多数框架解决的问题是模型调用工具但技能治理这块——依赖管理、版本控制、回归测试、灰度发布、线上指标监控——很多框架没有现成的成套方案。遇到这些需求时团队还是得自己搭一层管理平台。框架能省掉最开始的造轮子成本但业务复杂到一定程度后治理层的设计终究绕不开。6.2 我的分层建议不排斥框架但治理层自主设计我的经验是调度层可以放心用成熟框架让框架负责协议解析、模型交互、工具路由这些通用能力。但技能注册、依赖校验、版本管理、质量评估这四块治理能力建议团队自己掌控因为它们是业务特有的不同行业不同场景的治理规则差异巨大。比如金融场景对审计日志和权限校验要求极高只能自研内容社区场景对UGC内容审核技能的依赖也很独特通用框架里没有。把这些治理逻辑放在框架之外既不容易被框架升级绑架也方便与公司内部已有的权限、监控体系打通。6.3 自研技能库的最小可行设计如果你的团队决定自研技能库我建议从最小闭环开始不需要一开始做得很重。先具备几个核心能力技能注册接口、技能描述存储、依赖拓扑校验、运行时调用拦截器、基础日志埋点。第一版甚至可以不用图形界面用配置文件和命令行工具就能维护。我见过不少团队在自研时犯一个错误技能库还没建起来先花大量精力开发管理后台。其实前期完全不必。先把规则用版本化配置管理起来跑通流程之后再逐步做可视化。技能治理核心是规则不是界面。7. 技能演进路径上的最后几点体会技能库不是一次性建完就结束的静态资产它需要跟着业务一起迭代。我在实际运营中感受最深的一点是技能库里真正长期活跃的技能其实占比不高不少技能在上线后始终无人调用。与其追求技能数量不如定期做一次技能下线评审把那些描述模糊、无调用量的技能清理掉避免它们干扰Agent的决策。新技能的加入也应该走一个轻量评审流程至少要明确该技能与现有技能的边界、说明用户会在什么场景触发它、以及列出三条供测试验证的场景。这个流程不需要很重但能挡住很多感觉有用实则冗余的技能。另外技能描述不是写一次就完事的文案。模型版本一升级模型对描述的理解能力也会变化。我建议每次更换底层大模型版本后重新跑一遍技能选型测试集对比新旧模型下的选型准确率。之前遇到过换了新模型后查询订单状态和查询物流轨迹的误选率从4%涨到15%查了好久才发现是模型版本导致的语义理解偏移。类似情况用回归测试来找根因往往比人肉看日志快得多。回到最初的问题——Agent为什么总是什么都会但干不利索很大程度是因为把技能藏在了提示词里而不是做成体系的工程模块。把每一次工具调用、每一步规划、每一段记忆当成一个可测试、可版本化、可治理的技能Agent才能真正稳定起来。这也是我在项目里反复验证之后才彻底相信的一点。