AI Agent技能库工程化实践：从Prompt乱象到可控工具调用

如果你最近在研究AI Agent一定遇到过类似的困局模型什么都能聊但一落到具体业务就抓瞎。我去年接手了一个智能客服项目最初的方案是“一个大模型 一套大而全的Prompt 一份工具列表”结果模型频繁选错工具、传错参数维护成本高到怀疑人生。后来我把整个Agent的能力体系重构为“agent-skills”技能库项目——把每一个业务能力封装成独立技能模块每个技能自带描述文件、参数校验、测试用例和调用日志让Agent既能“知道自己会什么”又能“按规矩调什么”。这个项目解决了我在真实业务里遇到的大部分稳定性问题如果你的工作也涉及Agent落地、智能客服、自动化办公或RPA类场景这篇文章值得你看下去。我用agent-skills模式跑通订单查询、物流追踪、售后处理、库存查询等多个客服场景后最大的感触是Agent能力的核心瓶颈其实不在模型选得多强而在于你能否把能力“工程化”。技能库表面上是一堆目录和脚本本质上是一套控制LLM行为边界的机制。下面我会从为什么拆技能、技能文件怎么设计、注册调用怎么实现、以及我踩过的坑这几个维度完整复盘这个项目的每一个关键细节。1. 为什么我把Agent能力拆成了技能库1.1 最初的问题一个巨型Prompt驱动的Agent如何失控项目刚启动时我采用了最主流的做法把客服业务里的所有动作——查订单、查物流、发优惠券、登记售后——全部写成函数塞进一个大数组里作为tools传给模型同时在一份系统Prompt里强调“当用户询问订单信息时调用order_query当用户询问物流时调用logistics_query”。听起来没什么问题但真跑起来全是坑。第一个坑是工具列表膨胀。业务场景一多工具超过了十五个模型开始频繁选错。比如用户问“我的包裹怎么还没到”模型居然去调了coupon_query。我仔细看了调用日志发现模型不是不聪明而是工具描述之间的区分度太低两个工具名称里都有query描述里都有“查询订单信息”LLM根本分不清边界。第二个坑是参数幻觉。模型经常把自然语言里的信息直接填进参数比如order_id字段它传“用户说他的订单号是三个七”这根本不是合法的订单号。第三个坑是维护成本极高改一个工具的描述可能影响其他工具的选择逻辑回归测试困难。我实测过一个数据工具数量从8个上升到17个时工具选择的准确率从95%左右掉到82%以下。对一个客服系统来说选错工具意味着直接给用户错误答案这是不可接受的。后来我意识到问题不在于“工具不够多”而在于“工具没有被结构化地组织”。1.2 技能Skill模式的本质从“一个大脑”到“大脑工具箱”我换了个思路看待这件事。一个刚入职的新员工你给他一份公司手册他能干的事非常有限。但如果你带他走遍仓库、认全每台设备、每样工具贴在什么位置、什么场景下用哪个他很快就能独当一面。Agent也是一样它不能只靠一份Prompt里的文字描述去“想象”如何工作它需要一个真实的、结构化的工具箱。agent-skills项目做的就是这件事。它把每个业务能力封装成独立的Skill每个Skill包含四个绑定在一起的部分给LLM看的能力说明书SKILL.md、给程序看的参数约束schema.json、实际执行逻辑skill.py、以及保证回归的测试用例tests。这个模式和很多Agent框架里简单的tools列表最大的区别在于tools列表只有“名字描述函数”而Skill把“什么时候用、参数怎么传、调用后怎么验证、坏了怎么排查”全部固化了下来。我当时做了一个类比tools是一个工具箱里的各种零散零件Skills是一整套带说明书和质检标准的工具卡。前者适合demo后者适合生产。如果你只是自己玩一玩tools列表完全够用一旦要接真实业务面对真实用户、真实订单数据、真实售后流程你需要的是一套能让工程团队和LLM都理解的能力规范。1.3 agent-skills项目的整体目标与设计红线做agent-skills之前我先给自己定了三条设计红线后来证明这几条红线帮我避开了很多麻烦。第一条技能之间不允许互相依赖。也就是说一个Skill不能直接import另一个Skill的内部函数所有技能只能通过统一执行器间接协作。这样做的好处是技能可以独立替换、独立升级坏了也不至于连环崩溃。第二条每个技能必须自带SKILL.md和schema.json。没有说明文档和参数约束的技能不允许注册进技能库这是硬校验不是自觉遵守。第三条每个技能都要有日志和测试用例。技能执行必须输出结构化日志包含技能名、调用参数、耗时、结果状态方便线上排查测试用例则保证后续改动不破坏已有能力。这三条红线在早期看起来很麻烦尤其是给每个技能写说明和测试特别耗时。但项目运行了三个月后我越来越觉得这是最值得的一笔投入。因为客服场景的Agent一旦出错影响的不只是用户体验还有后续工单、订单状态、售后流程等一系列连锁反应。能力可以扩展得慢一点但不能脏乱差地膨胀。2. 技能库的目录结构与技能文件设计2.1 一个技能长什么样SKILL.md、skill.py、schema.json、tests我在项目里采用了非常直接的目录结构每个业务能力占一个文件夹所有文件夹放在skills根目录下。下面是一个订单查询技能的标准结构agent-skills/ ├── skills/ │ ├── order_query/ │ │ ├── SKILL.md │ │ ├── skill.py │ │ ├── schema.json │ │ ├── requirements.txt │ │ └── tests/ │ │ └── test_order_query.py │ ├── logistics_query/ │ │ └── ... │ └── coupon_send/ │ └── ... ├── registry/ │ └── index.yaml ├── core/ │ ├── loader.py │ ├── executor.py │ └── logger.py └── main.py你可能会问为什么不把schema直接写在SKILL.md的YAML头里还要单独放一个schema.json我一开始也是这么干的但后来发现SKILL.md是给LLM读的越轻量越好而schema.json是给程序做参数校验用的需要严格、完整、可机器执行。两者混在一起会导致Markdown文件里塞大量JSON既影响LLM理解也容易在解析时出错。SKILL.md的核心作用是告诉LLM“你什么时候该用我、用了我会得到什么、我需要你提供什么”。skill.py是真正干活的函数我统一约定它对外暴露一个run(params)入口接收字典参数返回字典结果。schema.json约束参数格式比如订单号必须是特定前缀加数字、手机号必须是11位、时间字段必须是timestamp。tests目录是给工程人员用的回归保护用pytest跑每次改动技能库前先跑全量测试。一个技能文件夹里的四个部分各司其职谁出问题都能快速定位。比如用户反馈“Agent乱用技能”先看SKILL.md写得好不好反馈“技能报了参数错误”看schema.json的约束反馈“执行结果不对”看skill.py的业务逻辑和测试用例。这种结构让整个项目好查、好改、好交接。2.2 SKILL.md怎么写LLM能读懂的能力说明书SKILL.md是整个技能库的“灵魂”写法好坏直接决定Agent的技能选择准确率。我踩过很多次坑之后形成了一套比较稳定的写法规范。核心原则是写清楚触发条件、输入要求、输出结构并且一定要写“绝不使用”的场景。下面是我在order_query技能里用的一份SKILL.md示例--- name: order_query version: 1.0.0 description: 查询用户的订单状态、发货时间与售后进度。 triggers: - 用户询问“我的订单到哪了” - 用户询问“货发了吗” - 用户询问“订单什么时候到” - 用户要求查看最近订单状态 non_triggers: - 用户询问“怎么退货” - 用户询问“退款到账时间” - 用户询问“优惠券怎么领” inputs: order_id: type: string description: 平台生成的订单号以ORD开头 required: true user_id: type: string description: 用户唯一标识 required: true outputs: - 订单当前状态 - 预计送达时间 - 最近物流节点 example: 用户说我的订单ORD20240115001还没发货吗 - 输入order_idORD20240115001, user_idU100234 ---写这份文档的时候我特别强调triggers和non_triggers。LLM在选择技能时本质上在做一道语义匹配题描述里给出正面触发词能帮它命中正确技能给出反面排除项能帮它避开相似技能。比如order_query和return_apply配置单看“查询”两个字很容易混淆但order_query里明确写了“不处理退货”return_apply里写了“不查询物流状态”两个技能的边界一下子就清晰了。另外我强烈建议在description里写一句“查询类动作不会修改任何数据状态”这句话在Agent决定是否调用某些只读技能时非常有用。部分场景下Agent会为了避免改变系统状态而选择不调用技能有了明确的只读声明它能放心大胆地使用。2.3 参数Schema用JSON Schema约束Agent不要乱来LLM生成参数时经常出现“多传、漏传、错传”的问题。我在不做参数校验时遇到过模型把用户输入的订单号“我的订单号是三个七”直接塞给order_id也遇到过把两个参数合并成一个传的情况。用JSON Schema做参数校验之后这些问题大幅减少——因为非法参数会被直接拦截而不是带病进入业务逻辑。我针对order_query技能写的schema.json大致如下{ $schema: http://json-schema.org/draft-07/schema#, type: object, properties: { order_id: { type: string, pattern: ^ORD[0-9]{12}$, description: 平台订单号ORD加12位数字 }, user_id: { type: string, minLength: 6, maxLength: 32, description: 用户唯一标识不能为空 } }, required: [order_id, user_id], additionalProperties: false }很多人会忽略additionalProperties这个字段但它极其重要。默认情况下JSON Schema允许额外字段模型有时候会自己发明一个叫“order_detail”的参数塞进去如果不把它设成false这些垃圾参数会被带进skill.py导致业务代码里到处都是防御性判断。设成false以后不合规的参数在入口处就被挡掉代码清爽很多。再补充一个细节pattern校验对订单号这类格式稳定的字段非常有效但对用户ID、昵称等自由文本就别上太严的pattern了。我一开始给user_id加了“必须是数字”的pattern结果大量存量用户ID带字母频繁报错。参数校验的粒度要和真实数据匹配该严的地方严该松的地方松。3. 技能注册、调用与编排的工程实现3.1 技能发现与加载动态扫描 index.yaml技能库搭建初期的核心问题是怎么让Agent“知道自己会什么”。我调研了许多Agent框架发现有的把技能列表写死在一个大数组里有的靠向量数据库做实时检索。写死数组简单但扩展性差向量检索重但适合技能数量很大的情况。作为一个中间态方案我用“目录自动扫描 registry/index.yaml 索引”的组合兼顾了扩展性和可控性。目录自动扫描的逻辑很简单程序启动时遍历skills目录下的所有子目录每个子目录必须包含SKILL.md、schema.json、skill.py否则跳过并输出告警日志。这样新增一个技能时只需要新建一个文件夹无需修改注册代码。index.yaml则用于补充扫描无法获取的元信息比如技能版本、维护人、分组、启停状态。skills: - name: order_query version: 1.0.0 group: order enabled: true owner: team_order - name: logistics_query version: 1.1.0 group: order enabled: true owner: team_logistics - name: coupon_send version: 0.9.0 group: marketing enabled: false owner: team_marketingenabled字段是我后来加上的。早期没有这个字段时已经开发但未验收的技能会直接被LLM使用出过几次事故。加了enabled字段后新技能默认false验收通过才改成true相当于多了一道人工审核闸门。group字段则用于打标签Agent在规划时可以先按业务分组缩小候选技能范围减少选择压力。加载器还有一个容易被忽略的细节技能目录的扫描顺序不能影响结果。我用字典存储技能名到Skill对象的映射不依赖文件系统顺序这样即使在多台机器上部署同一份代码加载出来的技能集合和技能行为都是一致的。3.2 统一执行器Agent调用技能的接口设计技能加载只是第一步真正麻烦的是让Agent以统一的方式调用技能。我设计了一个核心执行器core/executor.py对外只暴露一个execute方法。所有技能的调用都走这个入口不在业务代码里直接调skill.py。# core/executor.py import json import jsonschema import time class SkillExecutor: def __init__(self, registry): self.registry registry def execute(self, skill_name, params, request_id): skill self.registry.get(skill_name) if skill is None: return {status: error, error: skill_not_found, data: None} try: jsonschema.validate(params, skill.schema) except jsonschema.ValidationError as e: return {status: error, error: finvalid_params: {e.message}, data: None} start time.time() try: result skill.implementation(params) return {status: success, data: result, error: None} except Exception as e: return {status: error, error: str(e), data: None} finally: duration time.time() - start logger.log_execution(skill_nameskill_name, paramsparams, resultresult, durationduration, request_idrequest_id)这段代码有几个细节我后来才体会到价值。第一参数校验放在技能执行之前而不是在skill.py里做保证了所有技能的错误行为一致。第二返回值统一为{status, data, error}三元组LLM能轻松消费不需要自己去猜返回结构。第三finally里的日志记录无论如何都会执行哪怕技能抛异常调用链也能在日志里找到。统一执行器还有一个好处它让所有技能都具备“可观测性”。每次调用都会记录调用了哪个技能、传入了什么参数、耗时多长、返回了什么。这些日志既是排查问题的依据也是后续做技能质量评估的数据基础。我甚至从这个日志里统计出哪些技能经常被调用、哪些技能老是报错、哪些技能调用耗时过长然后针对性优化。3.3 多技能编排让Agent自己决定调用顺序单个技能的调用解决了“怎么干一件事”但真实业务里用户一句话往往需要多个技能配合。比如用户问“我昨天买的手机怎么还没发货如果再不发货我就退了。”这句话里面既有订单查询的需求又可能触发退货登记的需求。如果Agent只调一个技能很难给出完整回复。我采用的是“LLM规划 顺序执行”的轻量编排机制。模型收到用户问题后先根据技能库生成一个执行计划计划是技能名和参数的列表然后交给Executor逐项执行。我封装了一个编排函数def run_agent_plan(user_question, skill_names, executor, request_id): plan llm_planner.create_plan( questionuser_question, available_skillsskill_names ) results [] for step in plan[steps]: result executor.execute(step[skill], step[params], request_id) results.append(result) if result[status] error: break return results这里最关键的并不是代码而是plan的生成策略。我早期让LLM自由发挥结果它经常生成不存在的技能名或者在第一步失败后仍然继续执行后续步骤。后来我在planner的prompt里加上两条硬规则只能从候选技能列表里选择技能名第一步失败则立即终止整个计划并回复用户“暂时无法完成”。编排层同样需要日志。我会把每一步的计划、实际执行结果、每一步耗时都记录下来。这样如果用户说“机器人答非所问”我可以直接回放整个计划执行过程快速定位是哪一步的判断出了问题。相比黑盒式的Agent反馈这种白盒可观测的模式在团队协作和故障定责上优势明显。4. 实操过程从零跑通一个订单查询技能4.1 需求梳理与技能边界确定用一个具体案例来把前面的设计串起来我需要在agent-skills里新增一个“订单查询”技能。需求来自客服团队——用户高频问题之一是“我的订单到哪了”“发货了吗”“多久能到”客服希望机器人能直接查订单状态并回答。我梳理出这个技能的边界查询范围订单状态、预计送达时间、最近物流节点。不处理退款、退货、改地址、催发货有另两个技能负责。输入参数order_id和user_id两者都必填。数据来源内部订单系统的HTTP接口。边界确定后我把它写进SKILL.md的triggers和non_triggers里。这一步不能省因为客服场景下用户表达极其口语化“货呢”“我的件儿呢”“怎么还没到”这些说法都要在triggers里覆盖到。我甚至从历史工单里拉了500条真实用户问题人工过了一遍把高频表达都提炼出来写进触发词。4.2 创建技能目录并编写实现我按标准结构创建了文件夹skills/order_query然后写核心实现。技能实现本身并不复杂关键在于接入内部订单接口时的封装方式。我将外部API调用和参数解析分离避免在skill.py里堆太多杂逻辑。# skills/order_query/skill.py import requests API_ENDPOINT https://api.internal.example.com/order/status def run(params: dict) - dict: order_id params[order_id] user_id params[user_id] resp requests.get( API_ENDPOINT, params{order_id: order_id, user_id: user_id}, timeout3, ) resp.raise_for_status() data resp.json() return { order_status: data.get(status), estimated_delivery: data.get(estimated_delivery), recent_logistics: data.get(recent_logistics), raw_text: f您的订单当前状态为{data.get(status)}预计送达时间{data.get(estimated_delivery)} }这里有一个重要的注意事项不要在skill.py里硬编码密钥或敏感配置。我把API的base_url和鉴权信息放在环境变量里技能代码从os.environ读取。这样技能库可以自由地在不同环境间切换不用改一行代码。另外接口调用设置了timeout3避免第三方接口挂起导致Agent长时间无响应。你会发现skill.py里没有做任何参数校验逻辑因为校验已经由executor通过schema.json完成了。这让我在写业务函数时非常轻松只需要信任入参是合法且完整的专注处理数据获取和结果组装。4.3 注册技能并验证加载链路技能写完以后需要先做本地校验再把它正式注册启用。我在项目里写了一个validate命令它会自动检查技能的SKILL.md格式、schema.json合法性、skill.py能否被正常导入、测试用例是否通过。python main.py validate skills/order_query执行后发现有两个问题。第一个问题是schema.json的order_id pattern写成^ORD[0-9]{12}$但测试数据里的订单号是ORD开头加14位数字校验失败。这个不算bug是我对数据口径理解不对。第二个问题是测试用例里mock接口返回格式和真实接口不一致导致返回的estimated_delivery字段解析出错。修正这两处后validate全部通过。注册完成后我立即启动了一个最小版的Agent服务在本地用真实用户问题做了一次端到端对话测试。我输入“你好我的货怎么还没到”Agent先通过LLM判断这属于order_query技能然后从对话中抽取出参数发现user_id缺失主动追问“请提供一下您的手机号或用户ID”拿到参数后调用了order_query并回复查询结果。整个链路在本地跑通。4.4 线上日志与调用链观察技能上线运行后我重点观察执行器的日志。这是agent-skills项目里最让我有成就感的部分——不再需要靠猜来定位问题。一次普通的订单查询调用日志大概长这样request_idreq_20240315_001 skillorder_query actionexecute statussuccess duration187ms request_idreq_20240315_001 skillorder_query params{order_id: ORD202403150001, user_id: U100234} request_idreq_20240315_001 skillorder_query result{order_status: shipped, estimated_delivery: 2024-03-20, recent_logistics: 已到达杭州转运中心}从这份日志里我能清晰看到某次请求调用了哪个技能、传了什么参数、多久返回、返回了什么。如果用户投诉“机器人回答错误”我直接按request_id在日志系统里检索几秒钟就能还原现场。这样的日志在任何Agent项目里都应该成为标配但在实际接触过的很多团队里Agent调用是没有日志的出了问题只能复现非常痛苦。5. 常见问题与排查技巧实录5.1 技能匹配错乱为什么模型总选错技能我在技能库上线初期最头疼的问题是“模型选错技能”。用户问退货它却调了订单查询用户问物流它却调了库存查询。排查了一段时间后我发现主要原因有两个一是SKILL.md里的description太泛比如只写“查询订单信息”没有写明“仅查询不包含退货和物流”二是相似技能的边界没有说清楚候选技能越多这个问题越严重。解决思路是给每个技能增加negative triggers和非目标场景描述。比如order_query里明确写“不处理退换货、不处理退款、不处理物流轨迹实时追踪”logistics_query里写“只处理物流节点信息不处理订单支付状态”。这样增加描述后技能选择准确率从约86%提升到了94%。我还做了一个小实验把技能名也改成更语义化的方式比如把order_query改名为query_order_status模型的选择准确率没有显著变化说明问题主要出在描述内容而不是命名方式。5.2 参数校验失败模型传参太随意怎么办参数校验失败是上线第一天就出现的问题。模型在抽取用户输入时经常漏掉字段或者把“我的订单号”这类描述文本直接当作订单号。我试过在prompt里反复强调“只能传订单号”效果有限。后来我在executor前面加了两层处理。第一层是参数抽取的独立prompt让LLM先针对用户问题做字段抽取再决定调用哪个技能第二层是正则兜底比如订单号字段先尝试匹配ORD[0-9]{12,14}如果没有匹配到就直接返回需要用户补充信息的提示而不是把脏数据传进技能。这两层合起来让参数校验的失败率降低了一个数量级。5.3 并发冲突与技能状态污染技能数量多起来以后我碰到过一类比较隐蔽的问题Agent的某个技能在一定并发量下会偶发返回错误结果。排查了很久最终定位到coder在skill.py里使用了一个模块级全局变量缓存用户信息导致不同用户的请求之间产生了数据污染。这个问题本质上违反了我在项目初期定的“技能无状态”红线。修复方案是把所有请求相关的数据都放到run(params)局部作用域里禁止使用模块级可变变量。为了长期防住这个问题我在code review规范里加了一条skill.py内不允许出现全局可变对象。同时把并发测试纳入了标准测试流程模拟多个不同用户同时调用同一个技能验证结果是否互相干扰。这个教训让我深刻体会到设计红线必须通过工程规范和测试用例来固化否则很容易被后来的改动突破。5.4 排查Agent技能问题的三板斧如果有人问我在agent-skills项目里最实用的排查方法是什么我会回答日志、最小复现、降级方案。第一板斧是日志。每个技能调用都带request_id日志里必须有技能名、参数、结果、耗时。没有日志的Agent项目排查问题基本靠猜。第二板斧是最小复现。发现某个技能有问题后我通常会写一个几十行的脚本直接调用executor.execute绕开LLM和编排层确认问题是出在技能本身还是出在LLM的选择/规划环节。这一步能快速切分责任边界。第三板斧是降级方案。当技能依赖的第三方服务不可用或者技能本身报错时Agent要能从“调用技能模式”降级为“人工兜底模式”返回一句“暂时无法查询已为您转接人工客服”而不是胡编一个答案。5.5 避坑清单agent-skills开发速查表我把项目里遇到的高频问题整理成了一张速查表开发新技能时可以逐条对照问题根因对策技能被选错SKILL.md描述太宽泛缺少边界写清楚triggers和non_triggers举具体例子参数被传错缺少JSON Schema校验为每个技能配置schema.json并启用additionalProperties: false技能执行超时外部接口慢或无超时限制所有HTTP调用设置timeout并在executor外增加超时熔断并发返回脏数据skill.py使用全局可变变量技能无状态化状态只放params局部作用域新技能没启用index.yaml未更新新技能默认enabled: false验收后手动开启日志查不到没传入request_id或日志级别不对链路入口统一生成request_id日志落盘到独立索引测试没覆盖只测了主路径补边界输入、异常返回、并发场景测试我建这个项目的过程中几乎把表里每一行都踩过一遍。这些坑单独看都不复杂但组合在一起往往会让一个Agent项目从“demo能跑”到“生产可靠”之间隔着一道鸿沟。而agent-skills的价值正是把这条路上所有容易出问题的点都变成可以格式化的工程规范。6. 这个项目的未来扩展与我的个人体会技能库模式跑通以后我发现它的想象力远不止订单查询。首先技能可以跨项目复用。同一套订单查询技能既可以用在客服Agent里也可以用在后台运营的数据助手Agent里只需要复用同一份技能文件夹不用重新实现。其次技能可以做得更细。比如把“订单查询”继续拆成“订单状态查询”和“物流轨迹查询”按业务场景动态组合。再次技能还能做灰度发布——新版本技能先在部分流量中试运行观察日志和成功率再逐步放量这对生产环境非常友好。如果后续继续深化我可以为技能库建设一套“技能质量评估体系”。比如用自动化测试集跑全量技能统计每个技能的成功率、平均耗时、参数校验失败率并按周输出质量报表。这样技能库就不再是一堆静态文件而是一个可持续运营的能力资产。我个人在实际操作中的体会是技术方案本身没那么高深真正难的是改变团队对Agent能力的认知。以前大家在Prompt里堆词寄希望于模型“更聪明一点”agent-skills把问题转化为工程问题让每个能力都有边界、有校验、有日志、有测试。这个转变带来的稳定性提升立竿见影。如果你现在也正被Agent的乱调用、参数幻觉和排查困难困扰我建议你不要急着加更多Prompt先把能力拆成一个个干净、可测试、可观测的技能。最后再分享一个小技巧每开发完一个技能强制自己写一个“这个技能绝不做什么”的清单放进SKILL.md你会发现模型后期选错技能的概率低到超乎预期。