前几个月我所在的团队在做一个企业知识库问答Agent一开始的思路非常简单粗暴给Agent塞十几个API工具把向量库、搜索、文档解析统统挂上去然后让大模型自己“看着办”。结果跑起来之后问题不断——Agent经常不知道在什么场景用哪个工具同一个需求换个说法就懵更别提多步任务里中间状态的混乱了。当时我最大的感受是单纯堆工具等于给一个实习生桌子上扔了二十本说明书却从来没教过他这些活儿该怎么干。后来我彻底换了一套思路也就是今天要聊的agent-skills。它的核心不是“给Agent更多工具”而是把Agent需要的能力拆成结构化的、可被动态加载和调度的“技能”每一个技能自带触发条件、执行流程、输入输出约定和状态管理。这套思路改完之后同一个知识库Agent的准确率和使用体验直接上了一个台阶。这篇文章把我从概念理解到落地实现的完整过程写下来包含技能库的数据结构设计、一个可复用的多源检索技能实战、以及我在测试和上线中遇到的典型翻车场景和排查链路希望对正在做Agent工程化、或者想让自己手上的Agent“更像一个靠谱员工”的朋友有帮助。1. 当我们在讨论Agent技能时讨论的到底是什么很多人一听到“Agent技能”就觉得是给Model加Function Calling或者多封装几层Prompt。其实这完全是两个层面的事我一开始就是这样踩偏的。工具Tool解决的是“能做什么”技能Skill解决的是“在什么情况下用什么方式做完一件事”。如果只有工具没有技能Agent就像一个拿到了电钻、螺丝刀、水平仪但完全不知道如何装好一个书架的人工具都认识活还是干不利索。1.1 工具与技能的本质差异状态、目标与边界我后来的理解是一个合格的Agent技能至少要包含三个维度的信息而不只是一个可以被调用的函数签名。第一个维度是目标Intent。这个技能到底要帮用户完成什么目标我一般会把目标写成一句话比如“从企业内部的多个数据源检索与某主题相关的资料并输出带引用的结构化摘要”。这句话不是装饰品它是技能调度器判断“该不该启用这个技能”的重要依据。第二个维度是状态State。这个技能在执行中会携带哪些中间变量比如检索技能需要维护“已检索过的数据源列表”“每个数据源返回的结果片段”“最终采纳了哪些片段”。没有状态管理Agent在做多步检索时就会反复查询同一个源甚至最后自己都不知道某个结论是哪来的。第三个维度是边界Boundary。哪些情况是这个技能不该管、管不了的比如检索技能只负责“找资料摘录”不负责“生成行动计划”“调用外部API下单”“做数据分析绘图”。边界写清楚了Agent才不会在技能内部越权操作也方便在多个技能共存的场景下防止冲突。拿开车来做类比。工具就像方向盘、油门、刹车都是独立的零部件技能则是“完成一次右侧超车”这样一个完整的驾驶动作——它调用了多个工具遵循一定的先后顺序同时清楚自己当前的车速和位置也知道什么情况下必须放弃超车回到原车道。技能是工具之上的驾驶动作不是零件本身。1.2 为什么技能化比工具化更适合复杂Agent工具调用的粒度太细了。细粒度的直接后果就是大模型在做意图匹配时选择空间巨大容易选错。比如我给Agent挂了“数据库查询接口”和“文档全文检索接口”用户问“上季度华东区的销售额汇总一下”有些模型会倾向于去调数据库查询有些则直接跑到文档库里去翻PDF。两个说法都对但大概率会选到根本不合适的那一个。但技能化的粒度就完全不同。我可以定义一个“经营数据汇总报告技能”它的触发条件写清楚“当用户请求中同时出现季度、区域、销售额、汇总、报告等关键词簇或请求显然指向结构化经营数据的跨维度整合时启用”然后把数据库查询、指标计算、结果格式化三个工具按顺序编排到技能内部。大模型需要做的决策从“选哪个函数”变成了“判断用户的意图是不是这个技能”决策空间缩小了一个数量级准确率自然就稳了。另外一个特别重要的点是复用性。工具化方案里每个Agent都要重新编排一遍工具列表和Prompt说明换个场景就推倒重来。技能化之后一个“多源检索与结构化总结技能”可以同时挂到客服Agent、知识库助手、行业研究员助手上去只需要在技能配置里改一下数据源的地址和参数。这个性价比在长期维护中是肉眼可见的。这也是我后来常跟团队强调的一句话工具是可替换的零件技能是可复用的能力Agent是能力的组合体。这句话基本可以作为整个技能化设计的总纲。2. 从零搭一套技能库的底层设计有了上面的认知之后就可以开始动手设计了。技能库的底层设计是整个体系里面最需要认真对待的部分因为上层调度、技能编排、动态加载全都依赖这一层的数据结构是否合理。我把我最终落地的方案拆开讲包含存储结构、接口规范、注册与版本管理三个方面。2.1 技能描述文件给Agent看的“岗位说明书”首先每个技能我用一个JSON描述文件来做元数据定义这个文件同时承担两件事供调度器做意图匹配以及供Agent在运行时理解当前技能的能力边界。下面是我在实际项目里使用的一个精简但完整的示例{ skill_id: multi_source_retrieval_summary, name: 多源检索与结构化总结技能, version: 1.2.0, description: 从企业知识库、文档系统、外部搜索引擎等多个数据源检索与用户问题相关的资料并对检索到的片段进行来源标注、去重和结构化总结。适用于资料调研、竞品分析、内部知识问答、研究汇总等场景。, intent_trigger_hints: [ 检索、查找、搜集、调研、汇总资料, 对比多个来源的信息, 输出带引用的摘要或综述 ], boundary: 仅负责资料检索与文本总结。不负责生成行动计划、不执行外部业务操作、不处理非文本类数据解析。, input_schema: { type: object, properties: { query: { type: string, description: 用户的自然语言检索请求 }, sources: { type: array, items: { type: string }, description: 指定的数据源列表缺省表示使用全部已配置数据源 }, max_results_per_source: { type: integer, default: 5, description: 每个数据源最多返回的结果条数 } }, required: [query] }, output_schema: { type: object, properties: { answer: { type: string, description: 最终的结构化总结回答 }, citations: { type: array, items: { type: object }, description: 引用来源列表每条包含来源名称、片段摘要、原文链接或文档定位 }, status: { type: string, enum: [success, partial, failed] } } }, tools: [knowledge_base_search, document_fulltext_search, web_search, deduplication_filter], workflow: collect - deduplicate - summarize, state_management: { collected_fragments: { type: list, persist: within_turn }, source_trace: { type: dict, persist: within_turn } } }这里有几个值得展开说的地方。intent_trigger_hints不是简单的Prompt它是给调度器做意图路由的关键信号。我尝试过让大模型纯靠description做意图判断效果不稳定后来把触发线索单独拆成一个数组调度器用向量召回或者关键词加权来做第一轮预筛准确率明显更稳。具体做法后面会写到。input_schema和output_schema必须比普通的函数参数定义更严格。因为技能要服务于Agent的“编排决策”输入输出字段不清晰Agent就不知道什么时候该调这个技能也不知道调用完拿到的东西该怎么继续用。output里那个status字段是我后来加的——当多个数据源里有一部分挂了我就把status置为partial告诉上层“有部分结果但不够完整”而不是直接报错中止或假装没事。state_management是很多人容易忽略的。单个技能内部可以有中间状态比如collected_fragments列表但这些状态要不要跨轮持久化我默认设为within_turn也就是技能执行完一轮就清空。如果某个技能确实需要跨轮记忆比如“持续监控某关键词的新增资料”那再单独声明persist: true并配合会话级存储来管理。默认不持久化显式开启才持久化这个原则能省掉一大堆状态混乱的坑。2.2 技能调度器的接口设计技能描述文件解决的是静态描述真正跑起来还需要一个调度器。调度器对外暴露的接口我保持了最小化核心就三个方法class SkillRegistry: def register(self, skill_meta: dict) - str: ... def unregister(self, skill_id: str) - None: ... class SkillDispatcher: def match(self, user_query: str) - list[SkillMatch]: # 返回与用户请求最匹配的技能列表附带匹配分和理由 ... def invoke(self, skill_id: str, input_data: dict, context: dict) - SkillResult: # 按技能的workflow定义执行内部工具链 ...match方法做的事情就是根据技能描述文件里的intent_trigger_hints和description去匹配用户的自然语言请求。我试过纯关键词匹配、纯大模型分类、向量召回三种方案最后用的是“向量召回大模型精排”的两级结构先用Embedding把用户请求和所有技能的description、trigger_hints算相似度取Top-5再把Top-5的完整元数据交给大模型做一次精排让它输出最终选中的技能或判定没有合适技能。这样做的好处是省Token。技能多了以后把所有技能的完整描述一次性塞给大模型做意图路由光是描述文本就可能顶掉几千Token成本和延迟都不划算。第一级向量粗筛能快速把候选集缩小第二级再让大模型在极小的选择集里做精细判断准确率高开销也可控。invoke方法内部则是按技能的workflow字段去编排工具调用链。我这里写了一版极其简单的顺序执行器只支持collect - deduplicate - summarize这种线性流程实际场景肯定比这个复杂后面第4章会讲到支持简单条件分支和并行调用的进阶编排。2.3 版本管理与灰度发布技能文件有两个版本号一个是文件本身的version还有一个是依赖的工具集版本。我踩过一个特别典型的坑——升级了某个底层工具的API协议忘了同步更新依赖它的技能元数据结果线上Agent调用技能时传参全部错位报错信息还特别误导排查了整整一个下午。从那之后我做了两件事。第一每个技能描述文件里显式声明依赖的工具版本范围不写死但必须写明最低兼容版本。第二技能注册进Registry的时候要做Schema校验包括输入输出参数是否和依赖工具的签名匹配、workflow里引用的工具是否都存在。校验不通过技能直接拒绝注册不允许带病上线。灰度发布我用的办法比较简单粗暴但有效同一个skill_id可以存在多个版本Registry里把某个版本标记为production灰度中的版本标记为candidate。线上流量默认打到production只有指定的测试会话可以强制走candidate版本。对比跑几天没问题再把production切到新版本。这套流程在团队里已经固定下来了基本杜绝了“技能改了一行配置就把全线上干崩”的事故。3. 手把手实现一个可复用的多源检索技能理论部分讲再多不落地等于零。这一章我把上面设计的一套东西落到一个完整的技能实现上场景选“多源资料检索与结构化总结”因为这是绝大多数知识型Agent都会用到的基础技能通用性最高。下面从一个最小可运行的Python版本开始。3.1 整体目录结构与核心类我的技能目录采用一人一技能一目录的规则方便做版本管理和独立部署skills/ └── multi_source_retrieval_summary/ ├── skill.json # 上一章说的技能描述文件 ├── executor.py # 技能执行器实现workflow ├── source_adapters/ │ ├── __init__.py │ ├── knowledge_base.py # 知识库检索适配器 │ ├── document_search.py # 文档全文检索适配器 │ └── web_search.py # 外部网页搜索适配器 └── utils.py # 去重、片段排序等工具函数executor.py是技能的核心它接收标准化的input_data和context然后按workflow执行。我不把业务逻辑写死在技能执行器里而是用适配器模式把每个数据源的差异封装起来。这样新接一个数据源只需要新增一个adapter文件技能执行器完全不用动。后面在避坑部分会详细讲这种设计在维护阶段能救命的。3.2 技能执行器代码解析下面是executor.py的核心代码我删掉了日志和细节处理保留主干逻辑方便理解import asyncio from typing import Any class MultiSourceRetrievalSkill: def __init__(self, meta: dict, adapters: dict): self.meta meta self.adapters adapters # {knowledge_base: KBAdapter(), ...} async def execute(self, input_data: dict, context: dict) - dict: query input_data[query] # 1. 确定本次要查询的数据源 sources_cfg self._resolve_sources(input_data.get(sources)) # 2. 阶段一并行收集原始片段 collected await self._collect_phase(sources_cfg, query) # 3. 阶段二去重与相关性过滤 deduped self._deduplicate_phase(collected) # 4. 阶段三调用大模型做结构化总结 result await self._summarize_phase(deduped, input_data, context) return self._normalize_output(result)_collect_phase用的是asyncio.gather做并行调用各个数据源互不依赖没必要串行浪费时间。一个典型的业务场景是用户问“最近一年国内大模型安全对齐方向有哪些代表性研究和实践案例”知识库检索只返回公司内部沉淀的材料文档全文检索返回的是上传的PDF和白皮书外部搜索则抓取公开网页。三个源同时跑总耗时取决于最慢的那个源而不是所有源之和。_deduplicate_phase做三件事首先是去掉完全重复的文本片段然后按语义相似度做二级去重我用了一个简单的Embedding余弦阈值0.92超过就视为重复最后对保留片段做个简单的相关性排序。这里不追求完美核心目的是控制后续送去大模型的片段数量防止上下文窗口被垃圾信息填满。_summarize_phase的Prompt构造是整条链路里面最关键的地方。我提供了一个稳定的模板核心是约束大模型“只能基于给定的片段作答不能引入外部记忆”同时强制要求带引用标记SUMMARIZE_PROMPT 请基于以下检索片段回答用户的问题。 规则 1. 只使用片段中明确支持的信息禁止根据片段未提及的内容进行推测。 2. 回答末尾必须附上使用的片段编号列表格式为[片段编号]。 3. 如果片段之间存在矛盾请在回答中明确指出并优先采用来源更权威的片段如公司官方文档优先于个人博客。 4. 如果片段信息不足以完整回答请在开头明确说明“以下回答基于不完整的信息”。 检索片段 {numbered_fragments} 用户问题{query} 小括号和方括号的用法我故意精细化处理了这是为了让大模型在生成citation时更稳定地锚定到片段编号而不是自己脑补一个来源。实测下来这种方式比“请注明来源”这种模糊指令的引用准确率至少高出两成。3.3 调用示例与输出效果技能封装好之后外部调用只需要做两件事准备input_data和context然后调用dispatcher。我放一个完整调用示例input_data { query: 大模型安全对齐的最新研究趋势, sources: [knowledge_base, web_search], # 这次不查文档系统 max_results_per_source: 3 } context { user_id: u_10086, session_id: s_20250115_001, preferred_language: zh } result await dispatcher.invoke( skill_idmulti_source_retrieval_summary, input_datainput_data, contextcontext ) print(result[status]) # success print(result[answer]) # 带引用标记的结构化总结 print(result[citations]) # 引用来源列表实际项目中我遇到过一个细节问题sources参数缺省的情况下到底该查哪些源我的策略是默认全部数据源但通过配置定义一个源的黑名单比如客户现场部署时外部搜索网络不通那就把它加进黑名单技能不会去碰它。判断“网络不通”这个状态需要一个探活机制我在adapter层加了connectivity check每次调用前先确认可用性失败则跳过并在status里标记为partial。这个机制在后面排障章节还会再次提到。4. 实测中最容易翻车的四个场景技能化做了大概两个月期间遇到过不少问题。这些坑单独看都挺小但在线上环境里每一个都有能力让整套Agent系统看起来“笨得离谱”。挑四个最有代表性的展开说说每一个都附上我排查的完整链路和最终修复方案。4.1 症状技能触发混乱两个技能反复横跳第一次出现这个问题是在同时引入“多源检索技能”和“文档翻译技能”之后。用户问“帮我把这篇英文PDF翻译成中文”按理说应该走文档翻译技能。但多源检索技能的intent_trigger_hints里写了“调研、资料、文档、翻译”这些词结果系统两个技能都能匹配上模型在两次调用之间反复横跳最后一轮给用户的是“我找到了相关资料但没有找到翻译结果”。排查链路是这样的。第一步我打开了调度器的日志确认每个技能的实际匹配分。发现两个技能的匹配分都很高说明问题出在粗筛阶段——Trigger hints写得太宽泛了。第二步我把查询语句关键片段摘出来和两个技能的关键词对比发现“翻译”这个词是两个技能共享的多源检索技能根本不需要把“翻译”列进触发词。第三步修复把多源检索技能触发词里的“翻译”删掉同时在描述里增加一句“本技能专注检索与总结不包含文件格式转换、语言翻译等操作”。这种边界声明写在Description里比写在Boundary里更有效因为调度模型在做意图匹配时对Description的权重感知高于对Boundary的权重感知。这个调整上线之后类似的触发混乱问题几乎绝迹。4.2 症状技能会执行但执行结果永远“差一点”用户问“帮我总结一下最近领导讲话里面提到的四个季度工作重点”技能确实执行了检索也返回了一堆片段但最终总结里只提到了三个季度第四个季度被漏掉了。这属于典型的“召回率不足”问题表现不是报错而是给出一个看起来正常、实际上不完整的结果危害更大。我沿着技能内部的状态追踪log查了一遍。第一步检查了检索返回的原始片段数量和质量——发现第四个季度在某个源里确实存在但被排名靠后被去重阶段的阈值误杀了。当时去重模块用的是纯粹的语义相似度阈值第四季度的表述和另一个季度在语义上过于接近被当成重复内容过滤掉了。第二步修复方案给去重逻辑加了一个“摘要完整性保护”规则——如果某个片段的文本长度显著短于其他片段但同时包含独特的关键词如“四季度”“Q4”则不参与粗粒度去重单独放行。第三步在总结Prompt里加了一条硬性指令“如果片段中包含季度、月份、数字编号等结构化信息必须逐一覆盖缺失需在回答中说明。”两个修改合并上线后漏项问题消失了。这个坑的核心教训是技能内部的每个环节都可能静默地制造“看起来对、实际错”的结果排查的时候不能只看最终输出要看中间状态在哪个环节丢了信息。所以我在技能框架里默认给每个阶段都做了debug快照线上可以按需开启这个设计在多次排障里都发挥了决定性作用。4.3 症状技能依赖的工具升级技能突然失灵有一次底层文档检索服务的API从v1升级到v2返回字段从doc_id改成了document_id嵌套层级也变了一层。原有技能执行器没有做字段兼容直接按document_id去取原文结果全部取空。问题表现是技能调用不报错但最终拿到的检索结果永远是空的。排查链路第一步我看技能执行器日志发现第一阶段检索调用成功返回了但_fragments为空。第二步临时在适配器里加了原始返回值的dump对比v1和v2的差异发现字段名和结构都变了。第三步修复在适配器层增加了一套“字段兼容解析器”先用新字段名解析失败则回退到旧字段名同时适配器内部做一次结果结构标准化保证技能执行器永远拿到统一的数据结构。第四步把适配器对底层服务的依赖做了契约测试——每次上游升级先跑一遍契约测试通过才允许升级上线。这里再次印证了第2.3节说的版本管理必要性。技能执行器不要直接依赖外部服务的字段所有外部数据格式差异都必须封装在adapter层内消化。这会让前期开发多花一点时间但后期维护的成本能省出一个数量级。4.4 症状技能在长对话中上下文过载每轮输出质量逐渐下降这个问题出现在Agent连续对话超过10轮之后。技能每次调用都会把历史上下文以非常大的规模传给大模型一开始还没事但随着片段数量累积模型越来越倾向于从历史信息里找答案而不是基于最新检索结果回答。用户越聊回答越“凭印象”完全失去了检索增强应有的严谨性。排查链路第一步我检查了context传参发现每一轮技能调用都会读取整个会话历史包含所有已检索片段。第二步修复把技能内部的已检索片段从跨轮上下文中摘除只保留最终生成的answer和citations作为会话历史的一部分检索片段的生命周期严格限制在本轮内。第三步给context传入增加了一个截断策略——历史消息按时间倒序截取最近5轮加上前文摘要。经过这个调整之后长对话场景下技能的输出质量明显恢复了。这件事让我对“技能状态管理”有了更深的理解。技能产生的中间产物检索片段、去重轨迹对最终用户是有噪音的不应该暴露到会话主线程。真正需要进入长期记忆的只有技能的最终输出。中间产物要么放弃要么进入一个独立的短期记忆桶由需要它的其他技能显式申请读取。5. 更上一层的玩法技能组合与自动编排单个技能跑通之后自然会想能不能让多个技能配合起来完成更复杂的任务我在这块也做了不少尝试虽然还没有完全成熟但已经有一些比较稳定的模式可以分享。5.1 把技能当成乐高积木的前提是标准化技能组合听起来很灵活但真正做的时候会发现如果每个技能的输入输出没有一个统一的约定组合就无从谈起。我关于标准化踩出的最终准则就两条。第一条所有技能之间只允许通过标准化的data object传递数据。比如“多源检索技能”输出的citations是一个JSON数组“结构化信息提取技能”输出的entities也是一个JSON数组两个技能之间不能因为“内部实现方便”就传一个自定义类实例。所有跨技能传递的数据都必须是可序列化的JSON兼容结构这样即使某个技能换了一种编程语言实现组合逻辑也不会受影响。第二条每个技能必须以显式声明的Schema约束自己的输入输出组合器不负责隐式转换。如果“数据分析技能”需要的输入是表格化的dataframe-like JSON那么上游“多源检索技能”的输出如果没有这个结构要么在组合时加一层转换器要么拒绝组合。我见过的很多Agent组合失败八成都是因为上游输出和下游输入之间在结构上不匹配然后靠Prompt硬让模型“理解”一下结果模型一“理解”就拿出了自己脑补的数据鬼知道对不对。做到这两条之后技能组合就变得非常机械了几乎不需要太多人脑干预。我在项目里做了一个简单的组合配置示例{ pipeline_id: weekly_report_pipeline, steps: [ { skill: multi_source_retrieval_summary, params: { sources: [internal_kb, web] } }, { skill: info_entity_extractor, params: { input: prev.output } }, { skill: table_generator, params: { input: prev.output, format: markdown_table } } ] }这样一个自动周报管线就拼出来了。每个阶段都是标准技能都可以被测试和替换整条管线本身也只是一个元数据描述不绑定具体代码。这套思路在团队内部跑起来之后有个很直接的感受开发新能力不再是“让Agent多会一样东西”而是“给现有技能库加一块新积木再拿现有积木拼一个新造型”。5.2 组合过程中哪些组合值得做哪些不要做技能组合虽然香但并不是无脑拼得越多越好。我个人的判断标准是如果一项任务的完成路径高度稳定就值得拼成管线如果路径经常变化、每次都要人和模型临时决定那就不如把决策权交给上层的Agent编排器而不是离线写死。比如“知识问答”场景路径就是检索-提炼-回答非常稳定我直接拼成固定管线把中间的决策空间压缩到最小速度和稳定性都最好。但“用户说了一句很模糊的意图比如‘帮我看看最近有什么值得关注的竞品动态’”这种路径其实非常不确定——需要先澄清再决定检索范围再决定要不要生成对比表这个时候写死一条管线反而会显得机灵不足。我把这类开放意图交给一个轻量的Agent编排器让它像项目经理一样自行决定调用哪些技能、以什么顺序调用。固定的活儿交给管线开放的活儿交给编排器这个分工极大简化了我的系统架构也让技能的价值发挥得更充分。5.3 技能编排的收敛条件最后加一个我在实际调试中总结的经验组合最终要“收敛”。也就是说无论技能链多长最终必须在一个明确的点上产出用户能看到的结果并且这个结果必须带有完整的溯源。我在编排配置里专门设计了一个终端条件——管线中必须有一个技能声明output_typefinal_answer这样编排器才会结束执行循环否则它会继续尝试组合新技能形成无意义的递归调用。这个设计源于一次线上事故用户问了一个特别简单的问题“公司总部地址是哪里”结果编排器判断需要先检索、再翻译、再生成地图、再分析周边……一连串调用下来又慢又昂贵最后的回答反而不如一个精确检索技能直接返回的地址准确。加了终端条件之后所有管线都必须有一个明确的“输出终点”技能链一旦链到终点就强制终止宁可少配几个中间步骤也不能让链路无休止地延伸。技能编排的本质不是越多越好而是收敛到用户真正需要的结果上。最后再分享一点我这个阶段的心得。Agent技能化不是银弹它不能替代领域知识建模也解决不了模型本身的推理能力问题。它最大的价值是让Agent系统的复杂度变得可控——把“一个什么都会但什么都不精的大杂烩”拆成“一组边界清晰、能力聚焦、可以独立测试和升级的小单元”再用统一的标准把它们组装起来。这套工程化改造也许看起来不如某些“神奇Prompt”那么惊艳但长期跑下来的稳定性和可维护性才是真正扛住真实业务压力的关键。如果你也在做Agent方面的落地项目建议从一个小技能开始改造先把单个技能的输入输出和状态管理做扎实再去想编排和组合。地基打牢了上面无论怎么搭都不会歪得太远。
