从“agent-skills”这个标题聊起。最近在复盘我这边一个已经跑了半年的Agent项目最深的感触就是搭一个能跑通Demo的Agent不难难的是让它在真实业务里稳定、可靠、不跑偏。而这个“稳定可靠”的关键很大程度上就落在标题里这两个词上——agent skills。我理解所谓Agent的技能层就是让大模型从“什么都懂一点”变成“在某些事情上真的能干”。这篇文章就从我实践的角度拆一拆Agent技能怎么设计、怎么实现、怎么避坑给正在做同类项目的朋友一些可参考的思路。先说清楚这个内容能解决什么问题如果你的Agent经常答非所问、工具调用不准、或者同样的任务换个说法就不会做了那问题大概率不在模型本身而在技能层的设计。适合谁来读正在做Agent应用开发、想做一套可复用的Agent能力体系、或者被Prompt和工具调用折磨得够呛的工程师这篇应该能对你有用。1. 技能层在Agent架构里的定位与整体设计思路很多刚接触Agent的人会有一个误区以为把大模型的API接上再给它一堆工具函数它就能干活了。实际上不是这样。模型确实会用工具但它怎么选工具、怎么传参数、怎么处理工具的返回结果这中间每一个环节都可能出错。技能层就是在这个环节上做约束和增强的——它本质上是夹在模型和真实世界之间的一层“能力适配器”。1.1 为什么大模型需要独立于提示词之外的技能层先讲一个我踩过的坑。最早做Agent原型的时候我把所有的工具说明直接塞进System Prompt里一次塞了大概十几个函数。结果是什么呢模型确实能调用但经常选错工具或者在不需要调用工具的时候强行调用。最离谱的一次用户只是问了一句“现在几点了”模型居然调用了发邮件的工具——虽然最后参数里没有收件人但这个行为本身已经说明问题了。后来我把这个问题归因于两个层面第一工具的语义和用户的意图之间距离太远模型缺乏足够的中间层来做匹配第二工具数量一旦超过某个阈值Prompt里的信息密度就会下降模型会“看不清”该用哪个。技能层解决的就是这两件事。它在工具之上再做一层封装把工具按业务场景重新组织每个技能自带触发条件、调用约束、参数规范和结果处理逻辑。模型面对的不再是一个扁平的函数列表而是一组有语义边界的“能力块”。你可以把它理解为工具函数是零件技能是组装好的机器模型只需要按需选择机器而不是当场去搞懂每个零件该怎么用。1.2 技能注册表与技能模板让Agent的能力可编排我这边Agent技能管理的核心是一个技能注册表用JSON格式维护每个技能有固定的字段。上个月刚重构了一版具体结构长这样skill: name: translate_document version: 2.1.0 description: 翻译文档内容支持中英日韩四语互译 triggers: - 关键词: [翻译, 翻一下, 译成, translate] - 意图区间: [0.85, 1.0] params: target_lang: type: string enum: [zh, en, ja, ko] required: true document_text: type: string max_length: 5000 required: true executor: type: function_call endpoint: agent.translate timeout_ms: 5000 output_schema: translated_text: string fallback: - summarization_alias这套结构里最重要的是两个字段triggers和executor。triggers决定了模型什么时候该想起来用这个技能executor决定了实际执行的动作。我把触发条件分成两种信号的组合表面信号关键词命中和深层信号语义相似度。双信号的好处是既能做到“看到翻译两个字就触发”也能做到“用户说‘这段我看不懂帮我弄成英文的’时也能触发”。注册表本身是可以在运行时动态增删的这给了系统很大的灵活性。比如业务侧临时加了一个需求只要往注册表里注册新技能模型在下一次会话中就能感知到。不用改代码不用重新部署这也是我最终放弃把所有技能写死在代码里的原因。1.3 方案选型背后的关键权衡其实在设计技能层的初期团队讨论过两条路线一条是把技能逻辑写成Python类每个技能对应一个类另一条就是我现在用的声明式注册表方案。Python类方案的问题在于技能与代码强耦合每加一个技能都要发版而且模型侧无法直接看到技能的结构只能通过拼接后的描述来理解容易失真。声明式方案的优势在于技能的描述、参数、执行入口都是纯数据。这带来两个好处第一可以用统一的方法把它渲染成Prompt片段给模型看第二可以做一个简单的内部管理后台非开发人员也能配置技能这在业务侧推进时帮助很大。当然声明式的代价也很明显它要求技能被严格标准化复杂的业务逻辑很难塞进去。我的做法是把技能定义为“薄封装”——复杂的计算逻辑仍然放在背后的服务里技能本身只负责描述、路由和参数转换。作为边界控制器它不亲自干活但必须知道谁适合干什么活让模型做出靠谱的决定。2. 核心技能模块的拆解与实现要点前面说了总体的架构思路这一部分拆到技能模块内部看看一个技能从声明到真正跑起来中间有哪些关键细节。很多人实现的技能不好用往往就是卡在这些细节上。2.1 技能触发机制的实现关键词命中与语义混合路由技能的触发我采用了两级路由。第一级是关键词和规则引擎第二级是语义相似度模型。这样组合的原因很简单关键词快但死板语义灵活但慢且有误判风险。规则引擎部分我挂了两个工具库一个是正则表达式匹配处理“把XXX翻译成英文”这种带变量的表达另一个是实体识别专门抽取文件名、时间、产品名等关键实体。正则匹配的方法很简单——命中关键词就给出候选得分通过加权公式把实体抽取出的变量一并计算初步确定该给用户推荐哪个技能。语义路由部分用的是模型输出的分布特征。我们给模型输入用户原话和候选技能描述让模型输出每个技能的匹配分数取高于阈值的和前三名作为候选。这样下来触发准确率能做到87%左右。剩下那13%的误触发或漏触发再靠后续计划编排来弥补。实操中最需要注意的一点是这个两层触发的阈值不得调过松。我一开始设置阈值偏松导致大量相似意图被并发触发。后来把所有触发阈值统一收紧到0.75以上漏召回率只上升了3%但误触发下降了22%整体体验改观明显。2.2 技能参数校验与自动补全不能信任大模型的参数这是整个系统里最值得说的一环。等你跑熟了就会发现大模型在决定调用技能时经常“自己发挥”参数格式与定义不符。典型问题是缺少必填参数、参数类型不对、日期格式乱来。我的方案是加了一层参数校验管道流程如下第一步格式校验。用上一步提到的JSON Schema做的结构约束。字段缺失直接拦截。第二步类型转换。模型给的数字可能是字符串要给成number日期可能写“明天”要换算成具体日期。第三步默认值兜底。定义技能时每个参数都尽量给定一个默认值。比如翻译的目标语言用户说“把它翻了”没指定目标语言那就默认按环境变量里的主流语言走。第四步边界约束。超过max_length的文本自动截断或者走摘要技能预处理。这个管道本身不复杂但它把错误卡在模型外面而不是业务里。因为模型调用工具时一旦报错Agent就很容易陷入死循环或者放弃任务。所以宁可在这里多写几行校验也不要让错误扩散到下游。2.3 技能调用编排从单技能到多技能的组合逻辑单技能能做的事毕竟有限。生产环境里的Agent往往需要串联多个技能完成一个复杂的任务。比如用户的会议纪要整理场景就需要先调用会议记录获取技能再调用摘要技能再调用待办提取技能最后调用邮件发送技能。编排方面我目前的实现是一种基于计划模板的方法。每个复杂任务都预定义了一个技能调用模板模板里指定了技能的执行顺序、依赖关系、以及失败时的替代方案。模板并不是死的模型可以根据用户的具体请求做微调。但这个微调被限制在一个范围内不能乱来。举个例子会议纪要任务的模板大概是这样的{ task_type: meeting_minutes, skills: [ {name: get_meeting_records, inputs: {meeting_id: $user_input}}, {name: summarize_document, inputs: {doc: $output.get_meeting_records}}, {name: extract_todos, inputs: {summary: $output.summarize_document}}, {name: send_email, inputs: {content: $output.summarize_document, recipient: $user.specified}} ] }这个模板的好处是Agent不用每次从头想该先做什么、再做什么而是按照模板顺序执行每一步的输入都来自上一步的输出出错时也能清楚定位到是哪个技能出了问题。用大白话打个比方模板像一个做菜的菜谱Agent是厨师菜谱写好了先切菜再炒菜厨师不用每道菜都自己发明流程只负责控制火候和判断实际情况。2.4 上下文管理与技能内部状态避免状态串台技能执行过程中有一个经常被忽略的点是技能内部状态和主对话上下文必须隔离。早期的实现里技能运行过程产生的中间数据都是直接拼接在主对话历史里的结果导致模型经常把上一个任务的数据拿来当当前任务的输入。每月统计的会话中将近十分之一出现了状态串台导致的逻辑混乱这个比例在当时是没法接受的。我现在的做法是为每个技能维护独立的上下文存储。技能执行时只能看到自己的输入参数和外部数据不能读主干上下文。执行结束之后主对话拿到的只有输出结果做成摘要而不是原始中间数据。这样虽然增加了一些存储开销但换来的是任务之间的隔离性。关于输出做摘要这里也有一个细节不是所有技能的输出都值得完整保留。像是数据库查询返回了50行数据如果全部塞回上下文等下一轮对话时信息过载模型就会“忘记”之前用户的需求重心在哪里。所以我给每个技能配了一个summary_strategy字段可以选择保留全量、保留关键字段、或只保留统计信息。这样即使在长会话里Agent也不会跑着跑着把需求搞丢。3. 技能集构建的实操过程与核心环节实现上一部分讲的是单个技能内部的构成这一部分讲怎么从零开始构建一套完整的技能集用在真实业务里。我就以自己在上线过的企业智能客服数据分析模块为例完整走一遍操作过程。3.1 需求分析与技能拆解先列动作再写技能动手写技能之前先从业务需求里拆出动作这一步不能跳。以数据分析模块为例用户的高频需求是查数据、看趋势、做对比、生成图表、写解读。那么对应到技能我拆出如下query_sales_data查询指定时间段的销售数据time_series_trend计算趋势指标环比、同比、均值compare_segments按维度做数据对比generate_chart生成图表图片narrate_insight用自然语言描述数据背后的情况在拆解阶段还有个容易被忽视的点别让技能太细碎也别太粗。太细碎会导致模型需要做很多次调用才能完成任务浪费token也增加失败概率太粗则会让技能描述和参数列表都非常复杂模型更难做出正确的调用。我的标准是一个技能应该能在一到两次工具调用中完成一个用户可感知的原子动作。比如“生成图表”是一个原子动作但“画折线图并加标注”就不是——它需要拆成“选图类型”和“画图”两个技能。3.2 技能实现的代码示例与参数计算过程以time_series_trend这个技能为例它接收一个时间序列数据集及需要计算的指标输出计算结果。这里有一个典型的参数计算过程环比增长率的计算依赖于当前周期值和上一个周期值两者缺一不可。我在参数定义里直接通过Schema约束了每个数据点必须包含value和period字段避免模型传入空字段。这个技能的执行函数我写了一个简化版如下def time_series_trend(data: List[Dict], metrics: List[str]): # 按period排序确保时间顺序正确 sorted_data sorted(data, keylambda x: x[period]) results {} for metric in metrics: if metric mom: # 环比 values [d[value] for d in sorted_data] if len(values) 2: return {error: 至少需要两个周期数据才能计算环比} current values[-1] previous values[-2] mom_rate (current - previous) / previous if previous ! 0 else None results[mom] round(mom_rate * 100, 2) elif metric yoy: # 同比 # 同比计算需要去年同期这里简化处理 current_values [d[value] for d in sorted_data if d[period] current_year_start] last_year_values [d[value] for d in sorted_data if d[period] current_year_start] if not last_year_values: return {error: 缺少去年同期数据无法计算同比} current_sum sum(current_values) / len(current_values) last_year_sum sum(last_year_values) / len(last_year_values) yoy_rate (current_sum - last_year_sum) / last_year_sum if last_year_sum ! 0 else None results[yoy] round(yoy_rate * 100, 2) return {trend: results, latest_period: sorted_data[-1][period]}这里除了算数本身重要的是边界条件的处理。数据不足、除零、数据缺失这三个问题在实际业务里每天都能遇到。如果没有在技能内部拦截返回的是一个报错模型就会在对话里开始“编”数据那跟这个工具本身有关系不推模型。3.3 技能效果调优从72%到91%准确率的参数调整记录技能搭好之后不是直接用一定要先做离线测试。我从历史工单里抽了300条真实用户询问逐一标注了期望调用的技能和期望参数再用Agent跑一遍算准确率。第一轮跑完准确率只有72%。主要问题有三类第一类关于触发条件过于宽泛。比如用户说“帮我看看这个月的表现怎么样”被同时触发了query_sales_data和time_series_trend。解决方式是给触发描述加了约束条件“仅当用户明确提出数据指标或时间范围时才触发”把“看看表现”这种模糊诉求交给主对话澄清。第二类参数缺失。用户说“这几个月的数据对比一下”但没说明月份范围。原先技能直接卡在参数校验失败。后来我调整了校验策略如果用户没说时间范围就默认用最近三个月如果对比维度缺失系统自动识别用户之前提到的维度若没有就用默认维度。在不影响准确性的前提下把参数默认值补充完。第三类模型输出格式不稳定。由于Skill描述是文本形式模型偶尔会直接把技能名拼错或把参数名改掉。后来我在给模型看技能描述时明确加了“参数名必须严格使用以下名称不可缩写不可改写”的约束模型调用格式错误率降到了2%左右。三轮调整之后准确率从72%提到了91%已经能满足业务上线的门槛目前线上的各项统计也比较稳定。3.4 技能间的数据传递与依赖关系管理最后一个实操细节是定义技能之间的数据协议。我统一采用JSON格式每个技能的输出都有确定的“输出Schema”下一个技能依赖上游输出时只取对应JSON路径的值。这里有一个很实用的技巧用JSONPath做数据提取。比如上游技能输出的是{data: {goods: [{name: 电脑, sales: 35}, ...]}}下游技能需要的是“销量总和”我在中间加了一个数据转换层提取后聚合再传给下游。这个转换层是个纯计算组件不涉及模型完全可控。这样做的好处是下游技能无需知道上游的原始结构只依赖转换层给它的聚合结果。在依赖关系管理上我维护了一张技能依赖表每个技能声明自己依赖哪些数据字段由数据转换层统一提供能有效避免“下游技能把上游输出忘掉”的情况。4. 常见问题与排查技巧实录这一部分是从多个版本迭代里沉淀的踩坑记录分开讲方便直接对照。4.1 技能误触发与漏触发怎么办误触发是最常见的问题。症状是用户问AAgent调用了技能B或者一口气把A、B、C全调了。排查步骤是这样的先看技能描述里的触发条件是否过于泛化。比如某技能描述里写了“当用户询问数据相关问题时触发”这句话等于没说——因为几乎所有问题都跟某种数据沾边。正确的写法是明确指出“仅当用户给出具体的数据集名称、字段名称或时间范围时触发”给出明确、可检验的触发约束。另一个排查点是多个技能的触发条件是否重叠。如果两个技能都能处理“查数据”的需求模型就很容易纠结。我处理重叠的办法是给技能加优先级当多个技能得分都高于阈值时优先选择排序靠前的同时把得分次高的作为备选在计划里留着。漏触发往往发生在用户表达的意图比较含蓄时。比如用户说“这季度做了多少生意”如果你没有“销售额”这个关键词匹配触发不了技能。这时候就需要使用语义路由模型来计算用户意图与每一个技能的定义之间的相似度分数。把相似度阈值调整到0.7左右漏触发率会明显下降。4.2 技能调用失败后的恢复策略重试与降级技能执行失败不可避免网络超时、外部服务报错、数据为空每一类都会遇到。我建议从以下三层考虑第一层重试。单个技能调用超时重试一次。注意重试前要确认技能操作本身具备幂等性。比如“发邮件”这个技能重试就要小心重复发送会惹麻烦。建议在技能定义里加一个idempotent字段标记该技能是否可以安全重试。第二层降级。主技能失败后走fallback技能。比如generate_chart技能如果因为图片渲染服务挂了而失败就降级为输出表格数据给用户。我最初开发时对每个技能都挂了fallback后来发现有的技能没有适合的降级路径例如“删除数据”降级成什么都不做更好一点。第三层告知用户。当所有恢复路径都失败时大方告知“当前暂时无法完成这个操作”。与其让模型编造一个虚假的成功结果不如承认失败。从客户满意度看坦诚的失败说明比虚假成功印象更可靠得多。4.3 上下文长度爆炸与技能输出截断策略长会话里很容易碰到上下文爆炸。比如用户连续让Agent做了五次数据分析每次技能输出都保留全量数据不到20轮对话上下文就到了上限。之后模型的质量明显下滑甚至开始“失忆”。我的解决方案是为技能输出设置最大长度限制。超过2000字符的输出自动做摘要。摘要采用分层策略用户关心的是结论就保留结论用户关心的是明细就保留TOP-N明细。对于需要完整结果的场景比如导出数据技能直接提供文件下载链接让用户去查看而不塞进对话上下文。这个做法试了一个多月效果很明显。会话平均轮次从原来常被截断的15轮以内延长到了接近40轮而关键信息的召回率几乎没有下降。4.4 多技能并发与状态隔离的坑最后说一下并发场景。当Agent判断多个技能可以并行执行时比如同时查库存和查价格我在工程实现上用了线程池来并发跑。但这里很容易踩坑多个技能共享了同一个上下文对象写的时候互相覆盖导致结果张冠李戴。我的经验是并发执行时必须为每个技能隔离上下文线程各自持独立的变量副本。Python里用threading.local或者用状态机加任务ID做隔离都可以。我这边目前采用更直接的方式在技能执行前生成一个task_id所有中间状态都挂在task_id下执行结束统一回收。这样无论并发多少技能状态都不会串。4.5 常用问题速查表问题现象可能原因解决方案技能A总是被误调到技能B触发描述重叠描述过于宽泛明确触发条件边界添加优先级参数频繁校验失败模型不理解参数格式或参数描述不清增加参数示例简化参数命名技能输出被截断或遗漏上下文过长摘要策略丢失关键信息按用户关注点分层摘要保留关键明细重试导致重复操作技能操作不具备幂等性幂等性标记非幂等操作禁止无脑重试并发状态下数据串台多技能共享上下文按task_id隔离状态与上下文技能注册后不生效注册表缓存问题强制刷新技能缓存或检查版本号5. 一些个人体会如果让我总结做这个技能层最重要的一句话我会说技能设计是在给模型划定一个舒服的工作区而不是让模型做所有自由发挥。技能太宽模型会迷失技能太窄模型会被困住——找到那个让模型既自由又有边界的中间状态就是整个工程的核心。另外想单独提醒一点技能层的效果不是一次性能调完的。模型本身在升级业务需求在变化用户问法也在改变这就意味着技能库需要有一个常态化的评估与迭代机制。我在线上每周都会抽一批新的用户请求做回归测试每两周更新一次技能注册表。保持这个节奏整个系统才不会随着时间和数据积累逐渐“生锈”。一个意外有用的技巧放在最后给技能描述写示例比写规则更有效。与其写“当用户提到数据时触发”不如给一个具体的示例“用户回答‘销售数据上周环比是多少’时触发”。模型对具体示例的理解和泛化能力往往比抽象规则强得多。这是一件小事但对准确率的提升帮助比我预想的大。
从“agent-skills”这个标题聊起。最近在复盘我这边一个已经跑了半年的Agent项目最深的感触就是搭一个能跑通Demo的Agent不难难的是让它在真实业务里稳定、可靠、不跑偏。而这个“稳定可靠”的关键很大程度上就落在标题里这两个词上——agent skills。我理解所谓Agent的技能层就是让大模型从“什么都懂一点”变成“在某些事情上真的能干”。这篇文章就从我实践的角度拆一拆Agent技能怎么设计、怎么实现、怎么避坑给正在做同类项目的朋友一些可参考的思路。先说清楚这个内容能解决什么问题如果你的Agent经常答非所问、工具调用不准、或者同样的任务换个说法就不会做了那问题大概率不在模型本身而在技能层的设计。适合谁来读正在做Agent应用开发、想做一套可复用的Agent能力体系、或者被Prompt和工具调用折磨得够呛的工程师这篇应该能对你有用。1. 技能层在Agent架构里的定位与整体设计思路很多刚接触Agent的人会有一个误区以为把大模型的API接上再给它一堆工具函数它就能干活了。实际上不是这样。模型确实会用工具但它怎么选工具、怎么传参数、怎么处理工具的返回结果这中间每一个环节都可能出错。技能层就是在这个环节上做约束和增强的——它本质上是夹在模型和真实世界之间的一层“能力适配器”。1.1 为什么大模型需要独立于提示词之外的技能层先讲一个我踩过的坑。最早做Agent原型的时候我把所有的工具说明直接塞进System Prompt里一次塞了大概十几个函数。结果是什么呢模型确实能调用但经常选错工具或者在不需要调用工具的时候强行调用。最离谱的一次用户只是问了一句“现在几点了”模型居然调用了发邮件的工具——虽然最后参数里没有收件人但这个行为本身已经说明问题了。后来我把这个问题归因于两个层面第一工具的语义和用户的意图之间距离太远模型缺乏足够的中间层来做匹配第二工具数量一旦超过某个阈值Prompt里的信息密度就会下降模型会“看不清”该用哪个。技能层解决的就是这两件事。它在工具之上再做一层封装把工具按业务场景重新组织每个技能自带触发条件、调用约束、参数规范和结果处理逻辑。模型面对的不再是一个扁平的函数列表而是一组有语义边界的“能力块”。你可以把它理解为工具函数是零件技能是组装好的机器模型只需要按需选择机器而不是当场去搞懂每个零件该怎么用。1.2 技能注册表与技能模板让Agent的能力可编排我这边Agent技能管理的核心是一个技能注册表用JSON格式维护每个技能有固定的字段。上个月刚重构了一版具体结构长这样skill: name: translate_document version: 2.1.0 description: 翻译文档内容支持中英日韩四语互译 triggers: - 关键词: [翻译, 翻一下, 译成, translate] - 意图区间: [0.85, 1.0] params: target_lang: type: string enum: [zh, en, ja, ko] required: true document_text: type: string max_length: 5000 required: true executor: type: function_call endpoint: agent.translate timeout_ms: 5000 output_schema: translated_text: string fallback: - summarization_alias这套结构里最重要的是两个字段triggers和executor。triggers决定了模型什么时候该想起来用这个技能executor决定了实际执行的动作。我把触发条件分成两种信号的组合表面信号关键词命中和深层信号语义相似度。双信号的好处是既能做到“看到翻译两个字就触发”也能做到“用户说‘这段我看不懂帮我弄成英文的’时也能触发”。注册表本身是可以在运行时动态增删的这给了系统很大的灵活性。比如业务侧临时加了一个需求只要往注册表里注册新技能模型在下一次会话中就能感知到。不用改代码不用重新部署这也是我最终放弃把所有技能写死在代码里的原因。1.3 方案选型背后的关键权衡其实在设计技能层的初期团队讨论过两条路线一条是把技能逻辑写成Python类每个技能对应一个类另一条就是我现在用的声明式注册表方案。Python类方案的问题在于技能与代码强耦合每加一个技能都要发版而且模型侧无法直接看到技能的结构只能通过拼接后的描述来理解容易失真。声明式方案的优势在于技能的描述、参数、执行入口都是纯数据。这带来两个好处第一可以用统一的方法把它渲染成Prompt片段给模型看第二可以做一个简单的内部管理后台非开发人员也能配置技能这在业务侧推进时帮助很大。当然声明式的代价也很明显它要求技能被严格标准化复杂的业务逻辑很难塞进去。我的做法是把技能定义为“薄封装”——复杂的计算逻辑仍然放在背后的服务里技能本身只负责描述、路由和参数转换。作为边界控制器它不亲自干活但必须知道谁适合干什么活让模型做出靠谱的决定。2. 核心技能模块的拆解与实现要点前面说了总体的架构思路这一部分拆到技能模块内部看看一个技能从声明到真正跑起来中间有哪些关键细节。很多人实现的技能不好用往往就是卡在这些细节上。2.1 技能触发机制的实现关键词命中与语义混合路由技能的触发我采用了两级路由。第一级是关键词和规则引擎第二级是语义相似度模型。这样组合的原因很简单关键词快但死板语义灵活但慢且有误判风险。规则引擎部分我挂了两个工具库一个是正则表达式匹配处理“把XXX翻译成英文”这种带变量的表达另一个是实体识别专门抽取文件名、时间、产品名等关键实体。正则匹配的方法很简单——命中关键词就给出候选得分通过加权公式把实体抽取出的变量一并计算初步确定该给用户推荐哪个技能。语义路由部分用的是模型输出的分布特征。我们给模型输入用户原话和候选技能描述让模型输出每个技能的匹配分数取高于阈值的和前三名作为候选。这样下来触发准确率能做到87%左右。剩下那13%的误触发或漏触发再靠后续计划编排来弥补。实操中最需要注意的一点是这个两层触发的阈值不得调过松。我一开始设置阈值偏松导致大量相似意图被并发触发。后来把所有触发阈值统一收紧到0.75以上漏召回率只上升了3%但误触发下降了22%整体体验改观明显。2.2 技能参数校验与自动补全不能信任大模型的参数这是整个系统里最值得说的一环。等你跑熟了就会发现大模型在决定调用技能时经常“自己发挥”参数格式与定义不符。典型问题是缺少必填参数、参数类型不对、日期格式乱来。我的方案是加了一层参数校验管道流程如下第一步格式校验。用上一步提到的JSON Schema做的结构约束。字段缺失直接拦截。第二步类型转换。模型给的数字可能是字符串要给成number日期可能写“明天”要换算成具体日期。第三步默认值兜底。定义技能时每个参数都尽量给定一个默认值。比如翻译的目标语言用户说“把它翻了”没指定目标语言那就默认按环境变量里的主流语言走。第四步边界约束。超过max_length的文本自动截断或者走摘要技能预处理。这个管道本身不复杂但它把错误卡在模型外面而不是业务里。因为模型调用工具时一旦报错Agent就很容易陷入死循环或者放弃任务。所以宁可在这里多写几行校验也不要让错误扩散到下游。2.3 技能调用编排从单技能到多技能的组合逻辑单技能能做的事毕竟有限。生产环境里的Agent往往需要串联多个技能完成一个复杂的任务。比如用户的会议纪要整理场景就需要先调用会议记录获取技能再调用摘要技能再调用待办提取技能最后调用邮件发送技能。编排方面我目前的实现是一种基于计划模板的方法。每个复杂任务都预定义了一个技能调用模板模板里指定了技能的执行顺序、依赖关系、以及失败时的替代方案。模板并不是死的模型可以根据用户的具体请求做微调。但这个微调被限制在一个范围内不能乱来。举个例子会议纪要任务的模板大概是这样的{ task_type: meeting_minutes, skills: [ {name: get_meeting_records, inputs: {meeting_id: $user_input}}, {name: summarize_document, inputs: {doc: $output.get_meeting_records}}, {name: extract_todos, inputs: {summary: $output.summarize_document}}, {name: send_email, inputs: {content: $output.summarize_document, recipient: $user.specified}} ] }这个模板的好处是Agent不用每次从头想该先做什么、再做什么而是按照模板顺序执行每一步的输入都来自上一步的输出出错时也能清楚定位到是哪个技能出了问题。用大白话打个比方模板像一个做菜的菜谱Agent是厨师菜谱写好了先切菜再炒菜厨师不用每道菜都自己发明流程只负责控制火候和判断实际情况。2.4 上下文管理与技能内部状态避免状态串台技能执行过程中有一个经常被忽略的点是技能内部状态和主对话上下文必须隔离。早期的实现里技能运行过程产生的中间数据都是直接拼接在主对话历史里的结果导致模型经常把上一个任务的数据拿来当当前任务的输入。每月统计的会话中将近十分之一出现了状态串台导致的逻辑混乱这个比例在当时是没法接受的。我现在的做法是为每个技能维护独立的上下文存储。技能执行时只能看到自己的输入参数和外部数据不能读主干上下文。执行结束之后主对话拿到的只有输出结果做成摘要而不是原始中间数据。这样虽然增加了一些存储开销但换来的是任务之间的隔离性。关于输出做摘要这里也有一个细节不是所有技能的输出都值得完整保留。像是数据库查询返回了50行数据如果全部塞回上下文等下一轮对话时信息过载模型就会“忘记”之前用户的需求重心在哪里。所以我给每个技能配了一个summary_strategy字段可以选择保留全量、保留关键字段、或只保留统计信息。这样即使在长会话里Agent也不会跑着跑着把需求搞丢。3. 技能集构建的实操过程与核心环节实现上一部分讲的是单个技能内部的构成这一部分讲怎么从零开始构建一套完整的技能集用在真实业务里。我就以自己在上线过的企业智能客服数据分析模块为例完整走一遍操作过程。3.1 需求分析与技能拆解先列动作再写技能动手写技能之前先从业务需求里拆出动作这一步不能跳。以数据分析模块为例用户的高频需求是查数据、看趋势、做对比、生成图表、写解读。那么对应到技能我拆出如下query_sales_data查询指定时间段的销售数据time_series_trend计算趋势指标环比、同比、均值compare_segments按维度做数据对比generate_chart生成图表图片narrate_insight用自然语言描述数据背后的情况在拆解阶段还有个容易被忽视的点别让技能太细碎也别太粗。太细碎会导致模型需要做很多次调用才能完成任务浪费token也增加失败概率太粗则会让技能描述和参数列表都非常复杂模型更难做出正确的调用。我的标准是一个技能应该能在一到两次工具调用中完成一个用户可感知的原子动作。比如“生成图表”是一个原子动作但“画折线图并加标注”就不是——它需要拆成“选图类型”和“画图”两个技能。3.2 技能实现的代码示例与参数计算过程以time_series_trend这个技能为例它接收一个时间序列数据集及需要计算的指标输出计算结果。这里有一个典型的参数计算过程环比增长率的计算依赖于当前周期值和上一个周期值两者缺一不可。我在参数定义里直接通过Schema约束了每个数据点必须包含value和period字段避免模型传入空字段。这个技能的执行函数我写了一个简化版如下def time_series_trend(data: List[Dict], metrics: List[str]): # 按period排序确保时间顺序正确 sorted_data sorted(data, keylambda x: x[period]) results {} for metric in metrics: if metric mom: # 环比 values [d[value] for d in sorted_data] if len(values) 2: return {error: 至少需要两个周期数据才能计算环比} current values[-1] previous values[-2] mom_rate (current - previous) / previous if previous ! 0 else None results[mom] round(mom_rate * 100, 2) elif metric yoy: # 同比 # 同比计算需要去年同期这里简化处理 current_values [d[value] for d in sorted_data if d[period] current_year_start] last_year_values [d[value] for d in sorted_data if d[period] current_year_start] if not last_year_values: return {error: 缺少去年同期数据无法计算同比} current_sum sum(current_values) / len(current_values) last_year_sum sum(last_year_values) / len(last_year_values) yoy_rate (current_sum - last_year_sum) / last_year_sum if last_year_sum ! 0 else None results[yoy] round(yoy_rate * 100, 2) return {trend: results, latest_period: sorted_data[-1][period]}这里除了算数本身重要的是边界条件的处理。数据不足、除零、数据缺失这三个问题在实际业务里每天都能遇到。如果没有在技能内部拦截返回的是一个报错模型就会在对话里开始“编”数据那跟这个工具本身有关系不推模型。3.3 技能效果调优从72%到91%准确率的参数调整记录技能搭好之后不是直接用一定要先做离线测试。我从历史工单里抽了300条真实用户询问逐一标注了期望调用的技能和期望参数再用Agent跑一遍算准确率。第一轮跑完准确率只有72%。主要问题有三类第一类关于触发条件过于宽泛。比如用户说“帮我看看这个月的表现怎么样”被同时触发了query_sales_data和time_series_trend。解决方式是给触发描述加了约束条件“仅当用户明确提出数据指标或时间范围时才触发”把“看看表现”这种模糊诉求交给主对话澄清。第二类参数缺失。用户说“这几个月的数据对比一下”但没说明月份范围。原先技能直接卡在参数校验失败。后来我调整了校验策略如果用户没说时间范围就默认用最近三个月如果对比维度缺失系统自动识别用户之前提到的维度若没有就用默认维度。在不影响准确性的前提下把参数默认值补充完。第三类模型输出格式不稳定。由于Skill描述是文本形式模型偶尔会直接把技能名拼错或把参数名改掉。后来我在给模型看技能描述时明确加了“参数名必须严格使用以下名称不可缩写不可改写”的约束模型调用格式错误率降到了2%左右。三轮调整之后准确率从72%提到了91%已经能满足业务上线的门槛目前线上的各项统计也比较稳定。3.4 技能间的数据传递与依赖关系管理最后一个实操细节是定义技能之间的数据协议。我统一采用JSON格式每个技能的输出都有确定的“输出Schema”下一个技能依赖上游输出时只取对应JSON路径的值。这里有一个很实用的技巧用JSONPath做数据提取。比如上游技能输出的是{data: {goods: [{name: 电脑, sales: 35}, ...]}}下游技能需要的是“销量总和”我在中间加了一个数据转换层提取后聚合再传给下游。这个转换层是个纯计算组件不涉及模型完全可控。这样做的好处是下游技能无需知道上游的原始结构只依赖转换层给它的聚合结果。在依赖关系管理上我维护了一张技能依赖表每个技能声明自己依赖哪些数据字段由数据转换层统一提供能有效避免“下游技能把上游输出忘掉”的情况。4. 常见问题与排查技巧实录这一部分是从多个版本迭代里沉淀的踩坑记录分开讲方便直接对照。4.1 技能误触发与漏触发怎么办误触发是最常见的问题。症状是用户问AAgent调用了技能B或者一口气把A、B、C全调了。排查步骤是这样的先看技能描述里的触发条件是否过于泛化。比如某技能描述里写了“当用户询问数据相关问题时触发”这句话等于没说——因为几乎所有问题都跟某种数据沾边。正确的写法是明确指出“仅当用户给出具体的数据集名称、字段名称或时间范围时触发”给出明确、可检验的触发约束。另一个排查点是多个技能的触发条件是否重叠。如果两个技能都能处理“查数据”的需求模型就很容易纠结。我处理重叠的办法是给技能加优先级当多个技能得分都高于阈值时优先选择排序靠前的同时把得分次高的作为备选在计划里留着。漏触发往往发生在用户表达的意图比较含蓄时。比如用户说“这季度做了多少生意”如果你没有“销售额”这个关键词匹配触发不了技能。这时候就需要使用语义路由模型来计算用户意图与每一个技能的定义之间的相似度分数。把相似度阈值调整到0.7左右漏触发率会明显下降。4.2 技能调用失败后的恢复策略重试与降级技能执行失败不可避免网络超时、外部服务报错、数据为空每一类都会遇到。我建议从以下三层考虑第一层重试。单个技能调用超时重试一次。注意重试前要确认技能操作本身具备幂等性。比如“发邮件”这个技能重试就要小心重复发送会惹麻烦。建议在技能定义里加一个idempotent字段标记该技能是否可以安全重试。第二层降级。主技能失败后走fallback技能。比如generate_chart技能如果因为图片渲染服务挂了而失败就降级为输出表格数据给用户。我最初开发时对每个技能都挂了fallback后来发现有的技能没有适合的降级路径例如“删除数据”降级成什么都不做更好一点。第三层告知用户。当所有恢复路径都失败时大方告知“当前暂时无法完成这个操作”。与其让模型编造一个虚假的成功结果不如承认失败。从客户满意度看坦诚的失败说明比虚假成功印象更可靠得多。4.3 上下文长度爆炸与技能输出截断策略长会话里很容易碰到上下文爆炸。比如用户连续让Agent做了五次数据分析每次技能输出都保留全量数据不到20轮对话上下文就到了上限。之后模型的质量明显下滑甚至开始“失忆”。我的解决方案是为技能输出设置最大长度限制。超过2000字符的输出自动做摘要。摘要采用分层策略用户关心的是结论就保留结论用户关心的是明细就保留TOP-N明细。对于需要完整结果的场景比如导出数据技能直接提供文件下载链接让用户去查看而不塞进对话上下文。这个做法试了一个多月效果很明显。会话平均轮次从原来常被截断的15轮以内延长到了接近40轮而关键信息的召回率几乎没有下降。4.4 多技能并发与状态隔离的坑最后说一下并发场景。当Agent判断多个技能可以并行执行时比如同时查库存和查价格我在工程实现上用了线程池来并发跑。但这里很容易踩坑多个技能共享了同一个上下文对象写的时候互相覆盖导致结果张冠李戴。我的经验是并发执行时必须为每个技能隔离上下文线程各自持独立的变量副本。Python里用threading.local或者用状态机加任务ID做隔离都可以。我这边目前采用更直接的方式在技能执行前生成一个task_id所有中间状态都挂在task_id下执行结束统一回收。这样无论并发多少技能状态都不会串。4.5 常用问题速查表问题现象可能原因解决方案技能A总是被误调到技能B触发描述重叠描述过于宽泛明确触发条件边界添加优先级参数频繁校验失败模型不理解参数格式或参数描述不清增加参数示例简化参数命名技能输出被截断或遗漏上下文过长摘要策略丢失关键信息按用户关注点分层摘要保留关键明细重试导致重复操作技能操作不具备幂等性幂等性标记非幂等操作禁止无脑重试并发状态下数据串台多技能共享上下文按task_id隔离状态与上下文技能注册后不生效注册表缓存问题强制刷新技能缓存或检查版本号5. 一些个人体会如果让我总结做这个技能层最重要的一句话我会说技能设计是在给模型划定一个舒服的工作区而不是让模型做所有自由发挥。技能太宽模型会迷失技能太窄模型会被困住——找到那个让模型既自由又有边界的中间状态就是整个工程的核心。另外想单独提醒一点技能层的效果不是一次性能调完的。模型本身在升级业务需求在变化用户问法也在改变这就意味着技能库需要有一个常态化的评估与迭代机制。我在线上每周都会抽一批新的用户请求做回归测试每两周更新一次技能注册表。保持这个节奏整个系统才不会随着时间和数据积累逐渐“生锈”。一个意外有用的技巧放在最后给技能描述写示例比写规则更有效。与其写“当用户提到数据时触发”不如给一个具体的示例“用户回答‘销售数据上周环比是多少’时触发”。模型对具体示例的理解和泛化能力往往比抽象规则强得多。这是一件小事但对准确率的提升帮助比我预想的大。
