Agent技能设计实战：从Function Calling到生产级编排的完整链路

做Agent项目做了这么久我越来越确定一件事决定一个Agent上限的往往不是模型本身而是你给它装的那些技能是怎么设计的。模型再强技能层一团糟跑起来就是灾难现场。反过来技能层设计得干净、边界清晰、可观测哪怕模型弱一档整体效果也能拉得很稳。agent-skills这个话题说白了就是在讲Agent的手怎么长出来、怎么管好这双手。我在生产环境里先后折腾过十几个Agent项目从简单单轮工具调用到多Agent协作的业务系统都碰过踩过的坑攒了不少。这篇文章我会把Agent技能从设计、开发、编排到测试的完整链路讲透适合正在做Agent应用、被Function Calling和Tool Use搞到头大、或者准备从Demo往生产环境推的开发者参考。1. 为什么Agent项目跑偏问题大多出在技能这个抽象层上我接手过好几个团队做废了的Agent项目复盘时看代码、看Prompt、看模型选型表面问题五花八门模型回答不稳定、多轮对话逻辑混乱、业务方说Agent太蠢。但把所有表面问题剥开几乎每一项都指向同一个根子技能层设计缺失或者设计错了。1.1 技能层到底是什么先对齐一个定义。技能层Skill Layer是Agent与外部世界交互的能力抽象集合。一次具体的工具调用、一段可复用的业务操作流程、一个带状态的多步骤任务脚本都可以封装成一个技能。它的核心价值是把模型从每次都要思考怎么调用底层工具的细节里解放出来让它聚焦在高层的任务拆解和决策上。模型就像一个项目经理技能库就是它的可调配资源团队。项目经理不需要知道每个工程师怎么写代码只需要知道这个团队能交付什么、有什么约束。1.2 技能层不是工具层也不是工作流层业界讨论Agent架构时技能Skill、工具Tool、工作流Workflow这几个词经常混用但它们在分层逻辑上是完全不同的东西。层级核心属性本质职责典型例子工具层无状态、单一动作完成一次原子操作查天气API、发HTTP请求、读写文件技能层有语义、封装逻辑完成一项完整业务能力客户情绪分析技能、智能排班技能工作流层有序、可编排串联多个技能完成复杂任务售后工单全自动处理流程工具层回答的是能干什么技能层回答的是能怎么干成工作流层回答的是按什么顺序干。很多项目的问题就是把这三层混在一起做在技能层写裸API调用在工作流层写业务判断逻辑最后Agent的上下文里塞满了碎片化的工具定义模型决策质量急剧下降。1.3 为什么技能抽象度决定了Agent的可用性我曾经帮一个电商客服团队优化Agent他们的初版实现里直接给模型暴露了20多个细粒度API工具包括获取订单基础信息、获取订单物流记录、获取订单商品明细、判断订单是否可退等等。结果就是模型在决策时频繁选错工具甚至出现先调判断是否可退的接口、再调订单信息接口这种本末倒置的调用顺序。我们把这一组细粒度工具重构成一个高级技能订单售后可行性评估内部封装查询、校验、规则判断全流程暴露给模型后决策准确率直接提升了30个百分点以上。这就是技能抽象的威力减少模型的选择负担把专家经验沉淀进技能实现里让模型只需要做该不该用这个技能的判断。2. 我从十几个Agent项目里复盘出的技能设计三原则技能设计的坑踩多了慢慢能总结出几条硬性标准。这三条原则是我现在每个Agent项目启动前必过的评审项也是我判断一个技能设计得好不好的快速标尺。2.1 把技能当API设计而不是当代码设计这是最重要的一条。技能最终会被模型以函数调用的方式触发所以它本质上是一个给非人调用者使用的API。这意味着输入参数必须有类型约束、范围约束、必填可选标注模型才能正确传参输出必须有稳定的结构不能今天返回JSON明天返回纯文本错误必须是可枚举、可处理的模型才能根据错误信息调整策略命名必须语义清晰模型才能从名字理解技能用途我之前见过一个团队给技能命名用的是内部开发代号比如skill_127_query模型根本不知道这个技能是干嘛的。改成query_order_status_v2、refund_apply这种自解释名字后技能命中率明显改善。2.2 每个技能要有明确的能力契约所谓能力契约就是技能的描述文件里写清楚三件事这个技能负责什么、不负责什么、什么条件下才能调用。一门技能描述写得好不好直接影响模型判断的准确性。我在实践中发现好的技能描述应该具备面向模型的表述方式而不是面向人类的说明书{ name: analyze_customer_sentiment, description: 对用户输入的文本进行情感倾向分析返回正面、负面或中性判断及置信度。当用户表达不满、投诉、抱怨情绪或需要判断用户态度时使用不适用于客观事实查询场景。若输入为空或超过2000字请先预处理后再调用。, parameters: { type: object, properties: { text: { type: string, description: 需要分析的用户原文不超过2000字 }, language: { type: string, enum: [zh, en], description: 输入文本的语言代码默认zh } }, required: [text] } }重点看description的写法先说明能力强项再给出触发条件用户表达不满时使用再明确边界不适用于客观事实查询最后给出出入参的前置约束。这比单纯写情感分析接口要有效得多。2.3 可观测性是技能的第一公民生产环境的Agent技能调用失败、参数传错、返回结构异常都是家常便饭。如果技能层没有可观测性设计出问题后排查链路会非常痛苦。我给自己定的硬性要求是每个技能必须输出结构化的运行日志包含调用方决策上下文、输入参数快照、执行耗时、返回结果摘要、错误码五类信息。这些日志不仅用于排查问题更是后续评测Agent效果的数据基础。没有可观测性的技能等于把失败原因全部藏进了黑盒里。3. 技能开发实战从模糊需求到可上线技能的落地链路确定原则之后具体怎么把一个业务需求变成Agent技能我一般遵循需求拆解 → 接口定义 → 逻辑实现 → 注册发布四步链路。3.1 需求拆解一段模糊诉求怎么切分成技能边界需求拆解阶段的目标是明确这个技能到底封装什么、不封装什么。我会用三个问题来引导这个操作能不能被一句话说清楚它完成什么业务目标它内部是否需要依赖其他技能或外部系统它是不是一个会被频繁复用的能力还是一锤子买卖举个例子智能招聘助手项目里业务方最初提的需求是帮HR筛选简历。这个需求太宽直接做一个技能会导致技能内部逻辑无比臃肿。我们把它拆成了三个技能简历解析标准化、岗位匹配评分、面试问题生成。每个技能职责单一组合起来又能完成完整业务。3.2 接口定义一个合格的技能Schema长什么样接口定义是整个技能开发中最需要较真的环节。除了上面提到的能力契约还有几个容易被忽略的点参数默认值要给合理预设减少模型传参压力枚举类型要覆盖所有业务分支避免模型想表达的值无处安放返回结构里尽量包含模型下一步决策所需字段我自己常用的返回结构模板长这样{ success: true, code: OK, data: { main_result: 技能核心输出, supporting_info: 辅助决策信息, next_step_hint: 给模型的后续操作建议 }, execution_ms: 1234 }这个结构里最有讲究的是next_step_hint它相当于技能在告诉模型我这边处理完了你可以考虑下一步做X或Y。这种设计能明显减少模型在跨技能切换时的犹豫和误判。3.3 逻辑实现参数校验、幂等性与超时处理是底线技能内部实现用什么语言、什么框架反而不是最重要的真正决定线上质量的是三个工程底线。参数校验必须在入口做死。模型的传参不可能百分之百规范前端校验、类型转换、默认值兜底做到位才能避免下游系统收到垃圾数据。我见过一个技能因为没做参数白名单校验模型把北京的城市代码传成了beijing_city结果整个查询流程挂了。幂等性不能有侥幸心理。Agent在超时后很可能会自动重试如果技能内部操作不是幂等的比如重复创建订单、重复扣款后果非常严重。我的建议是凡是涉及写操作的技能必须实现幂等控制用业务请求ID做去重判断。超时时间要按技能的真实执行时间反推。很多团队把超时统一设成3秒结果技能实际执行要8秒模型收到的全是超时错误再聪明的模型也只能反复重试。我一般会根据技能的历史P95执行时间设定基数为1.5倍到2倍。3.4 注册发布让模型正确“认识”你的技能技能写好了需要在Agent的技能注册中心登记上线。这里我要重点讲一下注册顺序和技能数量的关系。模型能同时看见的技能数量是有限的。OpenAI等主流模型对上下文中工具定义的数量和复杂度都比较敏感工具定义太多会导致性能下降、决策质量滑坡。实测下来大部分场景下把同时暴露给模型的技能控制在10个以内效果最稳。超过这个数就要考虑分组、路由或者分层技能架构了。技能的注册描述也是可以迭代的。上线后我发现模型对某个技能的理解有偏差不要急着改代码先看是不是描述写得有歧义调整description里触发条件和边界的表述往往比改逻辑代码更有效。4. 技能编排单技能是砖组合起来才是墙单个技能设计得再好也只是解决了一件事怎么做的问题。真实的业务场景几乎都是多步的需要多个技能配合。技能编排就成了决定Agent复杂任务处理能力的核心。4.1 三种编排模式顺序、条件与并行我的项目里最常用的编排方式有三种不同场景选不同模式而不是一个ReAct循环走天下顺序编排A技能输出直接作为B技能输入形成流水线。典型场景是简历解析 → 岗位匹配 → 生成面试问题条件编排根据前面技能的执行结果或用户意图动态选择后续走哪个分支。典型场景是先识别用户情绪正面走常规应答负面走安抚补偿流程并行编排多个互相独立的技能同时执行最后汇总结果。典型场景是同时查库存、查物流、查优惠策略汇总输出购物建议实现这些编排逻辑时我强烈建议用状态机或DAG图来管理而不是在自然语言Prompt里硬写你做完A再做B如果失败了就做C。Prompt里的流程约束再清晰模型也有理解跑偏的时候。流程的骨架逻辑应该放在代码层控制模型只负责在分支点做决策。4.2 技能链与子技能复用避免又臭又长的“巨无霸技能”做技能编排时最容易犯的错误是图省事把一条完整业务链路写成一个超大技能。这种巨无霸技能内部塞了几十步逻辑参数几十个既难调试又难复用模型也容易在长链路中途出错。我现在的做法是技能分层复用底层是原子技能单次查询、单次计算上层是组合技能内部编排底层技能完成一个业务目标。组合技能本身也可以作为更上层技能的原子单元被再次编排。这样整个技能体系是树状的任意层次都可以独立测试也可以任意组合。4.3 编排层最容易翻车的两个地方第一个是上下文传递。技能A的输出要传给技能B很多人简单粗暴地把全部输出塞进上下文结果无关字段污染了后续判断。正确的做法是在编排代码里做字段映射只抽取B需要的那几个结构字段传下去。第二个是循环失控。条件编排里如果设置了不满足条件就重试一旦缺少跳出机制Agent就会陷入死循环白烧Token还卡死任务。我给自己定的规范是循环必须有最大尝试次数上限每轮循环之间必须有意图变化检测如果Agent连续N轮输出相似判断但始终无法完成直接终止并转人工。5. 技能测试与调优上线前最有价值的投入测试是技能质量的分水岭。很多Agent项目Demo里跑得好一上生产就翻车核心原因就是测试阶段只测了理想路径没有测边界和异常。5.1 单技能评测别只看“成功调用率”我给每个技能单独建立评测集时至少覆盖四类用例评测维度考察内容典型测试用例正常路径输入规范时能否正确执行标准参数调用期望正确返回边界输入参数临界值、极端值的处理空字符串、超长文本、未知枚举值异常兜底内部系统报错时的表现下游接口超时、返回异常格式语义鲁棒性模型传参不精确时的适应力同义但非标准表述的参数值评测标准也不完全是调用成功我认为更合理的是结果可用性技能成功返回了但返回的结果是不是业务上真实可用的比如一个情感分析技能调用成功但置信度极低模型照着这个结果做决策一样是事故。5.2 回归测试与“技能漂移”技能上线后会不断迭代每次改代码、改描述、改参数结构都可能影响模型对技能的判断和调用行为。这种因为技能定义变化导致模型行为变化的现象我叫它技能漂移。防漂移的唯一有效手段是建立回归测试机制。我团队现在的做法是每个技能维护一个固定的评测数据集每次上线新版本自动跑全量评测对比调用成功率、结果准确率、平均延迟三个指标任何一个指标下降超过5%就阻止上线强制排查原因。5.3 调优顺序先描述再逻辑后代码当模型对某个技能的调用表现不佳时我强烈建议按描述 → 参数结构 → 内部逻辑 → 代码这个顺序排查不要一上来就改代码。先调整description里的触发条件、边界说明看模型能否正确理解技能适用范围再检查参数结构是不是让模型难以传参比如把自由文本参数改成枚举类型然后检查技能内部逻辑是否有隐藏异常最后才考虑是不是代码实现有Bug。这个顺序背后有逻辑Agent调用技能的大部分失败根源发生在模型决策和理解层面而不是执行层面。顺着这个顺序排查能节省大量时间和精力。6. 几个必须单独拎出来说的高频坑最后这部分是复盘时记录的典型坑位每一个都造成过线上事故希望你别再踩一遍。6.1 五个高频坑位坑一技能返回结构不稳定。同一个技能有时候返回{result: ok}有时候返回ok字符串模型解析逻辑直接崩。定好规范后所有技能必须返回统一JSON结构格式问题不能妥协。坑二忽略参数枚举值的语义覆盖。技能参数枚举只有是和否但业务里还有待定未知模型只能硬选一个产生错误决策。枚举设计时要留好业务分支的出口。坑三技能的description是给人看的而不是给模型看的。写了该接口基于深度学习算法模型看了只觉得抽象写清楚当用户输入包含订单号且询问物流时使用模型才会在正确的时候调用。坑四没有技能版本概念。技能迭代后直接覆盖线上配置老任务在恢复重放时用了新版本技能行为对不上。现在每个技能都带版本号运行时锁定版本避免不一致问题。坑五评测只看技能调没调不看技能用的对不对。调用了正确技能但在不合适的场景下用比不调用更危险。评测指标里一定要同时看调用率和调用正确率。6.2 我现在总结出的固定做法踩过这些坑之后我现在的Agent项目都会定一套固定的技能工程规范每个技能从需求拆解到上线走统一流程技能描述必须经过模型视角审查返回结构全项目统一每个技能带版本和owner上线前过评测回归集上线后有调用可观测看板。这套规范不是某个框架内置的是靠工程纪律一条条落地的。它带来的收益是肉眼可见的Agent行为的确定性大幅提升线上问题定位时间从天级降到小时级。对我来说agent-skills不是一个新名词而是这些实战经验沉淀出来的总称。技能既是Agent能力的载体也是工程化约束发挥作用的抓手。如果你正在做Agent应用我建议从项目第一天就把技能层当一等公民来对待而不是等Demo跑不动了再来补课。