1. 先把技能抽象做对Agent技能体系的设计逻辑做Agent开发有一段时间之后你会发现一个很现实的问题模型再聪明没有一套趁手的“技能”体系它也不过是一个只会聊天的空壳。“agent-skills”这个方向说白了就是把Agent能做的事物化成可注册、可编排、可复用的技能单元让模型在任务规划时能像搭积木一样按需调用。这个思路最早是我在做某跨平台系统的内部工具链时摸索出来的当时踩了不少坑后来把整套机制抽出来单独维护才发现这件事值得单独拿出来聊一聊。1.1 为什么需要独立的技能层先说个常见场景。大多数人上手Agent开发第一反应都是直接给模型拼工具调用。今天加一个查天气的接口明天加一个发邮件的函数后天再加一个操作数据库的方法。前两周看着挺顺利等工具数量超过十几个问题就开始冒头了。模型开始频繁调错函数。明明用户问的是“帮我查一下上个月的销售额”模型却跑去调了“导出订单明细”。表面上看起来是提示词写得不够好实际上是工具本身的定义太随意。函数名、参数说明、返回格式全凭个人喜好来定模型面对一堆风格各异的接口只能靠猜。更麻烦的是复用。你在A项目里写好的查询函数想搬到B项目里用得重新改参数、改返回映射、改错误处理。工具跟业务逻辑捆在一起拆不开换一个场景就等于重写一遍。所以我在做第二个项目的时候直接把“技能层”单独抽了出来。所谓技能就是一组可以被Agent发现、调用、组合的最小功能单元。它跟具体的业务代码解耦只暴露一个标准化的调用接口。模型不需要知道技能背后是调API还是查数据库它只需要知道这个技能叫什么、能干什么、需要什么参数、会返回什么。这一层抽象带来的好处非常直接。新项目接进来只需要注册自己的技能清单模型的规划能力立刻就有了抓手。老项目的技能也能搬过来直接用改改参数映射就行。更重要的是技能本身可以被单独测试、单独优化出了问题不需要在几千行业务代码里大海捞针。1.2 技能体系的核心构成一套完整的技能体系至少包含四个组成部分。技能定义层解决的是“技能长什么样”的问题。每个技能必须有名字、描述、参数Schema、执行逻辑、返回格式。这部分是整个体系的基石定义得好不好直接决定模型能不能正确理解和调用。技能注册层解决的是“技能存在哪”的问题。所有技能都要有一个注册中心登记技能的唯一标识、版本号、所属域、调用权限、依赖关系。注册表的作用是让Agent在规划任务时能快速发现可用的技能而不是把所有技能硬编码到提示词里。编排层解决的是“技能怎么组合”的问题。一个复杂的用户请求往往是多步骤任务需要拆解成多个子任务再分配给不同的技能去执行。编排引擎负责把模型的意图转成具体的技能调用序列处理参数传递和结果汇总。评估层解决的是“技能好不好用”的问题。每个技能都要有单独的评测用例尤其是针对模型的调用成功率、参数填充正确率、返回结果可解析率做量化评估。没有评估体系的技能库时间一长一定会退化要么被新技能挤占要么被模型误用。这四个部分各司其职才能形成一个自洽的技能体系。下面我逐个展开说。2. 技能定义为什么模型总是“用不对”你的技能很多人在做技能定义的时候最常犯的错就是把技能当成普通函数来写。一个函数只需要让人看懂但一个技能需要让模型看懂这两件事的难度差着一个量级。模型不像人它不会去读你的源代码也不会问“这个参数到底是什么意思”。它唯一能依赖的信息就是技能名、描述和参数Schema。这三个字段写得不清不楚模型就只能在调用边界上反复试探最后大概率是给你调错。2.1 名称与描述给模型一张“使用说明书”技能命名是有讲究的。我总结的经验是动词名词直指意图不要用缩写不要用行业黑话。举个例子你做了一个数据平台底层有好几个查询接口。如果技能名叫“DAC”模型看了完全不知道这是什么。但你把它改成“查询用户消费明细”模型在遇到相关请求的时候就能精准匹配。命名只是敲门砖真正决定模型能不能用对这个技能的是描述字段。一个合格的技能描述至少要包含四层信息这个技能是干什么的、在什么场景下使用、有哪些限制和边界、有哪些相近技能不能混用。我用一个具体案例来说明。假设你要做一个“生成月度报表”的技能你的描述不应该只写“生成报表”三个字。更合理的写法是该技能用于生成指定月份的经营数据汇总报告支持按部门、按产品线、按区域维度进行汇总。适用于用户需要查看历史经营数据、生成周期性统计、导出报告文件等场景。注意本技能只处理已归档的月度数据不包含实时数据如需实时查询请调用“查询实时经营指标”技能不要将本技能用于生成日报、周报或其他非月度维度的报表。这段描述里包含了能力边界、典型场景、相似技能区分。模型看到之后就能非常明确地判断什么任务该调这个技能什么任务不该调。实测下来加了边界描述之后技能误用率能下降一半以上。2.2 参数与返回值把契约定得够狠参数Schema是整个技能契约里最硬的部分。这里我有几条实战经验。参数名要用全称不要用缩写。比如“startDate”比“sd”好得多“orderStatus”比“os”更明确。模型对参数名的理解力其实很强但它不会去猜你的缩写。参数类型要严格定义能给枚举就给枚举。比如“统计维度”这个参数你定义成字符串类型模型就很容易填入乱七八糟的值。但如果你定义成枚举类型限定只能选“部门”“产品线”“区域”模型的准确率会大幅提升。每个参数都要写描述并且给出示例值。这一步很多人忽略但恰恰最关键。模型对示例值的理解能力非常强一个准确的示例往往比一段长描述更有效。比如“时间范围”参数你可以加一个示例值“2025-01-01至2025-01-31”模型就会明白这个参数期望的格式。返回值格式同样重要。我建议所有技能统一采用结构化返回至少包含三块执行状态、业务数据、附加信息。举个例子{ status: success, data: { reportId: REP-2025-0101, totalAmount: 328000, detailUrl: https://domain/reports/REP-2025-0101 }, message: 报表生成完成 }这种结构看起来简单但对Agent的后续处理非常关键。模型可以靠status字段判断技能是否执行成功靠data字段提取用户真正关心的信息靠message字段生成面向用户的回复。如果你的返回格式不统一模型在串联多个技能的时候就得写一堆兼容逻辑非常容易出错。2.3 示例与边界消灭歧义的最后一公里前面说的都是静态定义但技能定义还有一个非常容易被忽略的动态要素示例对话。我在实践中发现给技能配上1到2组完整的多轮对话示例效果比在描述里写一百个字都好。因为示例展示的是“用户怎么说—模型怎么想—调用哪个技能—返回什么结果”的完整链路模型能直接模仿这个链路。举个例子你的技能是“查询快递物流状态”你可以给出这样的示例用户帮我看看我昨天买的那个东西到哪了模型好的我先帮你查一下这个订单的物流状态。调用技能查询快递物流状态参数orderId20250101-0888返回包裹已到达本市集散中心预计明天送达模型您昨天购买的商品已经从发货地运到本市集散中心了预计明天就能送到您手上。这组示例不仅让模型学会了参数从哪里提取还学会了如何把返回结果转成自然的用户回复。我强烈建议每一个技能上线前都至少配一组这样的示例尤其是那些会被用户高频使用的技能。3. 从零实现技能注册与编排的最小闭环理论和规范聊完是时候动手了。这一节我带你从零实现一个最小可用的技能注册与编排闭环。不需要依赖任何重量级框架纯Python就能跑通核心代码也就两百行左右。整个实现我都在模拟项目X里验证过你可以直接抄作业。3.1 技能注册表一个轻量实现技能注册表的核心功能有三个注册、发现、注销。我建议用字典结构来承载Key是技能名Value是技能的所有元信息。class SkillRegistry: def __init__(self): self._skills {} def register(self, skill: dict): 注册一个技能 name skill.get(name) if not name: raise ValueError(技能名称不能为空) if name in self._skills: raise ValueError(f技能 {name} 已存在如需更新请先注销) self._skills[name] { name: name, description: skill.get(description, ), parameters: skill.get(parameters, {}), executor: skill.get(executor), # 可调用的函数 return_schema: skill.get(return_schema, {}), version: skill.get(version, 1.0.0), examples: skill.get(examples, []) } return True def unregister(self, name: str): 注销一个技能 if name in self._skills: del self._skills[name] return True return False def discover(self, query: str, top_k: int 5): 根据用户意图发现最相关的技能 scored [] for name, skill in self._skills.items(): score self._score(query, skill) scored.append((score, name, skill)) scored.sort(keylambda x: x[0], reverseTrue) return scored[:top_k] def _score(self, query: str, skill: dict): 基于关键词重合度的简单评分 query_tokens set(query.lower().split()) desc_tokens set(skill[description].lower().split()) overlap len(query_tokens desc_tokens) return overlap / max(len(query_tokens), 1)这个实现里有一个discover方法它负责根据用户的输入找出最相关的几个技能。我这个示例版本用的是关键词重合度够用但不精确。你在实际项目中可以换成向量检索用本地小模型把技能描述都转成embedding用户输入也做同样的转换然后算余弦相似度。效果会好很多。3.2 技能选择与调用让模型按需组合注册表是死的编排引擎才是让技能“活过来”的关键。编排引擎的核心任务是接收用户的请求判断需要哪几个技能以什么样的顺序调用最后把结果汇总。这个过程现在主流做法有两种。一种是直接让大模型做规划你给它一个技能清单它自己决定调用顺序和参数。另一种是先用规则或分类器做粗粒度路由缩小技能范围再让模型做细粒度的参数填充。我更推荐第二种尤其是当技能数量超过20个的时候。直接让模型面对所有技能做规划它很容易在技能A和技能B之间摇摆不定。先通过规则缩小到3到5个候选技能模型的判断准确率会高很多。看一下核心实现class SimpleAgentExecutor: def __init__(self, registry: SkillRegistry, llm_call): self.registry registry self.llm_call llm_call # 大模型调用函数 def run(self, user_input: str): # 第一步缩小候选技能范围 candidates self.registry.discover(user_input, top_k5) # 第二步让模型从候选中选择技能并填充参数 plan self._plan(user_input, candidates) # 第三步按计划依次调用技能 results [] for step in plan[steps]: skill self.registry._skills.get(step[skill_name]) if not skill: results.append({success: False, error: 技能不存在}) continue try: result skill[executor](**step[parameters]) results.append({success: True, result: result}) except Exception as e: results.append({success: False, error: str(e)}) # 第四步汇总结果生成最终回复 final_response self._finalize(user_input, plan, results) return final_response_plan方法需要拼接一段提示词把用户输入、候选技能列表以及每个技能的描述、参数说明都塞进去让模型返回结构化的调用计划。我建议模型返回JSON形如{ steps: [ {skill_name: 查询用户消费明细, parameters: {userId: U-10086, month: 2025-01}}, {skill_name: 生成月度报表, parameters: {month: 2025-01, dimension: product}} ] }拿到这个JSON之后代码就能依次执行技能。整个过程看起来不复杂但每一步的细节都值得打磨。3.3 技能串联一个多步骤任务的完整走通我找一个实际业务场景来完整演示一下。假设你做了一个经营分析机器人用户提问“帮我对比一下1月和2月的各产品线销售额然后生成一份简单的分析结论。”这个请求拆解下来至少需要三个步骤第一步查1月各产品线销售额第二步查2月各产品线销售额第三步基于两份数据生成对比分析结论。对应的技能注册表里要有三个技能查询产品销售数据参数为月份、维度返回指定月份的销售统计计算对比分析参数为两个月份的数据摘要返回对比结论生成分析报告文本参数为对比结论和具体数字返回一段自然语言的分析编排引擎拿到用户输入后先做技能发现把三个候选技能都捞出来。再看模型规划出来的步骤大概率是依次调用前两个查询技能然后把结果传给第三个生成技能。这里有一个特别重要的细节第二个技能的输出需要作为第三个技能的输入。这个传参过程完全依赖返回结果的标准化。如果第二个技能返回的字段名是data和summary而第三个技能的参数名恰好是data_summary编排引擎就需要做一次字段映射。我的做法是在提示词里明确要求模型参考前一步的结果格式来填充下一步参数实测下来成功率很高。等三个技能都执行完编排引擎把最终的文本结果直接作为回复内容返回给用户。整个过程用户看到的只是“这个机器人自己查了数据、做了对比、生成了结论”实际上背后是一次技能组合调用。4. 常见问题与排查技巧实录技能体系跑起来之后你一定会遇到各种奇奇怪怪的问题。我把这一年多以来实际踩过的坑和排查思路整理成一份速查表希望能帮你少走弯路。4.1 模型总是调用错技能这是最让人头疼的问题。明明技能描述写得很清楚模型还是会在查询和导出之间选错或者在月度维度和日维度之间填错参数。我排查这类问题时第一步是看调用日志确认模型到底选了什么技能、填了什么参数。然后对比技能的描述和示例通常能发现几个规律。第一种情况是描述里出现了歧义词。比如你的技能叫“查询销售数据”但另一个技能叫“统计销售数据”模型很容易混淆。解决办法是强化每个技能的边界描述明确写出“本技能不适用于XX场景”同时把两个容易混淆的技能在描述中互相点名比如查询技能的描述里写“如需汇总统计请调用‘统计销售数据’技能”。第二种情况是参数示例不够。模型填错参数绝大多数时候是因为它不确定这个参数期望的格式。你需要在Schema里给每个参数提供至少一个准确的示例值尤其是日期、金额、百分比这类格式敏感的参数。第三种情况是技能描述太短。有些人的技能描述只写一句话模型能推断出来的信息太少了。建议每条描述不少于100字覆盖能力、场景、边界、相似技能区分。4.2 任务编排卡死、循环、提前终止模型在规划多步骤任务的时候偶尔会犯一个毛病给自己规划一个死循环。比如步骤A的结果作为步骤B的输入步骤B的结果又回到步骤A两个技能互相调用一直出不来。还有一个更常见的场景模型在规划时过早终止。用户问的是“对比1月和2月的销售额”模型只查了1月的数据就生成结论了完全没有意识到还需要查2月的数据。针对循环问题我在编排引擎里加了两道保险。第一道是最大步骤限制默认跑10步超过就强制终止并返回部分结果。第二道是技能去重同一技能在同一轮任务中最多调用3次防止A、B交替调用的死循环。针对提前终止问题解决的关键在于技能返回时附带完整状态信息。查询技能返回的data里不要只放数据还要放数据覆盖的时间范围、记录条数等元信息。这样模型在规划下一步时能看到“我只拿到了1月数据2月数据还没有”它就有更大概率规划出第二个查询步骤。4.3 技能冲突、退化和质量问题技能库跑久了还会出现一种慢性的问题技能退化。一开始你可能只有5个技能每个都调得很好。后来增加到50个技能新技能和旧技能之间出现了重叠模型开始频繁误选。更麻烦的是你可能只修改了其中一个技能的描述却没意识到它跟另一个技能的语义变得更相似了模型选错的概率直线上升。我的建议是引入定期的技能盘点机制。每个月跑一次全量技能评测记录每个技能的调用成功率、误用率、平均响应时间。那些被模型误用超过一定次数的技能就要回到定义层去修改描述。这里推荐一个很实用的策略给每个技能在注册时设定一个“预期调用场景”列表然后在评测时专门构造这些场景的测试语句看模型能否选中正确技能。我实测过用50条精心构造的评测用例就能覆盖大多数常见误用问题性价比非常高。4.4 排查思路与工具化建议排查Agent技能问题最怕的就是没有日志。从一开始你就要给每次技能调用打上日志至少记录用户原始输入、模型规划的计划、实际调用的技能名、传入的参数、技能返回结果、最终回复。这些日志不只是排查用的更是优化技能描述的数据来源。我在做模拟项目X的时候就是把所有技能调用的日志汇到一个视图里然后每周过一遍。哪些技能被频繁误用哪些参数经常填充错误哪些技能组合是经常一起出现的一目了然。这些数据反过来指导我调整技能描述和编排策略整条链路跑顺之后Agent的稳定性和可用性都有了实打实的提升。5. 下一步让技能体系长出“组合”能力如果你已经跑通了一个基础技能体系接下来有几个方向值得探索。5.1 技能模板与变体同样的逻辑不同的参数组合可以抽象成技能模板。比如“生成月度报表”和“生成季度报表”逻辑几乎一样只是时间粒度和统计维度不同。与其维护两个独立技能不如抽一个“生成周期报表”技能把时间粒度做成参数。模板的好处是显著降低技能库的冗余度模型做技能选择时也不用在多个相似技能之间纠结。5.2 技能评测与回归前面提过评测这里展开说。一个完善的技能评测体系至少包含三层单技能评测、任务级评测、组合回归。单技能评测看的是给定明确请求后模型能否正确调用该技能并填充参数。任务级评测看的是多步骤任务能否完整走通每一步是否衔接顺畅。组合回归看的是新上线的技能或描述变更后是否影响了既有技能组合的调用成功率。这三层评测我都用简单的Python脚本就能跑核心就是准备一套固定的评测数据集每次改完技能就跑一遍对比通过率有没有下降。推荐你也建一套自己的回归数据集这是一笔性价比极高的长期投资。5.3 多Agent下的技能协同再往后你可能会有多个Agent分别负责不同业务域每个Agent都有自己的技能子集。这时候技能体系会面临更大的挑战跨Agent的技能调用、权限隔离、技能嵌套。打个比方运营Agent需要调一个数据分析Agent的技能前者不应该直接访问后端的数据库查询技能而应该通过Agent间的通信机制请求后者执行。这个方向现在还处在早期我也没有完全跑通但我觉得它是Agent工程化的必然方向。等技能体系足够成熟、足够标准化跨Agent的技能编排就会像今天的RESTful API一样通用。最后说一点个人体会。我做技能体系这么长时间最大的感受是Agent开发最核心的技术点不在模型选型也不在提示词设计而在于你对能力边界的抽象能力。技能定义得好模型的表现会上一个台阶技能定义得烂再强的模型也会被拖下水。与其花时间调提示词不如花精力把技能这套底层功夫练扎实。
1. 先把技能抽象做对Agent技能体系的设计逻辑做Agent开发有一段时间之后你会发现一个很现实的问题模型再聪明没有一套趁手的“技能”体系它也不过是一个只会聊天的空壳。“agent-skills”这个方向说白了就是把Agent能做的事物化成可注册、可编排、可复用的技能单元让模型在任务规划时能像搭积木一样按需调用。这个思路最早是我在做某跨平台系统的内部工具链时摸索出来的当时踩了不少坑后来把整套机制抽出来单独维护才发现这件事值得单独拿出来聊一聊。1.1 为什么需要独立的技能层先说个常见场景。大多数人上手Agent开发第一反应都是直接给模型拼工具调用。今天加一个查天气的接口明天加一个发邮件的函数后天再加一个操作数据库的方法。前两周看着挺顺利等工具数量超过十几个问题就开始冒头了。模型开始频繁调错函数。明明用户问的是“帮我查一下上个月的销售额”模型却跑去调了“导出订单明细”。表面上看起来是提示词写得不够好实际上是工具本身的定义太随意。函数名、参数说明、返回格式全凭个人喜好来定模型面对一堆风格各异的接口只能靠猜。更麻烦的是复用。你在A项目里写好的查询函数想搬到B项目里用得重新改参数、改返回映射、改错误处理。工具跟业务逻辑捆在一起拆不开换一个场景就等于重写一遍。所以我在做第二个项目的时候直接把“技能层”单独抽了出来。所谓技能就是一组可以被Agent发现、调用、组合的最小功能单元。它跟具体的业务代码解耦只暴露一个标准化的调用接口。模型不需要知道技能背后是调API还是查数据库它只需要知道这个技能叫什么、能干什么、需要什么参数、会返回什么。这一层抽象带来的好处非常直接。新项目接进来只需要注册自己的技能清单模型的规划能力立刻就有了抓手。老项目的技能也能搬过来直接用改改参数映射就行。更重要的是技能本身可以被单独测试、单独优化出了问题不需要在几千行业务代码里大海捞针。1.2 技能体系的核心构成一套完整的技能体系至少包含四个组成部分。技能定义层解决的是“技能长什么样”的问题。每个技能必须有名字、描述、参数Schema、执行逻辑、返回格式。这部分是整个体系的基石定义得好不好直接决定模型能不能正确理解和调用。技能注册层解决的是“技能存在哪”的问题。所有技能都要有一个注册中心登记技能的唯一标识、版本号、所属域、调用权限、依赖关系。注册表的作用是让Agent在规划任务时能快速发现可用的技能而不是把所有技能硬编码到提示词里。编排层解决的是“技能怎么组合”的问题。一个复杂的用户请求往往是多步骤任务需要拆解成多个子任务再分配给不同的技能去执行。编排引擎负责把模型的意图转成具体的技能调用序列处理参数传递和结果汇总。评估层解决的是“技能好不好用”的问题。每个技能都要有单独的评测用例尤其是针对模型的调用成功率、参数填充正确率、返回结果可解析率做量化评估。没有评估体系的技能库时间一长一定会退化要么被新技能挤占要么被模型误用。这四个部分各司其职才能形成一个自洽的技能体系。下面我逐个展开说。2. 技能定义为什么模型总是“用不对”你的技能很多人在做技能定义的时候最常犯的错就是把技能当成普通函数来写。一个函数只需要让人看懂但一个技能需要让模型看懂这两件事的难度差着一个量级。模型不像人它不会去读你的源代码也不会问“这个参数到底是什么意思”。它唯一能依赖的信息就是技能名、描述和参数Schema。这三个字段写得不清不楚模型就只能在调用边界上反复试探最后大概率是给你调错。2.1 名称与描述给模型一张“使用说明书”技能命名是有讲究的。我总结的经验是动词名词直指意图不要用缩写不要用行业黑话。举个例子你做了一个数据平台底层有好几个查询接口。如果技能名叫“DAC”模型看了完全不知道这是什么。但你把它改成“查询用户消费明细”模型在遇到相关请求的时候就能精准匹配。命名只是敲门砖真正决定模型能不能用对这个技能的是描述字段。一个合格的技能描述至少要包含四层信息这个技能是干什么的、在什么场景下使用、有哪些限制和边界、有哪些相近技能不能混用。我用一个具体案例来说明。假设你要做一个“生成月度报表”的技能你的描述不应该只写“生成报表”三个字。更合理的写法是该技能用于生成指定月份的经营数据汇总报告支持按部门、按产品线、按区域维度进行汇总。适用于用户需要查看历史经营数据、生成周期性统计、导出报告文件等场景。注意本技能只处理已归档的月度数据不包含实时数据如需实时查询请调用“查询实时经营指标”技能不要将本技能用于生成日报、周报或其他非月度维度的报表。这段描述里包含了能力边界、典型场景、相似技能区分。模型看到之后就能非常明确地判断什么任务该调这个技能什么任务不该调。实测下来加了边界描述之后技能误用率能下降一半以上。2.2 参数与返回值把契约定得够狠参数Schema是整个技能契约里最硬的部分。这里我有几条实战经验。参数名要用全称不要用缩写。比如“startDate”比“sd”好得多“orderStatus”比“os”更明确。模型对参数名的理解力其实很强但它不会去猜你的缩写。参数类型要严格定义能给枚举就给枚举。比如“统计维度”这个参数你定义成字符串类型模型就很容易填入乱七八糟的值。但如果你定义成枚举类型限定只能选“部门”“产品线”“区域”模型的准确率会大幅提升。每个参数都要写描述并且给出示例值。这一步很多人忽略但恰恰最关键。模型对示例值的理解能力非常强一个准确的示例往往比一段长描述更有效。比如“时间范围”参数你可以加一个示例值“2025-01-01至2025-01-31”模型就会明白这个参数期望的格式。返回值格式同样重要。我建议所有技能统一采用结构化返回至少包含三块执行状态、业务数据、附加信息。举个例子{ status: success, data: { reportId: REP-2025-0101, totalAmount: 328000, detailUrl: https://domain/reports/REP-2025-0101 }, message: 报表生成完成 }这种结构看起来简单但对Agent的后续处理非常关键。模型可以靠status字段判断技能是否执行成功靠data字段提取用户真正关心的信息靠message字段生成面向用户的回复。如果你的返回格式不统一模型在串联多个技能的时候就得写一堆兼容逻辑非常容易出错。2.3 示例与边界消灭歧义的最后一公里前面说的都是静态定义但技能定义还有一个非常容易被忽略的动态要素示例对话。我在实践中发现给技能配上1到2组完整的多轮对话示例效果比在描述里写一百个字都好。因为示例展示的是“用户怎么说—模型怎么想—调用哪个技能—返回什么结果”的完整链路模型能直接模仿这个链路。举个例子你的技能是“查询快递物流状态”你可以给出这样的示例用户帮我看看我昨天买的那个东西到哪了模型好的我先帮你查一下这个订单的物流状态。调用技能查询快递物流状态参数orderId20250101-0888返回包裹已到达本市集散中心预计明天送达模型您昨天购买的商品已经从发货地运到本市集散中心了预计明天就能送到您手上。这组示例不仅让模型学会了参数从哪里提取还学会了如何把返回结果转成自然的用户回复。我强烈建议每一个技能上线前都至少配一组这样的示例尤其是那些会被用户高频使用的技能。3. 从零实现技能注册与编排的最小闭环理论和规范聊完是时候动手了。这一节我带你从零实现一个最小可用的技能注册与编排闭环。不需要依赖任何重量级框架纯Python就能跑通核心代码也就两百行左右。整个实现我都在模拟项目X里验证过你可以直接抄作业。3.1 技能注册表一个轻量实现技能注册表的核心功能有三个注册、发现、注销。我建议用字典结构来承载Key是技能名Value是技能的所有元信息。class SkillRegistry: def __init__(self): self._skills {} def register(self, skill: dict): 注册一个技能 name skill.get(name) if not name: raise ValueError(技能名称不能为空) if name in self._skills: raise ValueError(f技能 {name} 已存在如需更新请先注销) self._skills[name] { name: name, description: skill.get(description, ), parameters: skill.get(parameters, {}), executor: skill.get(executor), # 可调用的函数 return_schema: skill.get(return_schema, {}), version: skill.get(version, 1.0.0), examples: skill.get(examples, []) } return True def unregister(self, name: str): 注销一个技能 if name in self._skills: del self._skills[name] return True return False def discover(self, query: str, top_k: int 5): 根据用户意图发现最相关的技能 scored [] for name, skill in self._skills.items(): score self._score(query, skill) scored.append((score, name, skill)) scored.sort(keylambda x: x[0], reverseTrue) return scored[:top_k] def _score(self, query: str, skill: dict): 基于关键词重合度的简单评分 query_tokens set(query.lower().split()) desc_tokens set(skill[description].lower().split()) overlap len(query_tokens desc_tokens) return overlap / max(len(query_tokens), 1)这个实现里有一个discover方法它负责根据用户的输入找出最相关的几个技能。我这个示例版本用的是关键词重合度够用但不精确。你在实际项目中可以换成向量检索用本地小模型把技能描述都转成embedding用户输入也做同样的转换然后算余弦相似度。效果会好很多。3.2 技能选择与调用让模型按需组合注册表是死的编排引擎才是让技能“活过来”的关键。编排引擎的核心任务是接收用户的请求判断需要哪几个技能以什么样的顺序调用最后把结果汇总。这个过程现在主流做法有两种。一种是直接让大模型做规划你给它一个技能清单它自己决定调用顺序和参数。另一种是先用规则或分类器做粗粒度路由缩小技能范围再让模型做细粒度的参数填充。我更推荐第二种尤其是当技能数量超过20个的时候。直接让模型面对所有技能做规划它很容易在技能A和技能B之间摇摆不定。先通过规则缩小到3到5个候选技能模型的判断准确率会高很多。看一下核心实现class SimpleAgentExecutor: def __init__(self, registry: SkillRegistry, llm_call): self.registry registry self.llm_call llm_call # 大模型调用函数 def run(self, user_input: str): # 第一步缩小候选技能范围 candidates self.registry.discover(user_input, top_k5) # 第二步让模型从候选中选择技能并填充参数 plan self._plan(user_input, candidates) # 第三步按计划依次调用技能 results [] for step in plan[steps]: skill self.registry._skills.get(step[skill_name]) if not skill: results.append({success: False, error: 技能不存在}) continue try: result skill[executor](**step[parameters]) results.append({success: True, result: result}) except Exception as e: results.append({success: False, error: str(e)}) # 第四步汇总结果生成最终回复 final_response self._finalize(user_input, plan, results) return final_response_plan方法需要拼接一段提示词把用户输入、候选技能列表以及每个技能的描述、参数说明都塞进去让模型返回结构化的调用计划。我建议模型返回JSON形如{ steps: [ {skill_name: 查询用户消费明细, parameters: {userId: U-10086, month: 2025-01}}, {skill_name: 生成月度报表, parameters: {month: 2025-01, dimension: product}} ] }拿到这个JSON之后代码就能依次执行技能。整个过程看起来不复杂但每一步的细节都值得打磨。3.3 技能串联一个多步骤任务的完整走通我找一个实际业务场景来完整演示一下。假设你做了一个经营分析机器人用户提问“帮我对比一下1月和2月的各产品线销售额然后生成一份简单的分析结论。”这个请求拆解下来至少需要三个步骤第一步查1月各产品线销售额第二步查2月各产品线销售额第三步基于两份数据生成对比分析结论。对应的技能注册表里要有三个技能查询产品销售数据参数为月份、维度返回指定月份的销售统计计算对比分析参数为两个月份的数据摘要返回对比结论生成分析报告文本参数为对比结论和具体数字返回一段自然语言的分析编排引擎拿到用户输入后先做技能发现把三个候选技能都捞出来。再看模型规划出来的步骤大概率是依次调用前两个查询技能然后把结果传给第三个生成技能。这里有一个特别重要的细节第二个技能的输出需要作为第三个技能的输入。这个传参过程完全依赖返回结果的标准化。如果第二个技能返回的字段名是data和summary而第三个技能的参数名恰好是data_summary编排引擎就需要做一次字段映射。我的做法是在提示词里明确要求模型参考前一步的结果格式来填充下一步参数实测下来成功率很高。等三个技能都执行完编排引擎把最终的文本结果直接作为回复内容返回给用户。整个过程用户看到的只是“这个机器人自己查了数据、做了对比、生成了结论”实际上背后是一次技能组合调用。4. 常见问题与排查技巧实录技能体系跑起来之后你一定会遇到各种奇奇怪怪的问题。我把这一年多以来实际踩过的坑和排查思路整理成一份速查表希望能帮你少走弯路。4.1 模型总是调用错技能这是最让人头疼的问题。明明技能描述写得很清楚模型还是会在查询和导出之间选错或者在月度维度和日维度之间填错参数。我排查这类问题时第一步是看调用日志确认模型到底选了什么技能、填了什么参数。然后对比技能的描述和示例通常能发现几个规律。第一种情况是描述里出现了歧义词。比如你的技能叫“查询销售数据”但另一个技能叫“统计销售数据”模型很容易混淆。解决办法是强化每个技能的边界描述明确写出“本技能不适用于XX场景”同时把两个容易混淆的技能在描述中互相点名比如查询技能的描述里写“如需汇总统计请调用‘统计销售数据’技能”。第二种情况是参数示例不够。模型填错参数绝大多数时候是因为它不确定这个参数期望的格式。你需要在Schema里给每个参数提供至少一个准确的示例值尤其是日期、金额、百分比这类格式敏感的参数。第三种情况是技能描述太短。有些人的技能描述只写一句话模型能推断出来的信息太少了。建议每条描述不少于100字覆盖能力、场景、边界、相似技能区分。4.2 任务编排卡死、循环、提前终止模型在规划多步骤任务的时候偶尔会犯一个毛病给自己规划一个死循环。比如步骤A的结果作为步骤B的输入步骤B的结果又回到步骤A两个技能互相调用一直出不来。还有一个更常见的场景模型在规划时过早终止。用户问的是“对比1月和2月的销售额”模型只查了1月的数据就生成结论了完全没有意识到还需要查2月的数据。针对循环问题我在编排引擎里加了两道保险。第一道是最大步骤限制默认跑10步超过就强制终止并返回部分结果。第二道是技能去重同一技能在同一轮任务中最多调用3次防止A、B交替调用的死循环。针对提前终止问题解决的关键在于技能返回时附带完整状态信息。查询技能返回的data里不要只放数据还要放数据覆盖的时间范围、记录条数等元信息。这样模型在规划下一步时能看到“我只拿到了1月数据2月数据还没有”它就有更大概率规划出第二个查询步骤。4.3 技能冲突、退化和质量问题技能库跑久了还会出现一种慢性的问题技能退化。一开始你可能只有5个技能每个都调得很好。后来增加到50个技能新技能和旧技能之间出现了重叠模型开始频繁误选。更麻烦的是你可能只修改了其中一个技能的描述却没意识到它跟另一个技能的语义变得更相似了模型选错的概率直线上升。我的建议是引入定期的技能盘点机制。每个月跑一次全量技能评测记录每个技能的调用成功率、误用率、平均响应时间。那些被模型误用超过一定次数的技能就要回到定义层去修改描述。这里推荐一个很实用的策略给每个技能在注册时设定一个“预期调用场景”列表然后在评测时专门构造这些场景的测试语句看模型能否选中正确技能。我实测过用50条精心构造的评测用例就能覆盖大多数常见误用问题性价比非常高。4.4 排查思路与工具化建议排查Agent技能问题最怕的就是没有日志。从一开始你就要给每次技能调用打上日志至少记录用户原始输入、模型规划的计划、实际调用的技能名、传入的参数、技能返回结果、最终回复。这些日志不只是排查用的更是优化技能描述的数据来源。我在做模拟项目X的时候就是把所有技能调用的日志汇到一个视图里然后每周过一遍。哪些技能被频繁误用哪些参数经常填充错误哪些技能组合是经常一起出现的一目了然。这些数据反过来指导我调整技能描述和编排策略整条链路跑顺之后Agent的稳定性和可用性都有了实打实的提升。5. 下一步让技能体系长出“组合”能力如果你已经跑通了一个基础技能体系接下来有几个方向值得探索。5.1 技能模板与变体同样的逻辑不同的参数组合可以抽象成技能模板。比如“生成月度报表”和“生成季度报表”逻辑几乎一样只是时间粒度和统计维度不同。与其维护两个独立技能不如抽一个“生成周期报表”技能把时间粒度做成参数。模板的好处是显著降低技能库的冗余度模型做技能选择时也不用在多个相似技能之间纠结。5.2 技能评测与回归前面提过评测这里展开说。一个完善的技能评测体系至少包含三层单技能评测、任务级评测、组合回归。单技能评测看的是给定明确请求后模型能否正确调用该技能并填充参数。任务级评测看的是多步骤任务能否完整走通每一步是否衔接顺畅。组合回归看的是新上线的技能或描述变更后是否影响了既有技能组合的调用成功率。这三层评测我都用简单的Python脚本就能跑核心就是准备一套固定的评测数据集每次改完技能就跑一遍对比通过率有没有下降。推荐你也建一套自己的回归数据集这是一笔性价比极高的长期投资。5.3 多Agent下的技能协同再往后你可能会有多个Agent分别负责不同业务域每个Agent都有自己的技能子集。这时候技能体系会面临更大的挑战跨Agent的技能调用、权限隔离、技能嵌套。打个比方运营Agent需要调一个数据分析Agent的技能前者不应该直接访问后端的数据库查询技能而应该通过Agent间的通信机制请求后者执行。这个方向现在还处在早期我也没有完全跑通但我觉得它是Agent工程化的必然方向。等技能体系足够成熟、足够标准化跨Agent的技能编排就会像今天的RESTful API一样通用。最后说一点个人体会。我做技能体系这么长时间最大的感受是Agent开发最核心的技术点不在模型选型也不在提示词设计而在于你对能力边界的抽象能力。技能定义得好模型的表现会上一个台阶技能定义得烂再强的模型也会被拖下水。与其花时间调提示词不如花精力把技能这套底层功夫练扎实。
