去年我重构一个内部知识助手的时候最头疼的并不是模型选型而是每个新场景都要重新拼Prompt、接工具、调参数。同事在A场景里调通的一套动作换到B场景基本作废代码越堆越乱负责维护的人也说不清“这个Agent到底会做什么”。后来我们推倒重来引入了一套独立的技能层skills把Agent能够执行的动作、动作需要的前置判断、失败后的补救措施全部封装成可复用模块。这套思路跑通之后新增一个场景的时间从原来的两三天缩短到半天而且每个技能都能单独测试、单独优化。这篇就把我是怎么理解技能层、怎么封装一个技能、怎么做多技能编排和评估的完整过程写出来顺便把过程中踩过的坑一并交代清楚希望对正在做Agent应用、又觉得“模型很强但系统很糙”的工程师有帮助。1. 先说清楚技能层到底解决什么问题1.1 从“临时拼凑”到“可复用组件”早期团队做Agent路子基本是拿到一个需求把一个API接进去往系统Prompt里写一段“你可以使用以下工具”然后就完事了。模型每次运行都是现场组装读一堆工具定义、临时理解任务、自己决定先调哪个再调哪个。这个模式在小规模Demo里非常好使因为场景小、参数少、失败影响可控。可一旦Agent要面对真实业务比如内部知识库的问答、文件归档、周报汇总、任务拆解问题就暴露出来了同一个动作在三个场景里被重复实现了三次每次的Prompt、参数结构、错误处理还不完全一致。模型表现很依赖上下文里的灵光一现状态一顿跑飞连日志都难定位。技能层就是冲着这个问题去的。它把Agent会做的事拆成一个个独立模块每个模块不只是“一个函数”而是一整套行为规范“什么时候调用我”的描述、参数的校验规则、执行过程的前置条件和失败策略、还有从历史经验里沉淀下来的注意事项。有了这层之后模型负责“根据任务选择合适的技能”而技能内部怎么执行、怎么处理异常是程序逻辑的事不需要模型临场发挥。1.2 三个最直接的收益我为什么要坚持这套做法核心是三个收益可复用性。技能一旦封装好就变成了团队内部的公共组件。知识库检索技能个人助手能用客服问答能用运营数据分析Agent同样能用。不用每次重写也不用担心改了一个地方影响另外几个场景。可观测性。每个技能有明确的输入输出结构有自己的触发日志、成功率和失败分布。出问题的时候能明确知道是模型的技能选择错了还是技能内部逻辑坏了不用对着整个Agent的冗长对话记录一点点猜。可组合性。Agent本身变成了一根比较“轻”的调度线真正干活的是背后一串技能。新业务来了先看现有技能库能不能覆盖覆盖不了就加一个新技能而不是把整个Agent推倒重来。用个表格对比一下传统写法和技能层写法会更直观维度传统写法技能层写法一个动作的定义散落在Prompt和工具函数里集中封装为一个技能模块复用方式复制粘贴后改参数直接引用并测试错误处理模型自己想办法技能内部有完整的失败策略可测试性只能端到端测试整个Agent每个技能单独测试新增场景成本改动Prompt可能影响旧场景新增/调整技能风险可控1.3 一个“假忙”的反面案例我经常用这个反面案例来说明什么是没有技能层的“假忙”。假设你让一个Agent“把这份周报存到指定目录”传统实现里模型会调用一个save_file工具传入路径和内容。一切顺利的话它确实存进去了但如果目标目录不存在呢如果重名了呢如果写入权限不够呢模型通常不会提前检查目录因为它只知道自己有个保存文件的工具并不知道这个动作的“完整成功条件”是什么。结果就是模型返回“好的文件已保存”实际上系统把文件写入失败的错误吞掉了或者创建了一个奇怪路径。这不是模型蠢而是我们根本没有给它定义“保存文件”这个技能的完整行为协议。真实世界的动作往往有前置条件、有后置校验、有异常分支技能层要做的就是把这一整套东西固化下来让Agent每次执行都走完整流程而不是碰运气。2. 技能到底是什么比“工具”更重的一层2.1 工具只描述“能做什么”技能还描述“怎么做好”很多做Agent的开发者会把“技能”和“工具”混为一谈。在我看来工具是一个轻量的能力声明告诉模型“我能干这个”技能则是一个完整的执行单元包含对这个能力的边界、前提、步骤、异常处理和验证方式的全部定义。举个例子。一个HTTP请求工具模型拿到它就知道“我能发GET/POST请求”但发请求之前要不要鉴权请求失败要不要重试响应返回之后要不要校验字段这些工具不管模型也不知道该不该管。如果封装成“网页内容抓取技能”它的内部就明确规定先判断目标URL是否在白名单、请求超时时间是多久、抓取结果要转成什么结构、抓不到的时候怎么降级处理。模型只需要决定“这个任务适合用网页抓取技能来做”剩下的交给技能执行器稳定得多。2.2 一个技能的四要素我在实际设计技能模块时固定用四个要素来约束一个技能的完整性。总结成表格方便参考要素内容作用能力描述何时调用、何时不调用、输入输出范围帮助模型做技能选择执行协议前置条件、动作序列、失败策略保证动作稳定落地输入输出契约参数校验、返回结构、错误口径保证技能之间能互通经验上下文少量示例、禁忌事项、历史教训减少模型的临场发挥空间能力描述直接喂给模型写在函数描述或系统提示里要写得具体。比如“当用户要求把一段文本按日期归档到知识库时使用此技能。注意仅用于归档不负责内容创作也不负责权限审批。”为什么要加“不负责”的部分因为模型经常过度调用把不相关的任务也塞给这个技能写上反例能显著降低误触发率。执行协议是技能的函数体逻辑这里面不光有正常流程还有前置校验和异常分支。以“文件归档”技能为例执行协议包括目标目录存在吗不存在就创建有同名文件吗有就按时间戳改名写入后做一次读取校验确认内容一致才能返回成功。这些步骤全部固化在代码里模型不需要思考也避免模型乱猜。输入输出契约很好理解就是参数和返回值的统一格式。我通常会把所有技能的返回包一层统一是{status: success|failed|partial, data: ..., error: ...}。这样编排层处理结果的时候很好写不用每个技能一套格式。经验上下文是最容易被忽略的。我会在技能定义里附带5到8条约100~200字的注意事项和典型案例比如“上次遇到目录名字带空格导致解析失败所以参数规范化时必须去除首尾空格”。这些经验不需要模型自己总结你直接告诉它。注意量不要太大太长反而干扰模型对技能边界的判断。2.3 怎么判断一个动作够不够“技能级”不是所有函数都要封装成技能否则维护成本反而失控。我给动作设了三个硬门槛能不能独立测试有没有明确的输入输出边界存不存在需要固化的失败处理能独立测试意味着这个动作不依赖Agent运行时的临时状态比如“发送邮件”可以独立测试“根据对话情绪决定是否发送邮件”就不适合做技能本身它更像是编排逻辑。明确输入输出边界意味着参数能写成Schema不带模糊字段。有失败处理则意味着代码里要有实际校验和异常分支而不是“直接调API失败了返回报错”就完事。按这个标准很多动作其实用普通工具函数就够了比如“计算两个日期的间隔”技能层只承接那些需要完整行为协议的关键动作。3. 从零写一个技能的完整过程3.1 第一步划定边界我拿“日报汇总”这个技能当例子拆解全程。它的任务是从一堆零散的工作记录里整理出结构化的日报文本。设计边界时我明确规定它只负责内容汇总和格式化不负责读取数据库、不负责发送邮件、不负责判断权限。这三个“不负责”直接写进能力描述防止模型顺手把别的工作让技能干。边界划得越清楚后面执行逻辑越好写。如果边界模糊技能函数里就会塞进各种乱七八糟的IO操作最后变成一坨没人敢动的代码。3.2 第二步写能力描述与参数Schema能力描述要写成给模型看的“使用说明书”。我的写法是当用户需要把零散的工作记录整理成日报时使用此技能。输入字段包括工作内容列表、日期、汇总范围。仅负责内容汇总与段落组织不负责发送、不负责权限校验。若输入内容为空返回failed状态并提示补充材料。这段描述里既有正面的“什么时候用”也有反面的“不负责什么”模型选技能的时候能快速对齐意图。参数Schema我用JSON Schema组织下面是这个技能的核心结构{ name: daily_report_summary, description: 将零散的工作记录整理为结构化日报, parameters: { type: object, properties: { records: { type: array, items: { type: object, properties: { time: {type: string, description: 工作发生时间格式YYYY-MM-DD HH:mm}, content: {type: string, description: 工作内容描述} }, required: [time, content] } }, date: {type: string, description: 日报对应的日期}, focus: {type: string, enum: [summary, detail], description: 汇总粒度默认summary} }, required: [records, date] } }最关键的是每个字段的description要写清楚。模型填参的准确率很大程度上取决于字段描述是否具体。比如time字段如果不加“格式YYYY-MM-DD HH:mm”模型可能会传时间戳、传“昨天”、传“下午3点”这种乱七八糟的值。3.3 第三步实现执行函数函数内部我坚持一条原则参数先进来先做完整校验再进入核心逻辑。校验不通过就立刻返回错误绝对不要试图在函数里强行清洗各种异常数据那是给后续埋坑。def daily_report_summary(records: list[dict], date: str, focus: str summary) - dict: # 1. 参数校验 if not records: return {status: failed, data: None, error: records不能为空} if not date or len(date) ! 10: return {status: failed, data: None, error: date格式不正确应为YYYY-MM-DD} # 2. 排序与分组 valid_records [ r for r in records if r.get(time) and r.get(content) ] if not valid_records: return {status: failed, data: None, error: 没有可汇总的有效记录} sorted_records sorted(valid_records, keylambda r: r[time]) # 3. 按粒度生成内容 if focus detail: lines [f{r[time]}{r[content]} for r in sorted_records] summary_text \n.join(lines) else: summary_text .join(r[content] for r in sorted_records) # 4. 返回统一结构 return { status: success, data: { date: date, summary: summary_text, record_count: len(sorted_records) }, error: None }把校验放在最前面有两个好处。一是错误能第一时间暴露方便定位是模型传参问题还是业务逻辑问题二是后续代码不需要到处判断空值逻辑清爽。实际项目里这段函数还会更长比如对超长内容做截断、去重、敏感词过滤但结构与这个示例一致。3.4 第四步注入经验与少量示例函数写完后我不急着把技能扔给模型而是补一段经验上下文。比如这个日报技能我会附上两条当某条记录内容为空或只有“无”字时直接过滤掉不要生成到日报里。如果两条记录时间相同且内容相似保留内容更长的一条作为对同一个事项的补充记录处理。经验文本要写“可执行的规则”不要写“注意准确性”这类正确的废话。模型不需要你告诉它要准确它需要的是判断逻辑。3.5 第五步注册进Agent调度循环技能封装好之后要注册到Agent主循环里。我用一个简单的注册表管理SKILL_REGISTRY {} def register_skill(name, description, handler): SKILL_REGISTRY[name] { description: description, handler: handler, schema: load_schema(name) } register_skill( namedaily_report_summary, description当用户需要把零散工作记录整理成日报时使用, handlerdaily_report_summary )Agent运行时调度器把用户请求和所有技能描述放在一起让模型选一个技能并填好参数然后调度器根据技能名找到handler执行。这一步的核心是模型只负责“选技能、填参数”不负责“执行过程”也不能跳过技能框架直接回答。实际项目里我会在注册时记录技能的版本号这样每次改动技能逻辑老版本的日志还能追溯方便对比新旧效果差异。3.6 为什么参数校验放在技能内部有一个设计细节值得展开参数Schema只是“引导”模型填参真正的参数校验必须放在技能执行函数内部。原因是模型生成参数是概率性的即使Schema写得很清楚偶尔还是会抽出超出枚举范围或者类型不对的值。如果执行函数直接按最优假设去跑数据就会污染下游逻辑。比如focus字段如果模型传了“的中文”排序函数不会报错但生成结果会走错分支。所以参数校验是技能内部的第一道闸门校验不过就返回明确错误让上层决定是重新让模型选技能还是直接给用户反馈。4. 多技能协同编排才是真正的难点单技能封装完成后真正复杂的是同一个任务往往要串起多个技能。以“新建客户跟进计划”为例它可能涉及知识库检索、客户信息查询、日程创建、邮件草稿生成四个技能。怎么让它们在正确顺序下协作就是编排层的事。4.1 三种编排方式对比编排方式适用场景优点缺点线性编排步骤固定、强依赖稳定、易调试不灵活无法处理分支条件编排存在明确分支规则逻辑可控效率高分支判断需要提前设计模型自主编排任务开放、依赖不明确灵活能应对未知情况不稳定失败排查成本高我目前采用混合编排整体流程用线性或条件编排把大框架定住框架内的某个节点上再允许模型在候选技能里自主选择。这样既保证了大方向不跑偏又保留了灵活性。4.2 技能之间要约定“握手规则”多技能协作最大的问题是“前一个技能成功但后一个技能不知道前一个技能做了什么”。我建议在编排层设定两条握手规则先感知后行动。凡是涉及写入、变更、发送类动作前面必须有一个感知类技能做前置检查。比如“生成日报草稿”后面接“发送邮件”之前先跑一遍“检查收件人合法性”技能。听起来多了一次调用但能把后续投诉和失败的概率降一半以上。先检查再写入。写入类技能执行前要确认目标位置的状态。一个典型的例子Agent帮用户归档文件到指定目录正规流程是先用文件查询技能确认目录存在和文件重名状态再调用归档技能执行写入。不然就会回到我开头说的“假忙”状态。4.3 冲突处理和失败回滚技能编排过程中最容易被忽略的是中间步骤失败后怎么办。比如日程创建成功了但邮件草稿生成失败整体任务应该被标记为失败吗还是继续执行我给出的方案是把任务执行链路分成“关键动作”和“非关键动作”。关键动作比如创建日程、发送通知失败时直接终止整个任务并回滚已产生的副作用非关键动作比如生成一段摘要、记录日志失败则记录警告后继续主流程。回滚也不一定非要彻底撤销很多场景下“补偿”就够了。日程已经建好但用户取消整个任务可以让技能针对这个新建的日程发起“取消日程”调用这比强行删除一份记录更安全。4.4 编排层要不要交给模型这是团队里争论很久的一个问题。轨道一全盘让模型自主编排模型读一堆技能描述然后自己决定调用顺序。轨道二用代码写死整个编排模型只负责技能节点的参数填充。我的倾向是主干规则用代码写死分支节点用模型自主选择。原因很简单Agent面向真实业务时稳定性优先级高于灵活性。如果整个编排都交给模型一次语义理解偏差可能导致整条链路崩溃而且日志排查困难。保留一点“模型决策空间”是好的但要有边界。比如“客户跟进计划”这个任务代码负责定义流程骨架模型只在“通过什么方式触达客户”这个分支上从电话、邮件、短信三种技能里选一个。这样既保证了最终结果结构一致又给了模型发挥余地。5. 技能库的评估和迭代你测的不该只有准确率很多团队把技能写完就扔给Agent用效果全靠“肉眼观察”。前几个月还行随着Agent调用次数增加模型升级一版偏差就开始冒出来。技能库需要一套自己的评估体系和业务准确率分开看。5.1 单技能四类指标我自己的技能评估从四个维度拆解指标含义参考口径触发准确率该调用时调了不该调用时没调误触发次数 / 总调用次数执行成功率技能内部逻辑成功完成的比例成功返回次数 / 调用次数参数质量参数校验一次通过的比例首次通过校验次数 / 调用次数失败恢复率失败后能通过重试或降级恢复的比例恢复成功次数 / 失败次数看起来有点重但四个数凑齐之后问题定位就非常顺。触发准确率低说明能力描述写得不够清楚执行成功率低说明函数内部逻辑或外部依赖有问题参数质量低说明字段描述和Schema不够明确失败恢复率低说明异常分支设计不足。以我手头那个知识助手为例上线初期参数质量只有68%大量调用都在“参数校验”这一步被拦下来。后来我把每个字段的描述加长、补充枚举和格式示例参数质量涨到92%整个Agent的端到端成功率上了一大截。模型填参这件小事直接影响系统质量。5.2 技能漂移模型升级后的隐形风险技能漂移是我最近体会最深的一个现象。基础模型升级之后技能的触发行为有时会发生肉眼可见的变化即使你什么都没改。有一次团队做完模型升级第二天日志里一个“文件归档”技能的调用量从每天300次掉到80次用户反馈归档失败。排查半天发现新模型对能力描述里的“归档”一词理解方式变了它倾向于优先调用“文件整理”技能把归档当成整理的一个子步骤。函数本身没有问题是模型的技能选择策略变了。从那以后我定了一条规矩每次上游模型升级必须先把技能库的回归测试集跑一遍验证每个技能的触发准确率和执行成功率没有大幅波动再决定要不要调整技能描述。5.3 技能描述、Schema、代码、经验的版本绑定技能的版本管理比普通代码版本管理繁琐因为一个技能涉及四份内容能力描述文本、参数Schema、执行函数、经验上下文。这四份内容任一变化都可能影响技能表现必须绑定成一个版本号。我习惯把每个技能定义为目录里的一个子模块版本号放在模块目录下的一个skill.yaml里name: daily_report_summary version: 3.2.0 description_file: description.md schema_file: schema.json handler_file: handler.py examples_file: examples.md升级的时候一次性修改这些文件统一发版。排查线上问题时直接看日志里的技能版本号就知道当时用的是哪一套描述、哪个版本的Schema不用靠猜。5.4 从误触发和失败日志里迭代技能库优化的素材主要来自Agent日志里的两类脏数据误触发记录和失败记录。误触发指的是模型在不需要某个技能时调用了它。比如用户只是问“日报模板长什么样”模型却真的调用了“日报汇总”技能白白消耗时间和额度。处理方式是找出这些误触发样本在能力描述里加一句“仅当存在需要汇总的工作记录时使用查询模板不是此技能职责”。失败记录处理方式类似把失败案例按原因聚类给执行函数加分支处理。比如发现大量失败是因为“用户输入里包含邮件列表格式”就在函数里加一个解析逻辑。技能是靠真实数据一步步喂大的不是一次设计到位。6. 踩坑清单这些坑不写出来对不起读者积累了大半年技能层经验按踩坑频率排序下面几个问题在团队里反复出现。如果你也打算用这个架构建议提前绕开。6.1 技能描述写得太宽泛模型拿它当万能卡片第一次给技能写描述的时候我犯的错误是写“处理用户提供的各种文本内容可生成日报、周报、月报”。结果模型碰到任何文本整理请求都优先调用这个技能连“翻译一段英文”都试图让它处理。这是最典型的误触发原因。后来把描述改成条件式的“当输入为多条零散工作记录且需要按时间整理成结构化日报时使用此技能翻译、润色、摘要等任务请调用其他技能。”加了“不负责”清单后误触发率立竿见影地降下来。6.2 参数校验没有放第一个脏数据到处流一开始我以为参数校验写进Schema就完事了函数内部直接开始跑业务逻辑。结果模型传过来一个date今天代码硬是把它当成合法字符串往数据库里写后续查询全部对比不上。现在所有技能内部第一行就是校验校验不过直接返回status: failed绝不放行脏数据。这保证了上层记录的日志和错误都是可解释的而不是“数据库里混进一条奇怪数据”。6.3 经验上下文塞太满模型反而犹豫经验是越多越好吗我一度把平时踩过的坑全部写进技能的经验文件里最后一份日报技能的说明有将近2000字。结果模型在触发技能时频繁犹豫有时甚至因为读了太多“禁忌”而误判任务不该做。压缩到每项技能400字以内的注意事项之后触发决策明显干脆了。经验上下文的定位是“快速校准模型判断”不是“完整历史档案”。想沉淀细节放在代码注释和架构文档里更合适。6.4 技能命名太相似模型触发混乱团队里有人起过“生成报告”“生成报告摘要”“生成报告全文”三个技能名字相近、描述重叠模型经常选错。后来我们定了技能命名规范动作对象禁止同义词堆叠比如“summary_daily_report”和“create_daily_report”对象完全不一样触发边界才分得清。6.5 一心想做“万能技能”结果谁都用不好早期我总想设计一个“高级分析技能”输入任意数据自动选择分析算法、画图、出结论。理想很丰满实际给模型带来的决策负担太大参数经常填得乱七八糟输出质量完全不可控。后来拆成“趋势统计”“异常检测”“图表生成”三个技能每个都窄但每个都稳。组合起来反而能覆盖原来那个万能技能的大部分能力出错时定位也更清楚。技能设计的哲学永远是窄而稳优于宽而虚。拿我自己现在的项目来说只要涉及Agent功能迭代我会先问“这里需要新技能还是改旧技能”而不是直接改Prompt。每个技能都在独立版本、独立测试、独立评估的状态下演进整体的可维护性比刚起步时高了不止一个量级。最后分享一个小习惯每次上游模型宣布升级我会第一时间跑一遍技能库的回归测试集。别觉得新模型只会变强它的意图理解方式很可能和旧模型不同描述和Schema换了一版之后触发准确率才守得住。