从标题“agent-skills”说起这其实不是一个具体工具而是一整套围绕 AI Agent 展开的技能设计与落地思路。我下面要分享的内容不是那种放之四海皆准的概念宣讲而是我自己在真实项目里把 Agent 从“只会聊天”推到“能干活”时踩过的坑、总结出的方法以及一套可以直接复制走的技能体系框架。不管你是刚开始接触 Agent 开发还是已经在生产环境里跑了几个智能体但总觉得效果不稳定这篇文章应该都值得你花十分钟读完。1. 技能体系设计思路先搞清楚 Agent 为什么“又蠢又笨”1.1 绝大多数 Agent 项目失败不是模型问题是技能缺失先说一个很多人不愿意面对的事实同一个大模型在不同人的手里跑出来的效果天差地别。差别不在模型的聪明程度而在你有没有给它配齐“能干活的手脚”——也就是技能skills。我见过太多团队拿着 GPT-4 级别的模型做客服机器人结果上线三天就被用户骂“人工智障”。问题出在哪里模型本身不笨但它缺了三个东西缺少调用外部工具的能力、缺少记忆上下文的方法、缺少按流程执行业务规则的机制。这三样合在一起就是 Agent 的技能层。没有技能层的 Agent本质上就是个没有手、没有脚、只有一张嘴的“键盘侠”嘴上说得头头是道真让它订个机票、查个库存、生成一份合同它就抓瞎了。我刚接手的一个项目特别典型客户要求做一个能自动处理售后工单的 Agent。第一版方案很简单粗暴——把工单数据全部塞进 Prompt让模型直接输出处理结果。结果可想而知上下文爆炸、模型答非所问、关键字段提取错误。后来我重新梳理了技能体系给 Agent 配上“工单查询工具、客户历史行为检索工具、赔偿计算脚本、风险标记规则”四组技能效果立刻就不一样了。这个案例我想说明的核心观点是Agent 的上限由模型决定但下限由技能体系兜底。1.2 技能设计的三层模型动作、知识、流程我做 Agent 技能体系设计通常把技能分成三个层次这也是我在几个项目里反复验证过的框架第一层动作技能Action Skills。这一层是 Agent 与外部世界交互的接口包括调用 API、操作数据库、发送邮件、读写文件等具体动作。这一层的关键设计原则是“动作粒度要小”。什么叫粒度小比如“根据订单ID查询物流信息”是一个动作“处理整个售后流程”就不是一个动作而是一组动作的组合。我在最开始的架构里经常下意识地把动作设计得太大比如一个“处理退款”的 function 内部写了几百行逻辑——结果模型根本不知道怎么灵活使用它因为调用门槛太高了。第二层知识技能Knowledge Skills。这一层解决的是“模型不知道但业务需要”的问题。知识技能包括检索增强生成RAG所需的知识库、业务规则库、数据字典等。我的经验是把业务规则显式地写成机器可读的规则条目而不是依赖模型“临场发挥”。比如“VIP 客户退货免运费”“生鲜商品不支持七天无理由”这类规则如果你不抽出来做成规则库模型大概率会在某些奇怪的时候突然“忘了”这条规则。第三层流程技能Process Skills。流程层是把多个动作按照业务逻辑串起来形成标准作业程序。Agent 在这一层体现出真正的“智能”——它知道什么场景下调用什么动作、按什么顺序执行、什么情况下需要向用户确认。流程技能通常用工作流引擎或者状态机实现而不是靠模型自由发挥。理由很简单核心业务路径必须可控否则模型一旦自由发挥就是灾难现场。这套三层模型是我设计 Agent 技能的骨架后面所有细节都是在这个框架里展开的。你先记住这个模型下面我来拆解每一层里具体的实现要点。2. 动作技能 vs 知识技能两套完全不同的实现路径2.1 动作技能让模型学会“使唤工具”动作技能的本质就是让大模型理解“有哪些工具可以用每个工具的输入输出是什么什么情况下应该用哪个工具”。目前主流的实现方式有两种Function Calling 和 MCPModel Context Protocol协议。Function Calling 是最直接的路径。OpenAI、Claude、通义千问这些主流模型都原生支持这个能力。实现方式就是把工具定义成 JSON Schema 格式随请求一起发给模型模型在需要调用工具时会返回一个结构化的调用请求你解析这个请求、执行对应函数、再把结果回传给模型。这套机制现在很成熟了。MCP 则是2024年底到2025年非常火的一套协议它把“工具定义”“工具调用”“资源访问”标准化让 Agent 可以像 USB 设备即插即用一样接入各种工具服务。我个人认为MCP 的价值不在于技术多牛而在于它建立了统一的集成标准——以前接一个工具要写一套适配代码现在只要服务方实现了 MCP 协议所有支持 MCP 的 Agent 都能直接用。从我自己的项目实践来看有一个特别重要但容易被忽略的设计细节工具的 description描述和参数定义决定了模型能不能正确调用工具。同样的一个函数如果描述写的是“get_order_info(order_id: str)”模型在需要查订单时大概率会用如果描述写的是“数据查询接口参数详见文档”模型很可能就蒙了。我给工具做 API 定义时遵循一个原则描述要写“什么时候用 这个工具有什么作用 参数的单位/格式/取值范围”而不是只写“功能说明”。这是我在动作层最想说的一点你写工具定义时的仔细程度直接决定模型调用工具的成功率。工具定义写得越“啰嗦”模型越靠谱。后面我会在第三节用一个实际的工具定义案例来说明。2.2 知识技能你以为的 RAG 其实只是知识技能的十分之一知识技能这块很多人的第一反应就是接向量数据库、做 RAG。但我在实际项目里的体会是RAG 只是知识技能里的“检索型知识”部分完整知识技能还应该包含规则型和参数型知识。规则型知识的典型例子业务政策、审核标准、折扣规则。这类知识不适合用向量检索去找因为它们是强逻辑、弱语义的。比如“退款金额实付金额-已使用优惠券分摊金额”这种规则用自然语言检索去匹配很容易出偏差。我的做法是把这类规则独立出来做成结构化规则库由 Agent 在需要决策时主动查询或者通过专门的“规则代理”模块来执行。参数型知识则更底层包括业务流程中涉及的各类配置参数、阈值、常量。比如“超时时间30秒”“风控拦截阈值单笔订单金额超过5000元需人工审核”。这些参数既不适合塞进 Prompt也不适合放到向量库里最好的方式是通过配置中心管理Agent 在运行时按需读取。关于知识技能我还有一个重要的工程建议不要只做“检索”要做“检索 路由 精排”。检索只是拿到了候选内容关键是你怎么让 Agent 在多个候选里挑出正确的回答依据。我常用的链路是问题→意图识别→知识库路由决定去哪个知识域查→向量检索/规则匹配→精排用 Rerank 模型或规则筛选→答案生成。整个链路下来知识输出的准确率和稳定性会明显上一个台阶。2.3 两类技能的边界什么时候写工具什么时候塞知识这是一个我经常被问到的问题。一个业务能力到底是做成动作技能让 Agent 调用还是做成知识技能让 Agent 查阅我的判断标准有三条第一看是否需要修改外部系统的状态。需要改订单状态、写数据库、发消息、调第三方接口的一律做成动作技能。知识技能只负责“读”和“查”不负责“改”。第二看执行结果是否可验证。如果动作执行以后有明确的结果和副作用比如扣款成功、邮件已发送必须做成可观测的动作技能方便审计和回滚。如果只是一段文字说明、一个数字、一个解释塞知识就行。第三看实时性和准确性要求。如果数据实时变化比如库存、价格那必须做成工具实时查询。如果是相对稳定的内容比如产品说明、操作手册用知识库就够了。这三条标准我每次做技能拆解时都会过一遍基本能避免大部分“这个功能到底放哪里”的纠结。3. 实操过程一个完整的技能注册与执行框架3.1 结构化定义技能清单的模板无论你用什么协议实现 Agent 技能第一步永远是把技能清单结构化。我下面的模板来自我实际项目中的简化版本你可以直接抄{ skill_id: order_query_001, skill_name: 查询订单物流信息, skill_type: action, description: 当用户询问订单物流、配送进度、快递单号时使用。支持通过订单ID或手机号查询。, parameters: { order_id: { type: string, required: true, description: 订单编号格式为英文字母O开头加10位数字如O20250115001 }, query_type: { type: string, enum: [basic, trace], required: false, description: basic返回订单基础信息trace返回物流轨迹节点默认basic } }, execution: { endpoint: http://internal-api/orders/{order_id}, method: GET, timeout_ms: 5000 }, permission: read_only, rate_limit: 100/min }这份 JSON 是技能体系的最小单元。你可以对照着审视一下description 是不是说清楚了什么时候用parameters 是不是定义了格式、取值、默认值execution 是不是明确了对系统的影响面如果这些问题都能回答这个技能定义就是合格的。我在实际落地中还会为每个技能增加两项元信息semantic_requirements触发该技能的典型用户表达示例和failure_handling调用失败时的兜底动作。前者用来在做意图识别时做语义匹配后者用来让 Agent 在技能失败时知道该怎么办。这两个字段看似不起眼但在生产环境里价值极大——没有 failure_handlingAgent 在技能失败时就会瞎编结果这是我最不能容忍的行为。3.2 执行引擎代码级的最小实现有了技能定义还需要一个执行引擎来负责“调度模型请求、解析工具调用、执行函数、返回结果”。下面我给一个极简的 Python 示例演示核心调度逻辑import json import requests class SkillExecutor: def __init__(self, skills): # skills 是从注册中心加载的技能定义列表 self.skills {skill[skill_id]: skill for skill in skills} def build_tools_schema(self): 把技能定义转换成模型要求的 tool schema 格式 tools [] for skill in self.skills.values(): tool { type: function, function: { name: skill[skill_id], description: skill[description], parameters: { type: object, properties: skill[parameters], } } } # 处理 required 字段 required [k for k, v in skill[parameters].items() if v.get(required)] if required: tool[function][parameters][required] required tools.append(tool) return tools def run(self, user_query): # 第一步调用模型附带工具定义 response llm_call( messages[{role: user, content: user_query}], toolsself.build_tools_schema() ) # 第二步检查模型是否请求调用工具 if response.get(tool_calls): tool_call response[tool_calls][0] skill_id tool_call[function][name] args json.loads(tool_call[function][arguments]) # 第三步校验参数执行技能 skill self.skills[skill_id] result self.execute_skill(skill, args) # 第四步把执行结果回传给模型生成最终回答 final_response llm_call( messages[ {role: user, content: user_query}, {role: tool, name: skill_id, content: json.dumps(result)} ] ) return final_response else: # 模型没有请求调用工具直接返回模型的回答 return response[content]这个代码核心点有四步构建 schema → 模型决策 → 参数校验执行 → 结果回传。看起来简单但实际生产环境中每一步都有不少坑。比如模型返回的arguments偶尔会不是合法 JSON你必须做容错解析再比如工具真正执行可能耗时较长模型在等待结果时可能会超时你需要把超时配置调到合适值。还有一点工具的调用循环不止一轮。一个 Agent 任务可能需要连续调用多个工具比如先查订单、再算赔偿、再发起退款。这时候需要把“模型请求→工具执行→结果回传”变成一个循环直到模型不再请求工具为止。我建议给这个循环设置一个最大迭代次数通常 5~8 次防止模型陷入死循环。3.3 技能的生命周期管理注册、版本、下线技能不是写完就一劳永逸的它需要像软件一样做生命周期管理。我在团队里推荐的技能管理流程是开发 → 注册 → 测试 → 灰度 → 上线 → 监控 → 下线。注册技能开发完成后把定义推送到技能注册中心Consul 或者一个 MySQL 表都可以Agent 启动时从注册中心拉取技能清单。版本每次修改技能定义必须生成新版本号。Agent 调用时带上版本号方便追踪“这个结果是用哪个版本的技能算出来的”。一旦新版本出问题可以秒级回滚。灰度不要一步到位全量切流量。我习惯的做法是新技能先只对 5% 的会话生效观察准确率和调用成功率达标后再逐步放量。监控重点监控三个指标——调用成功率、参数校验失败率、Agent 在调用该技能后的任务完成率。前两个指标在工具调用层就能统计第三个指标需要在下游业务结果里追踪最容易被忽视但恰恰最重要。我见过太多团队技能上线之后跑了两周才发现“Agent 一直在调用一个已经失效的接口”原因就是没有监控链路里加一层调用告警。记住没有监控的技能等于埋了一颗不知道什么时候爆炸的雷。4. 常见问题与排查技巧那些让我头疼整晚的坑4.1 模型不调用工具描述不清晰是头号原因遇到最多的疑难杂症就是明明技能已经定义好了模型在面对该调用工具的场景时却绕过去直接回复“我无法查询”。排查思路有三步第一步检查技能描述是否面向“触发场景”写清楚了。如果你的描述只写了“查询订单接口”没写“当用户询问物流信息、配送进度、快递何时到达时使用”模型就不知道这个工具是给这个场景用的。这个是最频发的低级错误。第二步检查当前模型版本是否支持 Function Calling。注意不是所有模型版本都能稳定地输出结构化的工具调用参数。有些开源模型的“智能体能力”很弱经常在工具调用格式上出错。我的做法是先跑一个最小测试用例只定义 1 个工具看看模型能不能稳定触发。如果最小的都触发不了问题一定在模型侧——换模型或者换 API 网关。第三步检查模型参数里 temperature温度是不是太高了。温度太高会让模型变得“自由散漫”不遵守指令。我在做工具调用的请求里一般把 temperature 压在 0 到 0.3 之间。这个参数看着不起眼但影响非常大——超过 0.7 时工具调用的稳定性显著下降。4.2 工具调用返回结果太长一次回传就撑爆上下文这类问题发生频率极高——Agent 调用一个查询工具工具返回了 580 条数据直接塞回给模型。轻则上下文膨胀、回答质量下降重则直接触发上下文长度限制。解决方案不是让模型自己“不要返回太多”而是在工具层做输出裁剪和总结。具体有三板斧第一板斧分页。如果数据量可能很大工具接口必须支持分页参数Agent 默认只取第一页的信息量比如前 50 条。第二板斧字段裁剪。工具返回给模型之前把不需要的字段剥离掉。比如一个订单对象有 40 个字段模型其实只需要其中的 6 个订单号、商品名、金额、状态、物流单号、更新时间那就在工具出口做一个精简 DTO 映射只回传这些字段。第三板斧聚合上报。如果是要统计数据不要回传明细回传聚合结果。“返回 580 条售后记录”不如“返回‘累计 580 条其中未处理 32 条最近一条未处理记录如下’”。做过一次上下文爆掉的线上故障后我在所有工具的执行层都加了一个“回传内容上限”的控制逻辑超过指定长度的输出自动做摘要。这个逻辑不是可选项是必需项否则你的 Agent 线上运行久了什么奇怪的问题都会冒出来。4.3 技能之间的“抢活”意图路由和冲突解决技能多了以后会出现一个新的坑用户的一个问题可能同时触发多个技能。比如“帮我查一下订单并对异常订单发起退款”——这涉及订单查询技能和退款技能到底先调哪个我的经验是不要在模型层面期望它天然处理好这个顺序而是用意图路由层做技能编排。具体做法是给每个技能打上“前置技能”标签。例如退款技能的前置技能是订单查询技能。在模型请求前用一个轻量的意图分类模型不需要大模型一个 Bert 小模型就够识别用户意图映射到技能调用路径。用工作流引擎编排技能顺序模型只负责处理技能执行过程中部分需要语义理解的环节比如判断退款理由是否成立。这套做法把“不可控的模型自由发挥”变成了“可控的流程编排局部的智能判断”在生产环境里稳定性提升非常明显。我见过很多 Agent 项目死在“让模型自己决定工具调用顺序”这个设计上——偶尔跑通一次看起来惊艳但稳定性一塌糊涂。把核心路径编排放在工作流层是让 Agent 从“demo 级”走向“生产级”的分水岭。4.4 技能执行的安全边界防止 Agent 越权操作最后说一个不少人都忽略的问题技能层是权限控制的最前线。你给 Agent 的技能清单本质上就是它拥有的全部权限。一个会调用“查库存”接口的 Agent如果没有权限控制用户可能诱导它去查“全部库存数据”或者更危险的是诱导它调用“改库存”的功能。我的做法是给每个技能做三档安全级别级别权限特征适用场景read_only只读查询无状态变更查询类技能user_confirmed执行前须用户明确确认下单、退款、发送消息等admin_approval执行前须管理员审批批量操作、高风险动作、现金类在工具定义里显式声明permission字段Agent 在用户提出请求时如果用户指令超出了当前技能的权限范围必须拒绝执行或者发起确认流程。这条规则看似简单但其实过了这一层再往上的安全都不可靠了。另外还要做一层“参数白名单”校验。比如技能定义只允许查询order_id参数的订单如果模型解析出来的参数里有恶意注入的特征比如order_id*就要在参数校验层直接拦截。我习惯在技能执行前加一个简单的规则校验器对所有参数的格式、范围、枚举值做强制校验——别依赖模型自己“懂规矩”要在执行层硬约束。5. 从单体技能到技能市场规模化复制之路5.1 技能的抽象与泛化从项目内复用到跨项目复用当你在一个项目里跑通了完整的技能体系自然会想到一个问题这些技能能不能在别的项目里直接用答案是一部分可以但直接复用的前提是做好抽象。我举一个具体例子“查订单物流”这个技能在电商项目里和物流追踪项目里虽然数据源不同但触发逻辑和参数结构几乎一样。如果你一开始就把“订单查询”实现成“查 A 平台订单”复用性就没了如果你把它实现成“根据订单号和来源平台查询物流轨迹”把来源平台作为参数这个技能就能同时服务多个项目。我的经验是在技能设计阶段就要考虑泛化程度。具体做法写技能描述时不要绑定具体业务名词先把“用户意图场景”抽象出来。比如从“查询京东物流单号”抽象为“查询平台物流单号”再抽象为“查询物流轨迹信息”。抽象层级越高未来复用的可能性越大但也不要过度抽象——抽成一个万能的“数据获取”就没有任何实用价值了。5.2 内部技能市场把 Agent 技能当成产品来运营当团队里有几十个技能、多个项目都在用的时候管理方式就需要升级了。我强烈建议把技能体系做成内部技能市场形式上可以是一个带搜索功能的技能目录页面或者一个技能包的 Git 仓库。技能市场要提供以下能力搜索和发现项目开发者能搜到“有没有现成的退款技能”“有没有发票识别技能”。评分和试用每个技能有调用次数、成功率、平均耗时、最近是否异常的数据看板。提交和评审新技能的提交要经过评审至少要有一个人 review 过技能定义的正确性和安全性。依赖管理技能之间有依赖关系时要有清晰的记录。技能市场做到这个程度Agent 开发就不需要每个项目从零造轮子了。新项目启动时直接逛一遍内部技能市场基本能覆盖 70% 的能力需求剩下 30% 才是真正需要新写的技能。这个比例带来的效率提升是非常惊人的。5.3 一个“技能集市”雏形的数据结构给个小参考一个技能目录页面的数据结构大致是这样的我简化了{ category: order_management, skills: [ { skill_id: order_query_001, name: 订单详情查询, version: 1.4.0, owner: 交易中台组, usage_count: 128430, success_rate: 0.986, avg_latency_ms: 845, updated_at: 2025-06-18, tags: [订单, 物流, 查询] } ] }我比较看重success_rate和avg_latency_ms这两个指标因为技能的健康状态直接影响所有依赖它的 Agent 的体验。只要某个技能的成功率跌破 95%我就要求负责人立刻排查宁可临时下线也不能带病运行——一个带病的技能会污染所有依赖它的 Agent 任务而且扩大的速度是乘法级别的。6. 生产环境里的避坑心得那些文档里永远不会写的事6.1 超时和重试设计技能服务不稳定Agent 率先崩溃生产环境里你会发现最容易让 Agent 崩溃的不是模型而是它身后的技能服务。任何外部服务都会有超时、抖动、限流而 Agent 恰恰对不稳定因素零容忍——一旦技能调用超时Agent 可能会重复调用、并发执行甚至因为等待而挂起整个会话。我的设计原则是技能调用必须做超时熔断默认超时 3 秒超过就立刻返回错误结果给模型让模型走故障处理逻辑而不是无限等待。重试策略必须显式设计哪些技能支持重试支持几次重试间隔多少我的默认策略是对只读技能做 1 次快速重试间隔 500 毫秒对写操作不做自动重试——因为写操作重试可能造成重复执行重复退款、重复发券。这一点务必写死在执行引擎里别指望 Agent 能自己判断。另外并发数限制一定要做。假设 500 个用户同时让 Agent 调技能如果你的技能服务撑不住Agent 拿到的全是超时错误用户体验直接崩盘。我在技能执行器上做了一个简单的信号量并发限制超过阈值就返回“系统繁忙请稍后再试”——这比让用户一直转圈好得多。6.2 日志与全链路追踪没有日志你修不了任何问题Agent 项目的排查难度比传统后端高出一个量级。因为它的每个任务可能经历“用户输入 → 意图识别 → 工具编排 → 多次模型调用 → 多次工具执行”任何一个环节出错都可能导致最终结果不对。没有完整的链路日志你根本无法定位问题出在哪一环。所以我从一开始就要求所有 Agent 请求打印结构化日志每个请求生成唯一的 trace_id记录以下信息用户完整的输入内容意图识别结果和置信度模型每次返回的内容和 tool_calls每个技能的执行参数、耗时、返回码和结果摘要最终回复内容这套日志在平时看着麻烦但在问题排查时救过我好几次。有一次线上 Agent 反复给用户推荐错误商品排查了整整两天最后靠日志发现问题出在一个技能参数解析时把sku_id和spu_id混淆了——这种问题靠肉眼盯屏幕永远找不到只能靠链路日志的数据回溯。6.3 兜底方案当 Agent 彻底不会的时候给用户一条人肉通道无论技能体系做得多完善总会有模型和技能都处理不了的长尾场景。我的坚持是这种场景必须有兜底方案Agent 不能傻乎乎地硬编一个回答给用户。兜底方案通常是两种一个是转人工客服把当前对话的完整上下文一并转交减少用户重复描述的成本另一个是明确告诉用户“这个问题还需要进一步确认我会稍后回复您”同时触发异步任务去处理。我在做一个售后机器人时刚开始的兜底分支是“回复无法处理请拨打客服电话”结果用户的体验吐槽如潮。后来改成“转人工时自动附带订单号、查询历史、用户诉求摘要”满意度立刻提升了 35% 以上。Agent 最不应该做的事情就是假装自己能处理而实际上处理不了。7. 结尾之外的一些话技能体系是一步一步长出来的最后说说我个人的一点体会。很多团队一开始就想做一个“全知全能”的超级 Agent什么技能都想塞进去结果要么是上下文爆炸要么是调用链路复杂到三天两头出故障。我实践下来更靠谱的路径是从一个最小可用闭环开始比如只做“查订单 物流 退款”三个技能把这三条链路跑到 99% 的成功率再逐步往体系里加新的技能。技能体系不是设计出来的是长出来的。每一个技能都要在真实流量里被反复调用、被发现问题、被迭代打磨之后才算真正“长在了系统里”。如果你的项目也正在做 Agent或者准备做 Agent不妨从标题里的“agent-skills”这个概念出发先梳理你手头业务里最常用的动作、最需要查询的知识、最核心的流程把它们变成技能清单再按我上面说的结构逐步实现。我个人对这些实践下来的体会是Agent 的智能不是模型的独角戏而是一整个技能基建托举的结果。模型给了 Agent 大脑技能体系才给了它真正干活的能力。希望这篇分享能帮你少踩几个坑。