★ FEATURED ARTICLE 做AI Agent开发这一年多我最大的感受是模型的推理能力早就不是瓶颈了真正决定一个智能体好不好用的是它手里到底握着多少种能稳定执行的技能。很多人把agent当成一个能聊天的prompt包装器结果做出来的东西只会接话不会干活。于是我开始认真琢磨一个问题能不能把agent的能力拆成一个个独立、可复用、可插拔的技能像工具箱一样按需装配这就是agent-skills项目最初的出发点。这个项目不是什么魔改模型也不是啥高深框架它解决的是一个特别朴素的工程问题当你决定让智能体去处理真实任务时你该怎样设计一套技能体系让agent看得懂、调得动、出错还能兜底。如果你正在做客服机器人、自动化助手、企业内部知识问答这类应用或者你手上已经有一个基于对话模型的智能体但总感觉它不太会干活这篇文章就是写给你看的。我会把技能体系的设计思路、实现细节、踩坑经验一条条拆开讲尽量让不同技术基础的人都吃得下。1. 为什么说技能系统是 Agent 的底层基建1.1 从会思考到会干活中间隔着一层技能层先想一个问题同样一个大模型为什么有人用它写邮件只能写出干巴巴的模板有人却能让它自动查文档、拉数据、生成报表、回完邮件还能顺手跟进待办差距不在模型本身而在你给它搭了多大的台子。模型本质上是一个推理引擎它可以根据上下文做出判断但它本身不持有任何执行能力。你要它查天气它并不知道气象接口在哪你要它帮你改个日程它也不知道日历服务的地址。模型能做的是告诉你该怎么查真正动手去查还得靠一套把它和外部工具、内部服务连接起来的东西——这就是技能层。我把技能层理解为agent的手和脚。推理是大脑技能是肢体。大脑负责决策该做什么技能负责执行把它做完。如果只有大脑没有手脚再聪明的agent也只能停留在给你建议的层面反过来如果技能足够丰富、足够稳定哪怕底层模型弱一点agent的整体可用性也能被拉上去。1.2 agent-skills 项目到底定位在哪里agent-skills是一个面向智能体的技能管理机制它的定位不是某个单一技能的实现而是技能的技能的框架。说得直白点它回答的是三个工程问题第一技能怎么描述。一个技能要被模型正确调用必须有清晰的名字、用途、参数说明和返回格式模型才能从一段自然语言对话里判断该用哪个技能、传什么参数进去。第二技能怎么组织。技能不是一堆散落函数它需要分类、检索、依赖管理。当技能多了得有一套机制让agent快速找到对的技能而不是在几百个候选里瞎猜。第三技能怎么执行与兜底。调用技能不是万能药接口会挂、参数会错、模型会误判。技能层必须包含超时、重试、降级、报错反馈这些机制保证单个技能的失败不会把整个agent拖垮。这三个问题合起来才是一个完整的技能系统。单纯写几个工具函数挂上去那是接口清单不是技能系统。1.3 技能调用和传统工具调用有什么区别有人会说这不就是function calling吗这两者确实有交集但不是一个层面的东西。function calling是模型与外部函数之间的一次性调用协议它解决的是模型怎么把参数传给函数这一层问题而技能系统要解决的是agent面对一个开放任务时怎么在一大堆能力中做选择、编排、执行、恢复这个问题。前者是局部通信协议后者是全局能力管理。举一个生活化的类比。function calling像是你从工具柜里单独拿一把螺丝刀出来用技能系统则是给整个工具柜装了一套编号、检索、借用登记和损坏上报制度。没有这套制度工具多了必然乱套你找不到合适的工具拿错了也没人发现坏了更没人管。所以我在做agent-skills的时候一直把工程思维放在第一位。先想清楚架构再填具体技能最后才是接模型。顺序反了后面全是补窟窿。2. 技能体系的设计思路先建模再填肉2.1 技能清单从哪来需求倒推法很多开发者动手的第一步就是写技能看到什么功能就给agent加一个结果技能库膨胀得像个杂货铺。我建议反过来先看你要agent做什么任务再从任务倒推技能。具体操作是这样的把你设想中的用户对话场景一条条列出来比如用户想查本月销售额用户想统计项目的延期率用户想批量修改订单状态。每个场景都问自己三个问题这个任务要哪些外部数据要执行哪些动作完成的标准是什么答案里重复出现的部分就是你最底层的原子技能只出现在特定场景里的是领域技能需要多个技能配合才能完成的则应该先沉淀成流程模板而不是硬塞给agent让它自己编排。我见过最典型的反面案例是有人给客服agent配了超过两百个技能觉得功能覆盖越全越好。结果模型在调用时频繁选错技能因为候选太多描述之间的区分度又不够。倒推法能在源头上帮你刹住车凡是场景列不出来的技能都不该出现在首版技能库里。2.2 技能分类的三个层次给技能分类会直接影响调度效果。我在agent-skills里把技能分成三层外层是工具技能中间是领域技能内层是策略技能。工具技能是最底层的原子操作特点是通用、无业务含义。比如读文件、发HTTP请求、查数据库、写日志、发邮件任何场景都可能用到。它们的接口设计要尽量简短参数尽量少职责尽量单一。领域技能则是和具体业务绑定的操作。比如查订单状态计算客户流失率生成对账单。这类技能实际上是工具技能的业务封装内部可能串起多个工具调用。它们存在的意义是把模型从繁琐的步骤里解放出来——模型不需要关心订单状态这个字段要查哪张表、做哪几次过滤它只需要知道调用查订单状态并传入订单号即可。策略技能比较特殊它不直接操作外部系统而是负责agent自身的控制逻辑。比如判断用户情绪是否需要安抚决定是否升级到人工客服在多轮任务里记住当前进度。策略技能是让agent显得会来事的关键但它很难写好因为在传统软件开发里我们习惯写死规则而在agent场景里你得留给模型一定自主判断空间。2.3 技能描述的四个关键字段无论哪一层技能在定义的时候我都建议至少包含四个字段技能名称、技能描述、参数模式、执行体。技能名称要短且无歧义查订单就比订单信息查询服务好。技能描述是给模型看的说明书它的质量直接决定模型会不会在关键时刻调用这个技能——这是后面踩坑部分我会重点展开的地方。参数模式可以理解成技能的使用说明书,它告诉模型需要哪些参数、参数的类型和取值范围以及哪些必填哪些可选。执行体则是真正干活的代码或函数。有一点容易被忽视那就是这四个字段都要写入同一个技能注册表而不是分散在各处。技能名称和描述可以存在JSON配置里执行体是你代码库里的函数但两者必须能通过统一的注册机制对上号。我把这个过程叫技能落库所有技能无论写得深还是浅都先在一个地方登记再由调度器统一读取。3. 核心实现搭一套能跑的技能库3.1 技能的注册机制注册是技能系统的入口也是整套机制运转的基础。我见过有人用一张大配置文件把所有技能写进去也见过有人每个技能一个类。两种做法都行关键是注册的产物必须标准化。我自己用的方案是装饰器注册加统一的技能清单导出。每个技能实现就是一个普通函数函数上标注技能元信息启动时扫描代码目录自动把所有标注过的函数收集起来生成一份技能清单。这么做的好处是技能和业务代码放在一起内聚性强注册过程全自动不会出现忘记登记导致agent找不到技能的情况。技能清单一经生成就是只读的运行时不允许随意增删。要改技能就必须走代码变更流程重新发布。这个约束初看繁琐实际上特别重要技能层是agent稳定性的兜底如果运行时能随意改技能配置你很难区分一次agent行为异常是因为模型判断错了还是因为技能被某个请求悄悄改掉了。注册信息里我还会额外记录一个版本号和负责人。版本号用于快速定位问题负责人则提醒大家技能不是无主资产每个技能出了问题都有明确的人去处理。这在团队协作时特别关键单人开发时无所谓人一多没有责任边界就乱套。3.2 调度与执行流程技能系统里最重要的执行路径可以概括成五步意图识别、技能选择、参数提取、执行调用、结果反馈。意图识别是让模型判断当前对话需要做事的依据技能选择是让它在技能清单中挑选最匹配的候选参数提取是把用户话里的信息填进技能需要的参数槽位执行调用是真正运行技能函数结果反馈则是把技能返回的数据灌输回对话上下文让模型能基于真实结果继续回答用户。这五步我在项目里拆成了两个模块一个是决策模块负责前三步通常由大模型完成另一个是执行模块负责后两步由纯代码完成。决策和执行分离有个明显好处你可以把决策模块想象成一名聪明的调度员而执行模块是一个严格的办事窗口。调度员可以灵活变通甚至偶尔犯点小错但只要执行窗口的错误处理足够严谨整体系统的容错能力就会很强。反过来如果把每一步都交给模型模型的一个幻觉就会污染后续所有环节。3.3 参数校验与容错技能执行过程中最常出事的不是技能逻辑本身而是参数在传递过程中的变形。模型从用户描述里提取参数时经常会把日期格式写成明天或者下周五把金额加个逗号或者单位。我建议所有技能在执行前都过一道参数校验层。校验层做三件事。第一是类型检查确保输入进去的参数类型和注册表里声明的一致。第二是格式归一化把所有日期、金额、序号这类格式不统一的参数转换成统一标准。第三是必填项检查把缺失参数的技能调用挡在门外同时返回明确的提示说明缺了哪个参数而不是让它进入执行代码里报一堆语义模糊的异常。超时和重试机制也在这里做。每个技能在注册时可以标注预期的耗时等级调度器根据这个等级设置超时时间。调用失败的时候系统会自动做一次重试。但要注意重试要区分场景查询类技能重试是安全的写入类技能则必须谨慎因为重试可能造成重复提交。处理办法是给写入类技能配备幂等键同一笔操作用同一个键标记服务端拿去重才能避免重复执行。3.4 一个完整技能的实现示例理论叠了一堆看看实际代码长什么样。我用一个很常见的查订单状态技能来演示核心结构# skills/order.py from agent_skills import register, execute, SkillContext register( namequery_order_status, description查询某个订单的最新状态。当用户询问订单发货、签收、退款进度时使用。, params{ order_id: {type: string, required: True, description: 订单编号形如 ORD-2025-0001}, customer_hint: {type: string, required: False, description: 用户提供的辅助信息可能是手机尾号或姓名} }, timeout_seconds5, idempotentTrue, ) def query_order_status(order_id: str, customer_hint: str | None None, ctx: SkillContext | None None): order order_service.get(order_id, ctx.trace_id) if order is None and customer_hint: order order_service.lookup_by_hint(customer_hint) if order is None: return {found: False, reason: order_not_found} return { found: True, status: order.status, updated_at: order.updated_at.isoformat(), timeline: [e.dict() for e in order.events[-5:]] }整个技能就是一个被装饰器标记的普通函数。装饰器把元信息登记进技能注册表函数体只关注自己的业务逻辑。SkillContext里装着链路追踪信息方便出了问题回溯。注意三个细节一是description写的是当用户询问...时使用这是给模型看的调用指引比光写查询订单状态有用得多二是加了幂等标记让调度器知道这个技能可以安全重试三是返回结构里明确区分了查询不到和查询出错后者会触发重试逻辑前者不会——这个区分在实际使用中非常重要。写技能的过程其实就是一种抽象过程把一句自然语言需求逐步收敛成一份参数明确、返回规范、行为可预期的函数实现。技能写得越规范模型的调用成功率就越高。4. 踩坑实录技能系统最容易翻车的地方4.1 技能描述写不好模型根本不会用这是我在整个项目里踩得最深的一个坑。一开始我把技能描述写得很学术化比如该技能用于获取订单域对象的当前生命周期状态结果模型在用户说我的快递到哪了时完全不触发这个技能。后来把描述改成当用户询问物流、快递、发货进度时使用触发率立刻上来了。道理很简单模型的调用决策依赖语义匹配而用户表达是口语化、场景化的。技能描述必须从用户视角出发多给几个典型触发说法。我在每个技能的description里都会附上两三个典型问法示例这比任何格式规范都管用。你现在看到的query_order_status描述里就包含了订单发货、签收、退款进度这几个触发语义这就是从真实对话样本里提炼出来的。同样的道理也适用于参数描述。订单编号这种说明太弱最好写成订单编号通常以ORD开头在用户短信或商品详情页可见。模型的很多参数错误本质上是它不知道该怎么提取这些信息你给它一个明确格式线索它就能显著收敛错误范围。4.2 技能调度的冲突与优先级问题技能库超过五十个之后技能之间的混淆开始大量出现。最典型的是查订单和查售后记录这两个技能表面看都有查和订单实际业务边界完全不同。模型时常把售后相关的问题丢给查订单技能返回了一堆用户不关心的物流信息。这个问题没有一劳永逸的解法我从实践中总结了三板斧。第一板斧是划清边界在易混淆技能的描述里互相加上边界说明。查订单技能的描述里写仅查询正常订单生命周期不包含退款和售后流程该类问题请用query_after_sale_record售后技能里也写反向提示。事实证明这一点点描述约束能大幅压制模型的误选率。第二板斧是优先级分层给技能设置匹配优先级。同一条用户问题如果被两个技能同时打到较高置信度系统自动选择优先级高的那个。常见的、无关风险的查询类技能优先级低一些涉及资金、权限、写入操作的技能优先级高一些——与其让模型纠结不如规则先兜底。第三板斧是上下文覆盖执行完技能之后让模型用自己的话把结果转述给用户如果转述里出现用户提及但技能返回里没有的信息就说明技能选择可能选错了系统会记录下来作为后续调优的线索。这其实是把错误检测延后到了对话层成本低但收益直观。4.3 技能的稳定性外部服务不可靠怎么办技能执行最常见的问题不是代码bug而是下游服务不稳定。数据库偶尔慢查询接口偶尔超时推送服务偶尔延迟这些都会直接表现为技能调用失败。如果把这种偶发失败原样抛给模型模型可能产生误判甚至对用户说系统出错了体验非常差。我在执行模块里加了一层统一的结果包装无论技能内部发生了什么外层都会收到一个标准的结构包含执行状态、返回数据、错误代码和建议话术。当技能超时时外层不会把技术错误暴露出来而是把错误码映射成一句用户能听懂的话比如我现在查不到物流信息请稍后再试。这也是我在前面强调决策与执行分离的原因一旦执行模块足够稳定即便模型选技能选得不完美用户侧的整体体验仍然可控。我见过很多团队把技能执行的失败反馈直接拼进模型上下文让模型临场发挥解释错误结果错误解释五花八门完全不可预期。4.4 技能库的维护就是一座活火山技能系统上线只是开始维护才是大头。业务规则一变技能行为就得跟着改用户问题变着花样技能描述就得不断补充触发语义。我在项目里专门给技能库加了一个使用统计看板每条技能记录调用次数、成功率和平均耗时每周过一遍。看板的价值是让维护工作有据可依。调用量很少且成功率低的技能要么是描述有问题模型找不到要么是业务上根本用不到该拆拆、该调调。调用量极大但偶尔出错的技能值得投入精力做专项加固。我不建议用所有技能一视同仁的方式去维护成本太高效果也差。还有一件事是技能下线。业务下线时相关技能必须同步下线绝不能让agent调用一个已被废弃的接口。我在注册表里给每个技能加了一个enabled标记下线操作直接改配置并触发缓存刷新不用改代码重新发布。做了这个机制后再也没有出现过agent还在调用旧逻辑的问题。5. 技能系统的下一步从单兵到协同5.1 技能编排把原子技能组合成工作流技能系统跑顺之后很自然会走到下一步不再满足于单个技能的调用而是想让agent具备完成复杂任务的能力。比如处理一笔退款申请需要校验订单状态、核对金额、走审批、发通知这串动作如果让模型从头到尾自己编排出错点太多了。我的做法是把这类高频复杂流程预先编排成技能模板。模板本身不执行动作它描述的是流程每一步用哪个技能、步骤之间有哪些依赖、出错时跳转到哪个兜底分支。模型只需要识别用户意图是退款然后按模板一步步执行每一步仍然走技能调度的标准路径。模板化编排的价值在于它把不确定性从模型自由发挥降到了模板框架内选择稳定性明显提高。每次模板跑出异常都是一次优化模板的机会你只需要不断增加模板的覆盖场景就能持续提升agent应对复杂任务的能力。这个思路和传统工作流引擎有相似之处但agent场景下的模板更强调语义匹配的弹性而不是硬编码的流程分支。5.2 技能复用跨项目共享能力资产agent-skills的技能库还有一个隐藏价值它是可以跨项目复用的能力资产。打磨好的订单查询技能、用户信息核验技能、日志分析技能换个项目直接注册过去就能用只是底下连接的业务逻辑换一换。我建议团队把技能库当成一个独立的内部项目来维护由专人review新技能的加入。技能命名规范、描述格式、参数约束这些在一开始就建立好约定后续才能平滑共享。如果每个项目各搞一套技能定义风格完全不统一所谓的复用就无从谈起最后只会变成互相复制粘贴。5.3 技能质量评估别只看调用成功率最后聊一下技能质量怎么评估。很多人只看调用成功率这个指标够直观但不够全面。我会额外关注三个维度一是误用率也就是模型在不需要这个技能的时候调用了它这反映技能描述边界是否清晰二是恢复率即技能首次调用失败后通过重试或降级最终成功的比例这反映容错机制是否有效三是用户侧转化率也就是技能返回结果后对话是否顺利收敛到用户满意的状态。误用率尤其容易被忽略。一个技能被频繁误选即使每次都能返回正确结果也会让agent显得笨拙——明明一句话能回答的问题非要走一遍接口查询再等结果。这块只能靠对话层面的效果反馈来修正描述没有捷径。我在实际维护中还养成了一个习惯每周随机抽几条真实对话记录逐条看模型对技能的选择是否合理。看板上的数字只能告诉我发生了偏差逐条对话才能告诉我为什么发生了偏差。这种笨办法在技能调优上比我见过的任何自动化工具都有效。最后说几句真心话agent-skills做下来我最大的体会是不要神化agent也不要把agent工具化。它既不是能包打天下的智能体也不是简单的if-else分发器而是一个需要持续浇灌的系统工程。模型负责聪明技能层负责可靠两者缺一不可。如果你也打算给自己的agent搭技能体系我的建议是从小做起先挑十个最核心的技能跑通注册、调度、容错、统计这四件事再逐步扩容。不要一上来就铺几百个技能也不要指望一个完美的架构能解决所有问题技能系统的价值是攒出来的不是设计出来的。最后分享一个小技巧把技能的description当成产品文案来写。想象你要把这个技能介绍给一个聪明的陌生人使用你会怎么说清楚什么时候用它、怎么用、用完能得到什么写出来的描述能给模型看也能给团队的同事看一举两得。
阅读完成 · 觉得有帮助？
