Agent技能库设计：从工具调用混乱到稳定可控的工程实践

1. 为什么要给Agent建一套技能库今年年初我接手了一个比较头疼的落地项目核心目标是把大模型接入真实的业务流程让它能自己处理工单、查数据、做判断。一开始的思路很简单给模型一个超长的system prompt配上十几个function定义然后祈祷它每次都能选对工具、填对参数、走对流程。结果自然是翻车了。不是模型不聪明而是你把太多事情混在一起塞给模型它就不知道该先干什么、后干什么什么时候该调用工具什么时候该闭嘴直接回答。最典型的一个场景是用户问帮我查一下上周订单的状态模型以为自己已经查过了直接开始编订单号。这种问题靠调prompt很难根治因为根子在于——你压根没有给Agent建立起一套可复用的行为能力体系。这就是我想聊的agent-skills。简单说它是一个面向大模型Agent的技能管理架构把模型能用什么工具、怎么用、什么时候用、做完之后怎么校验结果拆成一个个独立封装、可以组合、可以复用的技能单元。每个技能不再是一行function definition而是一整套触发条件 执行逻辑 参数约束 结果验证的完整闭环。这个思路解决的核心痛点有三个第一把复杂任务拆成原子能力模型的选择负担大幅降低第二每个技能的触发条件和行为边界是显式的误调用、乱调用的问题可以系统性地拦截第三技能与技能之间可以编排组合产品迭代时只需增删技能不用每次重写prompt。如果你也在做Agent相关的工程落地并且已经被工具一多模型就开始发疯折磨过这篇文章值得看完。我会从设计思路讲到代码实现再到实际运行中踩过的坑把整套方案尽量完整地拆开。2. 技能层整体架构与设计思路2.1 从模型自由发挥到技能约束的转变先说一个我在项目里反复验证过的结论大模型本身的能力边界是模糊的你越是让它自由发挥它的行为就越不可预测。但如果你给它的不是一堆工具而是一个技能库行为就会收敛很多。这里面的差别在于工具是字典技能是操作手册。字典告诉你某个函数能干什么但不会告诉你在什么情境下该翻开哪一页操作手册则把场景 → 动作 → 校验绑在了一起。比如查询订单这个动作在技能架构里它不是孤立的function而是一整套定义适用场景用户表达了对订单状态的疑问前置条件必须解析出订单号执行动作调用订单系统的查询接口后置校验查询结果必须包含有效状态字段否则判定失败并走兜底话术这个设计最直观的好处是模型的决策空间从十几个工具排列组合缩减为几条技能路径二选一。决策质量自然就上来了。2.2 技能编排与组合机制技能之间不是完全孤立的。在实际场景里一个用户问题往往要触发多个技能协作。比如帮我取消昨天买的那个耳机的订单表面上看是取消订单一个技能的事但实际执行链路里你需要先查订单列表找到具体订单再判断当前状态是否允许取消最后才执行取消动作。所以在设计技能层的时候我额外加了一个依赖声明的机制。每个技能可以声明自己依赖哪些其他技能Agent在运行时会根据这个依赖关系自动编排执行顺序。这样带来的好处是单个技能保持原子性而复杂任务通过组合完成不把逻辑写死在某个技能的内部。我实际用下来这个机制还有一个隐藏的好处当某个技能出问题时影响范围是可控的。比如取消订单依赖的查订单列表接口有一天挂了只会影响所有用了取消订单技能的会话其他技能照常工作。而如果所有逻辑都揉在一个大Agent里一个接口抖动就可能让整个系统的行为都失控。2.3 技能注册表与热加载设计技能层要支撑真实业务就必须考虑可扩展性。我这边采用的方案是一个技能注册表 目录扫描的机制。每个技能在文件系统里是一个独立目录里面包含技能定义文件skill.yaml、执行脚本skill.py、校验规则validator.py启动时通过一个加载器扫描技能目录自动注册到运行时环境里。这个设计带来的直接好处是新增技能不用改Agent主程序只要按规范往技能目录里丢一个文件夹重启或热加载之后就能被Agent发现并调用。我甚至做了一个简单的热加载接口在后台调整完技能代码之后通过一个API触发重新扫描——当然生产环境建议还是走标准发布流程但开发调试阶段这个能力真的能省很多时间。目录结构大概长这样skills/ ├── order_query/ │ ├── skill.yaml │ ├── skill.py │ └── validator.py ├── address_edit/ │ ├── skill.yaml │ ├── skill.py │ └── validator.py └── agent_skills/ ├── registry.py ├── loader.py └── exceptions.py3. 核心细节一个技能的标准组成3.1 技能声明skill.yaml定义了哪些东西skill.yaml是整个技能的门面也是Agent运行时用来做决策的最重要依据。它包含的字段我一般是这么设计的name: order_query description: 查询订单详情适用于用户询问订单状态、物流进度、商品信息等场景 version: 1.0.0 trigger: intents: - order_query - order_status entities_required: - order_id dependencies: - user_auth execute: entry: skill.py:main timeout: 5 validators: - validator.py:validate_result fallback: - message: 抱歉没有查询到对应的订单信息请确认订单号是否正确这个文件里我重点强调两个容易被新手忽略的字段。第一个是trigger.intents。这不是给最终用户看的而是用来在Agent内部做意图预筛。当用户问题进来后系统会先跑一轮轻量的意图分类只有命中了相关意图这个技能才会被纳入候选集合。这么做能把大模型的选择范围进一步缩小减少误调用。第二个是fallback。很多技能设计文档里根本不写fallback但真实线上环境里接口超时、数据异常、参数缺失都是家常便饭。没有兜底话术的技能一旦执行失败就会把错误暴露给用户体验极差。我现在的规范是无兜底不发布。3.2 执行函数skill.py的接口约定执行函数是技能的核心逻辑我这边约定了一个统一入口main(params, context)返回一个标准化的结果对象。这样设计的目的是把技能的输入输出都约束在一个稳定的协议之内无论是Agent调度器还是其他技能来调用都能用同样的方式对接。# skill.py from agent_skills import SkillResult def main(params: dict, context: dict) - SkillResult: order_id params.get(order_id) if not order_id: return SkillResult(successFalse, error缺少订单号) # 调用订单服务 data query_order(order_id, user_tokencontext[user_token]) if not data: return SkillResult(successFalse, error订单不存在, fallback抱歉没有查询到对应的订单信息) return SkillResult(successTrue, datadata)这里context参数很多人会忽略但它在真实系统里非常重要。比如用户身份、当前的会话状态、请求追踪ID都是通过context传给技能的而不是让技能自己再去查一遍。这样既保证了安全边界也让技能之间的数据传递更加清晰。3.3 验证器validator.py为什么要单独拆出来如果你只是想快速让Agent跑起来验证器看起来像多余的。但我的经验是没有验证器的技能层就像没有测试的代码库上线后都不知道哪里会炸。验证器做的事情很简单对执行函数返回的结果做一轮程序化校验确保数据是完整、合法、符合预期的。举几个实际例子查询订单接口返回了一个空字典这正常吗如果用户确实没有订单可以接受如果系统从来没返回过空字典就得判定异常。返回的金额字段是负数直接透传给用户吗不行需要拦截。接口返回了结果但status字段是UNAVAILABLE这时候是告诉用户查询成功还是查询失败需要验证器来定义。# validator.py def validate_result(result: SkillResult, context: dict) - SkillResult: if not result.success: return result data result.data # 校验订单号是否与请求参数一致防止出现串数据 if data.get(order_id) ! context[request_params].get(order_id): return SkillResult(successFalse, error数据校验失败订单号不匹配) # 校验关键字段 if status not in data or data[status] not in (PENDING, SHIPPED, COMPLETED, CANCELED): return SkillResult(successFalse, error订单状态异常) return result不要小看这个步骤。在实际线上场景里我最常遇到的一类问题就是工具调成功了但返回的数据本身有问题模型却直接把错误数据当成事实去回答用户。有了验证器这类问题在进入模型上下文之前就被拦截掉了。3.4 技能声明的完整校验规则与约束示例skill.yaml要支撑复杂场景字段会更多一些。我这边在项目后期扩展出来的几个字段也一并分享validation: schema: type: object required: [order_id] properties: order_id: type: string pattern: ^ORD\\d{12}$ retry: max_attempts: 2 backoff: 0.5 permissions: - scope: order:read - require_auth: true cost: estimated_tokens: 400其中permissions字段至关重要解决了多租户场景下的越权问题。具体来说就是在技能执行前先检查当前用户有没有对应权限没有权限就直接拒绝执行并返回提示省得让模型替我们做权限判断——模型在这件事上非常不可靠。cost字段是我后期加的。每个技能执行会消耗多少token、平均耗时多少有了这个预估之后调度器可以做一些预算控制。比如当某个会话的累计消耗超过阈值时自动降级到简易模型或者限制复杂技能的调用频率。这个在成本敏感的生产环境里非常实用。4. 实操过程从零到一构建一套技能层4.1 环境准备与基础代码骨架开始动手前你只需要一个基础的Python项目和OpenAI兼容的客户端SDK。我自己用的是FastAPI做服务端配合langchain的tool calling机制但这里为了讲清楚原理我直接基于openai库的function calling来实现。先初始化项目结构mkdir agent-skills-demo cd agent-skills-demo python -m venv venv source venv/bin/activate pip install openai pyyaml pydantic然后创建两个核心模块一个是技能加载器loader.py负责扫描技能目录并把yaml和py文件载入内存一个是技能运行时runtime.py负责根据用户输入决定调用哪个技能、传入什么参数、以及怎么把结果拼接到最终的回复里。加载器的核心逻辑不复杂重点是处理好异常情况。比如某个技能目录里的yaml格式写错了或者执行函数导入失败了不能让整个服务启动崩溃而要跳过坏技能并打印日志。生产环境里我还会再加一个技能健康检查的端点方便随时查看当前已加载了哪些技能、版本是什么、状态是否正常。4.2 实现一个真实技能查天气为了让例子完整我实现一个查天气的技能。这个技能的触发条件是用户询问某地的天气依赖的实体是城市名执行动作是调用一个天气API后置校验是返回值里必须有温度和天气状况字段。skill.yaml长这样name: weather_query description: 查询指定城市当前天气情况 version: 1.0.0 trigger: intents: - weather_query entities_required: - city execute: entry: skill.py:fetch_weather timeout: 3 validators: - validator.py:check_weather fallback: - message: 暂时查询不到这个城市的天气信息可能城市名称有误或者服务暂时不可用skill.py实现import requests from agent_skills import SkillResult def fetch_weather(params: dict, context: dict) - SkillResult: city params.get(city) if not city: return SkillResult(successFalse, error缺少城市名) # 这里替换成你的真实天气API resp requests.get( https://api.example.com/weather, params{city: city}, timeout3 ) resp.raise_for_status() data resp.json() return SkillResult(successTrue, data{ city: city, temperature: data.get(temperature), condition: data.get(condition), humidity: data.get(humidity), updated_at: data.get(updated_at), })validator.py实现def check_weather(result: SkillResult, context: dict) - SkillResult: if not result.success: return result data result.data # 校验返回的城市是否和请求一致 if data.get(city) ! context[request_params].get(city): return SkillResult(successFalse, error城市不匹配) # 温度应该在合理范围内 temp data.get(temperature) if temp is None or not (-50 temp 60): return SkillResult(successFalse, error温度数据异常) if not data.get(condition): return SkillResult(successFalse, error天气状况缺失) return result4.3 Agent如何感知并调用技能这一步是整个方案的关键。我采用的思路是不要把所有技能一次性塞给模型而是先用一层轻量的意图路由筛出候选技能再把候选技能的声明转成tool definition传给模型。这样做的好处有两个。第一context里塞的tool定义少了模型选择准确率会显著提升。我做过对比实验在工具数量超过8个以后模型的选错率会明显上升把候选集从20个缩减到2-3个之后准确率几乎翻倍。第二意图路由本身可以做得很快用一个小模型甚至基于规则都可以不会给整体响应增加太多延迟。示例代码def build_tools_for_user_query(query: str) - list[dict]: # 先做意图预筛把候选技能缩小到2~3个 candidate_skills intent_router(query) # 再把候选技能的声明转成openai function calling格式 tools [] for skill in candidate_skills: tools.append({ type: function, function: { name: skill.name, description: skill.description, parameters: { type: object, properties: { entity: {type: string, description: entity} for entity in skill.required_entities }, required: skill.required_entities, }, }, }) return tools4.4 把技能结果安全地拼回对话模型调用完技能之后拿到的是工具返回的JSON。这一步很容易犯的错是直接把JSON丢给模型然后让模型自由组织语言。这会导致模型偶尔会把一些内部字段、错误码之类的信息泄露给用户。我的做法是在把工具结果交给模型之前先经过一个结果整理层。这个层会根据验证器的输出把结果转换成一段适合模型阅读的摘要同时过滤掉敏感字段和调试信息。比如天气查询的结果进入模型上下文之前会被改成这样工具执行结果(weather_query): 上海当前温度25℃多云湿度60%数据更新时间2025-06-15 14:30这样模型拿到的是一个已经整理好的纯文本一方面减少了token消耗另一方面也没机会把底层字段泄露出去。5. 常见问题与排查技巧实录5.1 技能误触发模型在无关问题上调用了技能这是我在项目初期遇到最多的问题。用户明明在问你们公司几点下班模型却调用了订单查询技能结果自然是一通乱答。这类问题的根因通常不在模型本身而在技能的trigger定义太宽泛。比如description里写了查询订单信息模型可能把我们的工作时间里的订单两个字也关联上。解决办法我总结了一套技能description要写功耗句式明确强调仅当用户明确表达这个动作时才使用做好意图预筛无关query直接不给模型透出该技能的tool定义加上一个兜底的no_skill技能让模型在不确定时不调用任何工具直接回答这套组合拳下来误调用率能下降一个数量级。5.2 参数解析失败模型填了不存在的城市名模型在抽取实体的时候偶尔会发挥不稳定比如用户说帮我查一下北京的天气模型却把参数填成北京市朝阳区朝阳北路。大部分时候不影响功能但有些严格的API会直接报错。我的处理策略是在验证器里做一次容错归一化。像城市名这种有限集合的实体可以维护一个别名映射表在执行前先做一层标准化。如果标准化失败再走向用户确认的路径而不是直接报错。这种先容错再确认的设计比直接让系统崩溃要优雅得多。5.3 验证器误伤把正确的结果拦截了验证器设计得太严格也会有问题。我就遇到过因为温度字段是字符串25.0而不是浮点数我的校验逻辑直接用isinstance判断结果把正常数据误判为异常。所以后来我把验证器的原则定为只校验业务安全相关字段不过度约束数据格式。数据的类型转换放在执行函数内部解决验证器只关心这个结果能不能安全地展示给用户。另外验证器本身要有日志输出和监控。每一次验证失败都要记录下来这样一旦出现大面积误伤你能在第一时间发现规律而不是等用户投诉了才去排查。5.4 技能调度冲突多个技能同时命中当你的技能库超过20个之后会出现一个新问题用户的一个问题可能同时命中多个技能的触发条件。比如帮我看看附近有什么适合周末去的餐厅可能同时命中美食推荐和地点查询两个技能。这时候需要引入一个优先级机制。我目前的方案是在skill.yaml里加一个priority字段命中多个技能时默认选最高优先级的一个执行。另外还可以做意图置信度加权用意图分类模型的打分结果来辅助决策。目前我的经验是优先级手动配置配合置信度阈值已经能覆盖绝大多数冲突场景。更复杂的编排就用前面提到的依赖机制手工控制没必要在这一层做得过重。5.5 技能调用超时与限流工具调用的超时是个硬指标。模型在等待工具结果时如果一直等不到既不会自己重新生成回复也不会放弃等待整个会话就一直卡着。所以我给每个技能都配了独立的超时时间并且在超时后执行fallback策略超时时间一般设置为核心接口平均耗时的3~5倍超时后的fallback不是直接报错而是返回暂时没有查到结果请稍后再试有些技能支持重试一次重试必须排队不能并发打爆下游接口此外针对那些调用外部API的技能我还会在技能层做一个简单的令牌桶限流防止某些异常流量把外部服务打挂。5.6 常见问题速查表问题现象可能原因排查步骤解决方案模型在无关问题上调用技能trigger描述过于宽泛查看技能命中日志收紧description增加意图预筛工具结果明显错误但模型照单全收缺少验证器或验证器过弱检查验证器日志强化校验规则拦截异常数据用户多轮对话中技能调用频繁失效context丢失了关键参数检查上下文传递逻辑在context中用session级字段保存对话关键实体同一问题每次调用的技能不一样模型随机性太高查看temperature设置降低temperature增加决策缓存新增技能后老技能行为发生变化tool定义间存在语义干扰对比新增前后的命中日志优化权重与触发条件必要时做技能下线接口偶尔抖动导致用户体验差没有重试与降级策略查看接口错误率增加重试配置fallback文案6. 效果实测与性能优化记录6.1 技能命中率的量化结果方案上线后我专门做了一轮对比测试同样一批测试问题样本约200条分别跑传统大工具集方案和技能层方案统计工具调用准确率。结果差异非常明显。传统方案的工具命中率在82%左右而技能层方案在95%以上。误调用率从之前的12%降到了3%左右。尤其在一些模糊表达的场景比如东西还没送到技能层方案能更准确地判断出用户意图是查物流而不是查订单这在老方案里经常搞混。6.2 响应延迟与成本控制技能层方案还有一个意外的收获平均响应延迟降了。原因是每次只有2~3个候选工具的tool定义会进入模型上下文而不是全部工具。tool定义少了token就少了模型的处理速度自然更快。实测下来在同等复杂度的查询场景下token消耗下降约30%。如果你们的服务是走API按token计费这个优化带来的成本节省是非常可观的。6.3 进一步优化技能缓存与结果复用在系统稳定运行一段时间后我开始关注另一块优化空间相同参数、相同技能的执行结果是否可以复用答案是可以。比如天气查询这种强时效性的技能可以设置5-10分钟的缓存但订单查询这种数据强关联用户和时间的技能就不能随便缓存。所以我把技能分成三类强时效型查询天气、汇率可配置短TTL缓存用户绑定型查订单、改地址不缓存偶尔用session级记忆纯计算型算折扣、算运费只要输入不变结果就可以复用这个分类策略帮助我们进一步降低了外部API的调用量。6.4 引导式调参与技能灰度最后一个实战经验是关于技能上线流程的。技能的改动看起来小就改一个yaml、一个函数但如果改坏了影响的是所有走这个技能的会话。所以我这边的规范是所有技能改动必须先经过灰度比如先让5%的流量走新版本观察日志里技能命中率、执行成功率、验证器失败率这三个指标没有异常再逐步放量到全量。我踩过最惨的一次坑是改了一个地址修改技能的验证规则忘记考虑到某些老用户的地址格式导致大面积校验失败。从那以后每次改动我都要先在离线脚本里跑一遍历史样本确保回归通过再上灰度。7. 给后来者的一份实用清单7.1 起步阶段该从哪些技能入手如果你正准备给Agent引入技能层不用一上来就规划几十个技能。我建议从这三个最基础的技能开始试水知识查询类查商品信息、查文档、查FAQ状态查询类查订单、查物流、查账户余额简单操作类修改备注、收藏商品、订阅订阅提醒这三个类别的共同点是动作明确、输入简单、结果边界清晰非常适合用来验证你的技能层设计。跑通之后再慢慢加复杂技能。7.2 设计技能时的5条经验准则第一条一个技能只做一件事。如果发现技能描述里出现了和字就说明它需要拆分了。第二条fallback文案必须人话化。用户看到服务暂不可用和抱歉我暂时没办法帮你取消订单你可以稍后再试或联系人工客服体验完全不同。第三条验证器绝不省略。哪怕是一行判断也值得写。它不只是保护模型的输出质量也是在保护你的业务安全。第四条技能的description要让模型一看就懂而不是让人一看就懂。多站在模型的角度想这个词在前面的语境里会不会有歧义。第五条所有技能执行都要有trace日志。出了问题没有日志几乎等于没法排查。7.3 后续可以怎么扩展技能层稳定运行之后我已经开始往两个方向探索了。一个方向是技能组合的自动编排把当前依赖声明机制升级成可配置的DAG流程让复杂任务可以像流水线一样跑。另一个方向是技能效果闭环记录每次技能执行的最终反馈用户是否满意、问题是否解决然后据此周期性优化技能的触发条件和执行策略。这两个方向目前都还在探索阶段但路径已经比较清晰了。最后说点个人体会。我从最初几个function走天下到现在一套技能库支撑几十个场景最深的感悟是Agent落地的关键从来不是让模型变得更聪明而是通过工程手段把模型的聪明用在正确的地方。技能层的本质就是给模型的自由度划上合理的边界边界清晰了Agent才能真正在一个稳定可控的范围内发挥价值。