1. 为什么agent-skills成为AI工程化绕不开的话题做AI应用开发这两年一个很明显的感受是模型能力的天花板已经不是瓶颈真正拉开差距的是围绕模型构建起来的技能体系。我们团队从最早直接调API、写Prompt到后来不得不独立维护一套agent技能层这个转变几乎是被迫发生的——当你发现同一个模型在不同任务上的表现可以相差一个数量级问题往往不在模型本身而在你有没有把它调教成一把趁手的工具。所谓agent-skills落地到工程上就是一套可复用、可组合、可评测的能力单元。它既要解决模型会做什么的问题还要解决怎么做得稳、怎么做得好的问题。早期我们天真地以为给GPT或者其他大模型一个好的System Prompt它就能稳定完成复杂任务。实测下来Prompt能解决意图理解但解决不了工具使用多步规划错误恢复这些需要工程化支撑的环节。这篇文章我不会去拽论文里的概念就说说agent-skills在我的实战视角下到底是什么、怎么拆、怎么用、怎么避坑。如果你正在做Agent产品或者准备在业务里引入大模型做自动化这里面大部分内容应该是可以直接拿来参考的。2. 拆解agent-skills技能不是Prompt而是完整的最小执行单元很多人的第一反应是skills不就是在Prompt里多写几条指令吗这个理解其实差得比较远。2.1 从一段真实代码说起我们第一个成熟的agent技能是做舆情摘要自动生成。最初的做法很朴素把新闻列表塞进Prompt让模型输出摘要。结果可想而知——输出格式不稳定不同来源的新闻处理规则不统一偶尔还出现幻觉数据。后来我们重构了整个技能结构// 一个agent skill的典型结构 interface AgentSkill { id: string; // 技能唯一标识 description: string; // 给模型看的技能描述用于决策路由 inputSchema: Recordstring, any; // 结构化入参定义 execute(): PromiseSkillResult; // 实际执行逻辑 rollback?(): Promisevoid; // 失败回滚 metrics: { successRate: number; // 历史成功率 avgLatency: number; // 平均耗时 cost: number; // 平均token成本 } }关键点在于技能的本质是一个独立的最小执行单元它把模型的决策和程序的执行解耦。模型只负责判断现在应该调用哪个技能而技能内部的逻辑是确定性代码——数据清洗、格式校验、API调用、兜底逻辑。这套架构跑了大半年舆情摘要的生成成功率从86%提升到了98.6%主要功劳不在模型升级而在技能层的稳定化。2.2 技能的三个必要组成拆开看一个合格的agent技能必须包含三块。第一是能力边界描述。这一步是给模型做路由用的写清楚这个技能做什么、不做什么、在什么条件下调用。很多人忽略的是给模型看的技能描述和给工程师看的接口文档完全是两码事。技能描述要用模型能理解的语义写不能太抽象也不能太具体。例如summarize_new这类描述模型大概率会把它和普通总结混淆改成summarize_latest_news_feed并注明输入是RSS抓取结果输出是面向管理层的一页纸摘要路由准确率会明显提升。第二是确定性执行逻辑。技能的每一步最好都是可测试的确定性逻辑。比如摘要生成前的HTML正文抽取我们用readability库做不用模型做摘要后的关键数字校验用正则做也不用模型做。模型只负责总结归纳这一个真正需要创造力的环节。这样分割后出问题时的排查范围会小很多。第三是结果质量的自评估机制。每个技能执行完不能让结果就这么过去了。我们的做法是内置一层自检逻辑如果是生成类技能会用关键词和格式规则做快速校验如果是工具类技能会检查返回状态的完整性如果是多步任务每步都要记录中间状态。这个自检逻辑不复杂但它让整个agent系统的可观测性上了一个台阶。2.3 技能的组织方式从单技能到技能库单个技能解决单点问题多个技能组合起来才能处理复杂任务。我们现在维护的技能库分了三个层次基础技能通用能力比如网页抓取、文本清洗、格式转换、API调用。这些技能几乎不会变独立在任何业务逻辑之上。业务技能与具体场景绑定比如舆情摘要、竞品分析、客服工单分类。每个业务技能会调用多个基础技能。决策技能用于规划与控制比如任务拆解、工具选择、异常处理策略。这三层之间是单向依赖的上层技能可以调用下层技能下层不能反向依赖上层。这个约束让技能库的维护成本大幅降低不会出现改一个基础逻辑全库回归的噩梦。3. 技能工程的核心战场工具调用与上下文管理如果说技能是Agent的手脚那工具调用就是神经接点。这一节详细说下我们在工具调用和上下文管理上踩过的坑和最终沉淀下来的方案。3.1 工具调用不要指望模型天生就会现在的模型对工具调用的支持越来越好但工程上不能直接依赖这个天赋。我们经历过三个阶段。第一阶段是纯Prompt约定把工具列表和JSON格式写死在Prompt里。这种方式对单工具场景勉强凑合一旦工具超过五个模型选错工具、参数格式错误的情况就会明显上升。第二阶段是Function Calling。主流模型都支持结构化工具调用准确率高了不少。但这个阶段发现的问题是模型对工具的描述理解有限工具说明写得稍微潦草一点它就会传入错误的参数。比如有个工具需要ISO 8601格式的日期接口文档里写得很清楚但模型仍然偶尔传今天或者2024年1月1日这种不规范格式。后来我们强制在工具入参里加了一个$schema描述并配了示例值准确率才上来。第三阶段是工具封装加类型约束。每个工具定义都绑定一个JSON Schema所有入参在进入工具前先做一次校验和类型转换。模型传今天没关系我们先试着用自然语言解析器解析解析不了就抛一个类型错误给模型它就会自己重新调用。这个宽容入参严格校验的设计实际效果比强行要求模型输出完美格式要好得多。3.2 上下文管理的两个极端Agent的上下文管理是最容易被低估的工程难点。我们踩过的最大的坑是把所有历史对话和工具执行结果都塞进上下文结果模型越到后面越迟钝。后来我们把上下文管理拆成三层短期记忆当前任务相关的对话、工具调用记录有明确长度上限。工作记忆正在进行中任务的关键状态比如已确认的目标、已完成的步骤标记。长期记忆跨会话沉淀的用户偏好、领域知识、历史结论。实际操作中短期记忆我们严格控制通常只保留最近的5-8轮对话和最近3次工具调用结果超出部分做摘要压缩。工作记忆用结构化JSON存储确保任务中断后可以恢复。长期记忆统一写到向量数据库里按需检索绝不无脑全量沾进上下文。一个实测数据优化上下文管理后同样一个多轮调研任务模型回答的最终准确率从79%提升到了93%。token消耗还下降了近40%。所以这个环节做好省下来的成本是非常可观的。3.3 长任务的寒武纪大爆发困境做过Agent的人应该都有体会任务越长状态越容易崩。我们内部把这个问题叫寒武纪大爆发——前几步还很顺利突然某一步工具返回了预期之外的数据模型就开始了发散的连环错误如同物种大爆发一样错误也爆开花了。应对方法总结下来就四条每步都做状态校验模型每次调用工具之前先确认前一步的结果是有效、可信的。显式进度追踪用一个全局变量记录当前任务执行到哪一步而不是从上下文里猜。失败分支要预演写技能的时候就把可能出错的分支想在前面准备了重试、降级、请求澄清三套逻辑。定期工作总结长任务每执行5步左右让模型基于已经完成的工作做一个阶段小结summary后清掉部分细节历史防止上下文膨胀。这四条听着简单但真正做到位并不容易。我们是在一次内部项目事故后强制推行下来的那次事故中Agent跑了两百多步最后输出了一篇包含大量重复数据和错误引用的调研报告——问题就是上下文里充斥着几十轮无用的工具中间结果。4. 技能评测如何量化这个技能到底行不行没有评测你就永远不知道自己做的东西在真实场景里发挥了多大作用。技能评测是agent-skills工程体系里最容易被砍掉、但绝对不应该被砍掉的一环。4.1 评测集的建设逻辑我们的评测集不是一次性做出来的而是跟业务一起迭代出来的。核心原则是评测集必须来自真实场景而不是自己编的理想案例。具体做法是在系统上线的第一个月我们雇人把线上失败的案例全部捞回来逐条标注错在哪、期望结果是什么。把这些案例按技能分组每组挑出代表性样本形成回归评测集。之后每次改动技能代码或提示词先跑这组评测集通过才允许上线。这套流程跑下来最有价值的收获不是发现模型问题而是发现了一堆自己都没想清楚的业务规则。比如摘要不能超过400字这条规则模型在大多数情况下都能遵守但遇到某些新闻本身就非常长时模型会把400字误解为必须包含所有关键信息。评测集让我意识到这不是模型的问题是我的指令不够明确。后来把规则改成摘要不超过400字若原文超过2000字允许只概述前三大要点问题就消失了。4.2 评测指标不是只有一个准确率技能的评测指标需要按技能类型分开定义技能类型核心指标辅助指标生成类摘要、写作内容有用性人工评审格式合规率、重复率、关键信息覆盖度抽取类信息提取字段准确率完整率、误报率工具类API调用、数据操作执行成功率平均耗时、异常恢复率决策类任务规划目标达成率步骤冗余度、中途失败率注意生成类技能千万不要只看ROUGE或者BLEU这类文本相似度指标。ROUGE分数高不代表摘要真的有用。我们内部对生成类技能保留了一个有用性评审小组每周抽测50条线上结果人工打分。这个成本看着高但它能拦住很多自动指标看不出来的语义漂移问题。4.3 线上评测黄金数据集与影子模式离线评测集之外线上评测更贴近真实。我们主要用两种方式。一是黄金数据集对比。把一小部分线上流量导入一个黄金版本通常是离线评测效果最好的版本对比黄金版本和线上版本的输出差异差异大的case会捞出来人工看据此决定是否灰度扩大新版本。二是影子模式。新旧系统并行跑但新系统输出不直接展示给用户而是偷偷记录和执行。影子模式的好处是零风险天然获取对比数据。缺点是开发和运维成本高不适合所有场景、所有技能。我们只在变更比较大的技能上启用影子模式。5. Agent技能开发中的高发问题与排查链路技能开发做得久了会发现错误模式非常集中。把高发问题总结出来能帮你节省大量排查时间。我们内部整理了一张阿里斯特最常踩坑清单5.1 模型幻觉与数据验证的拉锯战大模型最诡异的一点是它在生成数字、引用、代码甚至某些事实的时候会以极其自信的口吻输出错误内容。做技能时如果不做数据验证环节幻觉会直接变成线上事故。我印象最深刻的一个case是一个客户数据归因技能模型在总结某地区销售趋势时把环比增幅从0.8%写成了8%而且给出了一个煞有介事的分析理由。如果这个输出直接进入周报系统影响面非常大。又是怎么堵住这个问题的呢我们在生成类技能里加了一层数字校验器凡是summary里出现的百分比、金额、日期必须和上游数据源比对一致才能输出不一致就触发重新生成或者标注数据待确认。加上这个校验之后类似的数字幻觉问题基本清零。这个教训是对Agent输出中的事实性内容永远不要默认模型是对的。让确定性逻辑做一次事实校对成本极低、收益极大。5.2 多技能组合时的冲突与干扰当技能库变大之后新问题出现了不同技能之间会互相干扰。比如舆情摘要技能和竞品分析技能都带一个情感分析基础步骤但它们对情感分类的标准并不一致。舆情摘要把正面/负面/中性三分类竞品分析把强正面/弱正面/中性/弱负面/强负面五分类。如果两个技能共享同一个基础情感分析模块结果经常互相打架。解决思路其实简单粗暴基础技能必须做到足够中性而业务差异放在业务技能层处理。情感分析基础模块只输出倾向性得分-1到1之间的浮点数业务技能自己决定如何把得分映射到自己的分类体系。这样既保留共享能力又不会互相干扰。5.3 排查链路一次Agent发疯的完整复盘说一个实际发生的排查案例过程很有代表性。现象是这样的一个做自动报价单生成的Agent忽然某天开始给客户报价时频繁多了莫名其妙的折扣而且折扣比例完全没有逻辑。第一反应是模型提示词被改了——排查后发现没有。然后怀疑是工具调用参数乱了回查日志后发现Agent在处理一个新请求时由于历史上下文里存在一个促销季折扣的旧会话记录它把这个旧信息错误地带入了当前报价任务。根因是长期记忆的检索召回出了问题。向量检索把折扣相关的旧会话记录召回后没有做足够的时效性过滤Agent误以为这是当前任务的一部分。修复方案分两步第一步在长期记忆入库时强制写入时间戳和会话ID检索时对这些元数据做过滤第二步添加一个可能过期的信息提示让模型在引用历史记录时主动判断时效性。这个case做完之后我们把相似的保护性逻辑推广到了所有会访问长期记忆的技能里。现在无论是检索还是引用历史信息都必须附带时间上下文否则模型无法区分这是一条历史事实还是这是当前任务的状态。6. 把Agent技能做成团队资产工程化与协作机制Agent技能写到一定程度就不再是个人代码而是一个团队甚至一个组织需要维护的资产。工程化与协作机制的缺失会导致技能库快速腐化。6.1 技能版本管理与灰度发布技能的迭代频率比传统后端接口高得多因为除了代码逻辑还有提示词、工具定义、上下文策略这些都需要反复调。如果不做版本管理改着改着就乱套。我们采用的方式是三级版本策略版本层级说明更新频率大版本v1/v2技能架构、工具链发生重大变化月度级中版本v1.4技能行为有明显调整比如新增工具、变更流程周级别小版本v1.4.2提示词细节、参数微调不改变行为边界天级别所有小版本都先走离线评测集通过后再灰度。灰度分三档1%流量观察10%流量放量50%流量确认最后全量。不要嫌麻烦Agent技能的灰度比传统接口更重要因为模型是非确定性的你永远不知道某个提示词的改动在真实流量里会触发什么连锁反应。6.2 技能文档与知识库建设写文档这件事在Agent技能开发中优先级极高。原因很实际技能的行为边界如果只存在于代码里那当模型开始做奇怪操作时你很难判断这是bug还是特性。我们给每个技能规范了文档模板技能用途和边界给人和模型同时看依赖的基础技能输入输出Schema已知失败场景与降级策略评测集摘要与历史表现这份文档模板写得并不复杂但它让技能库不再是一个黑盒。新同学接手也能快速知道每个技能的行为边界知道遇到什么问题该找哪个负责人。6.3 跨团队协作的通用技能市场当多个团队都在开发Agent时去重与共享就很有价值了。我们在公司内部搭建了一个技能市场每个团队把自己沉淀的技能发布到市场里其他团队按需引用。市场上有两个约束任何技能上线市场前必须通过质量评审不合格的不能发布。技能可以引用其他技能但引用关系必须可追踪不能出现循环引用和隐藏依赖。这个市场推行的头两个月效果一般大家还是习惯各写各的。转折点是有人把中文地址清洗这个基础技能共享出来后几乎每个做业务Agent的团队都引用上了——因为大家都遇到过中文地址格式混乱但谁都不想自己写一遍这段逻辑。从那之后有类似的先去市场上找慢慢成了团队习惯。7. 预算、成本与性能的平衡术最后说一个偏工程化但大概率躲不开的话题Agent系统的成本与性能。7.1 Token成本怎么算才准很多团队初期对Agent成本的预估严重不准核心原因是他们只用单次调用的token价格算成本忽略了Agent任务通常是一个多步循环。一个简单的联网查询并总结任务可能需要查询意图识别、调用搜索工具、读取结果、再总结、再格式化总共5次模型调用。我们后来建了一个内部成本模型单次任务成本 模型调用次数 × 平均输入Token数 × 输入价格 模型调用次数 × 平均输出Token数 × 输出价格 工具执行成本API调用、数据库查询这个公式看似简单但能让人一眼看出哪个环节才是成本大头。我们优化后把单任务的模型调用次数从平均7次降到了4.2次直接让系统总成本下降了38%。降下来的主要手段不是换便宜模型而是做好技能复用与上下文管理减少无用调用。7.2 模型降级策略不同技能对模型能力的要求差异很大。客户服务场景里的情感判断和任务拆解用满血旗舰模型但像实体抽取这种高度结构化的事中档模型就够了。我们内部给每个技能标注了模型能力要求等级自动路由到不同档次的模型而不是一刀切全用最强模型。这个策略让整体成本降了大概30%效果没有明显下降。对于一个Agent产品来说这笔账怎么算都划算。7.3 响应速度与流式输出Agent的响应延迟影响用户体验尤其涉及多轮工具调用时用户等着等着就容易流失。我们做的不多但每一条都有效第一次模型响应采用流式输出让用户尽快看到有东西在发生。工具调用环节加一个进度提示事件告诉用户当前正在做什么操作。可并行的工具调用尽量并行不要让模型串行等。设置了单步超时和总任务超时超时就走降级流程。这四条做完用户的等待焦虑明显缓解。技术上没有太复杂的核心价值在于让用户对系统状态有预期。8. 一点个人沉淀从我自己的经验看agent-skills这件事最重要的一点是不要被大模型什么都能做冲昏头脑真正稳定的Agent系统一定是模型的智能决策和工程的确定性逻辑的紧密结合。技能层就是这两者的粘合剂。把每一个技能做成一个边界清晰、可评测、可复用的最小执行单元系统整体的稳定性、可维护性和可扩展性都会得到改善。如果你正打算开始搭建Agent系统我的建议很简单先列业务场景里最常遇到的20个任务不要贪多。每个任务先画步骤图标清楚哪些环节必须确定性强哪些环节需要模型创造。确定性环节用代码实现创造性环节再交给模型。从第一个技能开始就写评测集和文档不要等做完了再补。这样出来的系统才是能真正跑在生产环境里、让业务敢用的Agent而不是一个只能在演示视频里大放异彩的玩具。