Agent技能模块化实战：从Prompt堆叠到可编排的技能体系

1. 从“能聊”到“能干活”Agent技能模块化到底在解决什么问题最近大半年我一直在做智能体Agent方向的工程落地发现一个特别典型的现象很多人搭出来的AgentDemo效果很惊艳能聊天、能推理、能调用一两个工具但一旦进入真实业务场景就崩——不是工具调错就是上下文太长把模型搞糊涂再或者新需求一来整个Prompt和代码逻辑就要推倒重来。后来我逐渐想明白了一件事问题不出在模型能力上而出在“技能”的组织方式上。所谓agent-skills本质上是把Agent能做的每一件事——查天气、写SQL、生成图表、调用内部API、发邮件——都封装成一个个独立的、可注册、可发现、可编排的技能单元。你不再把“技能”塞进一段巨大的Prompt里靠模型临场发挥而是像搭积木一样让Agent在运行时根据用户意图动态选择、组合、调用技能。这个思路对标的是人类的学习方式。人不会在每次做事前把所有知识从头想一遍而是按需调用长期积累的技能。Agent也一样技能库越大、拆得越细、注册越规范它在真实场景里的稳定性和扩展性就越强。这篇内容我就围绕agent-skills的完整落地过程把设计思路、注册机制、编排方式、踩坑经历一次讲透。适合谁来读如果你正在做Agent应用开发或者你的团队已经有一个“什么都往里塞”的Agent框架但觉得维护成本越来越高那这篇内容应该能给你一些可执行的参考。哪怕你只是刚开始接触Agent开发先从技能拆分的思路入手也能少走很多弯路。2. 技能层设计把“会做的事”变成可被发现的原子能力2.1 为什么不能继续堆Prompt早期做Agent最常见的写法就是把工具说明、调用规则、注意事项全部写进SystemPrompt里。比如“你是一个智能助理当用户查询天气时请调用get_weather工具参数city为城市名如果用户没说城市请先询问。”这种写法在技能只有三五个时完全够用。但一旦技能超过十个、二十个Prompt会变得极其臃肿模型的注意力被稀释经常出现该调工具时不调、不该调时乱调的情况。更麻烦的是每加一个新技能都要修改Prompt并重新测试全部流程回归成本指数级上升。我后来把这些技能从Prompt中剥离出来做成一个独立技能注册中心Skill RegistryPrompt里只保留Agent的角色定义和对话策略。模型在收到用户请求后先通过意图识别或工具选择逻辑去查询注册中心找出当前任务最匹配的技能再动态注入技能描述和参数约束。这一步的改变效果立竿见影——工具选择准确率明显提升新技能的接入也再不用动主流程代码了。2.2 技能的Schema该长什么样界定一个技能模块是否合格核心看它的描述是否能被模型准确理解。我在实际项目中为每个技能定义了一套标准Schema包含几个核心字段技能唯一标识name、人类可读的description、入参声明parameters、执行逻辑入口executor、依赖的上下文context以及安全策略security。其中最关键的是parameters。它需要极尽详细地描述每个入参的类型、是否必填、枚举范围、默认值、格式示例。AI模型不像传统程序会严格校验参数类型它依赖自然语言描述来识别应当传什么。比如一个用于数据分析的query_database技能参数sql的说明如果只写“SQL查询语句”模型很容易漏传或写错但如果写明“标准SQL仅允许SELECT查询禁止DELETE/UPDATE/DROP表名应为snapshot格式如orders_20240101”模型的遵从度会高很多。建议用JSON Schema来表达参数约束一方面它可以被程序解析做运行时校验另一方面它的结构对模型理解也非常友好。我给每个技能的Schema配了一个example字段专门存放一个完整可运行的示例调用。这个成本很低但对模型提升巨大——大语言模型在上下文中看到示例后照着示例输出的概率会显著增加。2.3 技能的存储与动态发现技能注册中心本身其实就是一个带索引的数据库或配置文件。项目初期可以简单用YAML或JSON文件维护随着技能数量增加再迁移到数据库或配置中心。每类技能除了存Schema外还要建立关键词索引和语义索引。关键词索引用于匹配那些意图已经非常明确的任务比如用户说出“帮我看看北京明天天气”关键词“天气”可以快速锁定weather技能。语义索引则用来处理意图模糊的场景用户说“我明天要去机场几点出发合适”这并不直接包含某个技能名但经过向量化检索能匹配到出行建议和航班查询类技能。这种“双通道召回”的方式在工程上是比较稳妥的做法。我最初跳过语义索引只做关键词匹配结果大量跨表述的请求落不到正确技能上Agent只能靠LLM临场硬编一段没有执行能力的回答体验很糟糕。后来加了语义检索每个技能的描述文本提前用Embedding模型向量化存入向量库运行时把用户请求也向量化用余弦相似度召回Top-K候选技能再交给LLM做最终取舍效果才算达到可用状态。3. 技能注册与调用链路从收到请求到技能执行的完整流程3.1 注册流程与版本管理新增一个技能我的一般流程分为四步。第一步明确能力边界。写清楚这个技能做什么、不做什么。比如一个send_email技能它的能力边界是“发送电子邮件”不包括“撰写邮件正文内容生成”。生成正文是另一个技能或由LLM直接负责。边界不清晰的技能最容易引起调用混乱。第二步编写Schema并注册。将技能描述、参数定义、执行函数入口注册进中心。这里我建议每个技能有一个version字段技能逻辑变更时版本递增并在描述中注明“本技能返回数据为JSON格式时间字段统一为UTC”。不同版本的技能可以共存方便灰度发布和快速回滚。第三步编写单元测试。给每个技能准备三到五组典型的调用用例和期望输出并覆盖参数缺失、超时、异常返回等边界场景。这些测试不仅用于验证代码正确性更能用于回归测试——因为随着技能库变大某个改动可能侧面影响另一个技能的调用路径。第四步在沙箱环境联调。模拟用户的几种典型问法观察模型是否能准确命中该技能、参数是否传递正确、返回结果是否合理呈现。通过后再发布到生产技能库。3.2 请求处理与技能选择的执行路径一个标准的请求处理链路是用户输入 → 意图路由 → 技能召回 → LLM技能裁决 → 参数抽取 → 技能执行 → 结果校验 → 组装回复。意图路由阶段系统判断请求是普通闲聊还是任务型请求。闲聊直接走对话模型任务型请求进入技能召回阶段。技能召回通过关键词和向量混合检索从技能库中取出Top-K候选。接下来是最有意思的部分——技能裁决。我不建议直接把唯一命中的技能强行执行因为用户的自然语言表达往往存在歧义。正确的姿势是把Top-K候选技能的描述和参数Schema拼进Prompt让LLM做一次“选择题”判断哪个技能最匹配、缺失哪些参数、是否需要反问用户。这个裁决过程可以显著降低误用率。举个例子用户说“帮我找一下上季度的销售冠军”。技能库里可能有query_sales_data和query_employee_info两个技能。前者关注数据维度后者关注人员信息。LLM裁决时如果发现两个技能都有可能就应该生成追问“你希望查询的是销售额最高的个人、团队还是产品线”。一次精准的反问好过盲目执行后给出一堆无用数据。参数抽取阶段LLM根据Schema从对话上下文中抽取出全部必填参数有缺漏时自动发起澄清式追问。技能执行阶段则调用具体函数或外部服务这一步通常要设置超时和重试机制。最后的结果校验非常关键——不要无条件信任外部API的返回尤其是数据型技能最好对字段完整性做快速校验再交给LLM生成最终回复。3.3 技能执行与上下文管理技能执行完毕后的数据如何融入对话也是一个需要精细化处理的环节。我的做法是引入一个短暂的上下文缓冲区把技能返回的原始JSON存入其中LLM在组织回复时参考缓冲区数据但不会直接把JSON原文全量丢给用户。比如一个查询订单状态的技能返回了包含三十个字段的JSON真正需要呈现给用户的只是订单号、状态、物流单号和预计到达时间。LLM应该从原始JSON里筛出关键信息生成一句话摘要。这样既保证了回复的简洁性也避免无关敏感数据出现在回复里。上下文缓冲区还需要注意清理策略。技能返回的大段数据如果在下一轮对话中不再需要要及时释放。否则多轮对话后上下文会积累大量无用的结构化数据白白消耗模型的上下文窗口。4. 技能编排当单个技能搞不定复杂任务时怎么办4.1 从原子技能到技能链真实业务场景很少只靠一个技能就能完成。比如“帮我分析本周销售额下降的原因”完整流程涉及查询销售数据 → 拉取竞品动态 → 分析天气或节假日影响 → 生成可视化图表 → 输出结构化报告。如果让一个技能硬扛全部步骤又会回到“巨无霸技能”的老路上灵活性大打折扣。正确的思路是把技能设计成可组合的原子单元再通过一个编排层把它们组装成技能链。我用过两种编排方式。第一种是代码编排Orchestration by Code用Python或JSON配置定义好步骤的先后顺序和依赖关系每个步骤的输出作为下一步骤的输入。这种方式路径固定、可控性强适合那些流程基本不变、确定性要求高的任务。第二种是模型编排Orchestration by Model把若干技能作为候选交给LLM去规划让LLM自主决定先调用哪个、再调用哪个。这种方式灵活度高适合探索性强、路径不固定的开放任务但对底层技能的可靠性要求也更高——因为LLM的规划一旦建立在不可靠的执行上错误会被逐层放大。一个相对稳妥的组合方式是“骨架用代码编排节点用模型裁决”。也就是说任务的宏观流程由代码固定下来但在每个关键节点是否选择某个技能、如何调整参数由LLM根据当前上下文做动态决策。这个模式在我手头的多个项目里表现都比较稳定。4.2 技能编排中的一个避坑要点技能链设计里最容易被忽略的是“上下文传递”。上游技能输出的数据如何结构化地传给下游技能直接决定链路的稳定性。如果上游输出是一段自然语言总结下游技能需要结构化参数时就很容易解析失败。所以技能链中建议前置一个数据规范化步骤即每个技能输出的JSON要按统一规范组织任何下游技能直接按字段名取用即可不要依赖自然语言解析。另一个坑是循环依赖即在模型编排模式下两个技能互相调用导致死循环。我在系统中加了一条安全约束限制单个任务中技能调用的总次数默认上限四次同时禁止同一技能在同一条链路中被连续调用两次以上。这两个限制看似简单却能有效防止很多失控场景。4.3 一个完整的技能链示例拿“竞品分析日报”场景来展示一个典型的技能链实现思路。技能链由五个技能串接组成。fetch_competitor_data负责从公开渠道抓取竞品动态summarize_article用大模型提取每条动态的核心要点query_own_metrics查询自家产品的关键指标compare_metrics完成指标对比并生成差异结论最后generate_report把以上结果渲染成Markdown日报。整个链路中fetch_competitor_data固定第一个执行generate_report固定最后一个执行中间三个步骤则交给LLM根据当天数据情况进行取舍。比如某天没有重要竞品动态LLM可以选择跳过summarize_article直接进入指标分析环节。这种灵活但不越权的编排风格兼顾了效率与稳定性。5. 落地过程中踩过的坑与排查技巧5.1 技能描述太“虚”模型根本不知道怎么触发我最早写技能描述时一句话就说完了——“查询订单数据”。结果模型很多次都识别不到该用这个技能。后来我改用“场景具体行为触发条件”的写法“当用户需要查看历史订单、跟踪订单状态、查询物流信息时使用本技能用户提供订单号时可查询单个订单详情未提供时可按用户身份查询订单列表。”把触发场景写得越具体模型的选择准确率越高。这里还有一个技巧写description时想象你正在给一个新同事写交接文档而不是给机器写函数注释。模型对自然语言的语义理解远好于对结构化注释的理解所以用通顺自然的语言描述使用场景比列一堆参数表格更有效。5.2 参数缺失时不要硬挫学会反问问清楚另一个经常出现的问题是参数缺失导致执行报错。用户说“帮我看看空调”但没有说任何约束条件。技能需要品牌、匹数、价格区间三个参数。最差的处理方式是直接报错或者用一堆默认值瞎猜。我设计的处理逻辑是参数缺失时由LLM判断关键程度。如果缺失的是非关键参数就使用Skill内预置的默认值并在回复中说明如果缺失的是无法取默认值的关键参数则生成一条追问回复一次只问一个最关键的问题避免连续反问把用户体验搞坏。5.3 测试的“最后一公里”问题很多Agent项目测试只覆盖了“技能单独调用”的成功路径忽略了组合场景和异常链路。我在项目后期养成了一个习惯为每条技能链准备一份“故障注入清单”刻意让某个技能返回超时、返回空数据、返回格式异常观察整条链路的兜底行为是否合理。排查技能调用问题时日志里一定要记录技能选择的完整路径——用户输入、召回的候选技能及得分、LLM裁决的理由、参数抽取的中间结果、执行时长、异常堆栈。这些日志在故障复盘时价值极大。没有这些信息你很难判断到底是模型选错了技能还是技能本身执行出了问题。6. 工程化落地的几个关键建议6.1 安全与权限隔离技能离业务数据越近越不能忽略权限控制。我给每个技能都绑定了最小权限策略比如数据查询类技能只授予只读权限文件操作类技能限定在指定目录外部请求类技能做强域名白名单校验。用户身份与技能的权限映射关系也要设计清楚——不同角色能调用同一技能的不同数据范围。这一点在“写操作”类技能上必须严格对待。像send_email、create_order、delete_record这类有副作用的技能建议在技能定义中标注requires_confirmation由系统在规则阶段而非模型阶段强制加入确认环节。绝不要指望大模型每次都自觉在写操作前跟用户确认——模型会遗忘规则不会。6.2 可观测性建设技能调用链路的每一个环节都需要可观测。我一般为每个技能调用生成唯一的trace_id记录调用的技能名、版本、入参、出参、耗时、错误信息并把这些数据接入监控大盘。没有这个基础设施技能库超过一定规模后基本就是黑盒出了问题只能靠猜。6.3 从0到1的落地路径如果你想在自己项目里实践agent-skills的思路我的建议是不要一上来就追求大而全的技能框架。先用一个最简单的场景做通端到端——比如只做“查询功能”相关的三五个技能完整跑通Schema定义、注册中心、动态选择、执行回调和日志链路。跑通之后再逐步扩展。这个渐进式方法的好处是你能在早期就暴露框架层面的设计缺陷。如果最初的三个技能都无法稳定运行那就先别急着加到三十个技能不然后面的问题会让你改得怀疑人生。我个人在实际操作中的体会是agent-skills最有价值的不是某一项技术实现而是它逼着你重新思考“Agent到底擅长什么、不擅长什么”。模型擅长理解和生成但技能的稳定执行、权限边界、错误兜底统统要靠工程手段来保证。把技能当作一等公民来看待而不是Prompt里的一段说明文字这一步想通之后整个Agent系统的演进路径就清晰多了。最后再分享一个我觉得很值得坚持的习惯每次给Agent加新技能时先写技能的测试用例再写技能代码。这本来是传统软件开发的老规矩但在Agent开发里反而经常被忽略。经历过几次技能上线后悄然破坏其他链路的事故之后我深刻感受到——一个没有测试保护的技能库规模越大风险越高。