Agent Skills 实战：一套技能，Web/IM/API 三端复用

做 AI Agent 应用最尴尬的场景往往不是模型不够聪明而是换一个平台就得把之前的代码重写一遍。我见过不少团队把第一个 Demo 跑通后老板说“把这个也接到 IM 上”结果大家发现之前写的工具函数、Prompt 规则和业务流程全绑在 Web 端逻辑里换个入口等于二次开发。这也就是 Agent Skills 这个概念出来后迅速被工程化团队关注的核心原因把 Agent 的能力拆成可复用的技能单元每个技能自带说明、参数定义和执行入口平台只负责调用不关心内部实现。这篇是这个系列连载的收尾篇前面几篇聊过单 Agent 的搭建、模型选型和推理加速这篇把重心放到多平台落地。Web 网页、企业内部 IM、开放 API 三种接入形态我们都实际做过文章里会给出 Skill 定义规范、示例实现、路由与降级策略以及上线之后排查过的四个真实问题。适合正在做 Agent 工程化、或者准备把现有 Agent 能力扩展到更多端口的同学参考。1. 为什么 Agent 开发需要 Skills 化从写死流程到能力复用1.1 Assistants 满天飞真正缺的是可复用的能力单元现在做 Agent 应用第一版 Demo 的实现方式通常高度相似一个编排函数里面塞了十几个 function calling 定义再配上几十条系统 Prompt 规则加上一堆 if/else 分支来处理特殊情况。这个阶段跑通业务逻辑没问题真正的问题出现在业务开始增长之后。首先是系统 Prompt 越来越臃肿。每加一个工具就要在 Prompt 里补充它的调用说明模型需要从越来越长的上下文里判断该调什么、不该调什么选错工具的概率急剧上升。其次是平台耦合。Web 端工具函数里混着 session 获取、回调地址、前端渲染逻辑这些换到 IM 端完全用不上。最后是测试困难。改一个工具的说明可能影响所有场景的决策但没有任何机制能快速验证影响范围。Agent Skills 的核心思路是给能力单元化。一个 Skill 包含四个部分什么场景下该用description、调用需要什么参数input schema、具体怎么执行handler、返回什么结构output schema。Agent 主循环退化成一套通用的“理解意图、选技能、调技能、总结结果”流程不再跟具体业务绑死。打个比方。以前是给每个平台单独写一本菜谱厨房流程互相独立现在先把食材预处理标准化菜谱只需要写“用预制好的食材做菜”谁来都能炒。这个转变带来的直接好处是新平台接入时大部分工作从“重写业务逻辑”变成“适配输出格式”。1.2 Skills 与 Tools、Workflow 的边界到底划在哪做 Skills 化之前团队内部必须对齐一个概念边界否则后面会吵个不停到底什么是 Skill、什么是 Tool、什么是 Workflow。我个人的划分经验是这样的概念粒度典型内容适合场景Tools原子操作HTTP 请求、数据库查询、加密解密一次函数调用即可完成Skills能力单元多个 Tools Prompt 模板 使用说明模型能“想明白应该用”的独立能力Workflow流程编排多个 Skill 串起来的固定顺序流程稳定、顺序确定的业务Plugins打包分发一组 Skills 配置 依赖对外发布、多应用共享判断一个能力到底该不该做成 Skill我常问三个问题模型只靠一段描述能不能决定是否调用它调用之后能不能直接得到用户要的结果这个能力能不能脱离当前业务场景独立测试三个问题都是“是”就做成 Skill。如果需要在多个 Skill 之间按固定顺序跳转、有条件分支那是 Workflow 的活别硬塞到单个 Skill 里。还有一个多平台场景下的关键点一次用户请求往往需要多个 Skill 组合完成这个组合应该由 Agent 主循环动态编排而不是写死在 Workflow 里。原因在于不同平台的交互习惯差异很大——Web 端可以连续追问IM 端用户可能发一句就等两分钟API 端则完全不支持对话。动态编排能把“组合逻辑”统一收口在 Agent 层Skill 本身保持单一职责这样才能保证“一份实现多处消费”。2. 多平台实战的选型过程从客服场景倒推 Skill 边界2.1 场景拆解先列需求再定 Skill 清单我用一个很典型的场景来说明整个选型过程售前售后客服 Agent。目标平台三个——Web 工作台、企业内部 IM、被第三方业务系统调用的开放 API。这类场景的通用性很强你手上的业务换个行业名词结构基本一样。先列需求清单意图识别区分售后咨询、订单查询、物流查询、退款处理、闲聊等订单状态查询用户提供订单号返回当前状态物流轨迹查询返回物流流转记录和最新位置话术生成生成安抚话术、解释说明、催办提示多轮澄清订单号缺失或格式不对时追问用户对照需求我划定的 Skill 清单如下order_status_query订单状态查询函数型logistics_track_query物流轨迹查询函数型reply_draft_generator话术生成Prompt 型意图识别和澄清不单独做 Skill直接由 Agent 主循环的模型能力承担这里要特别说明一个经验登录、会话管理、消息推送这类能力坚决不放进 Skill。它们和具体平台的绑定太深放进去会让 Skill 变得不纯粹也无法复用。Skill 应该尽量做到无状态、可重试、不关心用户从哪个端来。判断一个能力要不要沉淀为 Skill我总结四条标准语义清晰用户能感知到的能力边界、输入可控参数类型和范围可描述清楚、输出结构化返回字段可定义、可独立测试离开 Agent 也能跑通。四个条件缺一个就要重新考虑边界划分。2.2 Skill 的三种实现形态与选择逻辑确定 Skill 清单后接下来要为每个 Skill 选择实现形态。我实际用下来就三种Prompt 型不写代码靠 LLM 直接完成。适合纯语言任务比如话术生成、文本摘要、语气改写。优点是实现快、不依赖下游服务缺点是延迟高、结果不稳定同一个输入两次输出可能有差异。函数型绑定一个具体 handler适合有确定性数据源的任务——查订单、调接口、查数据库。优点是结果可靠、延迟低、能复用已有后端服务缺点是需要维护输入输出 schema模型构造参数出错时会直接失败。混合型先函数取数再 Prompt 组织语言。客服场景绝大多数是混合型——订单状态用函数拉取返回给用户的语气和结构由 Prompt 控制。选择逻辑其实很简单数据是确定性的函数化语言表达是核心的Prompt 化两类都重要混合。混合型要注意分工界限函数侧输出结构化数据Prompt 侧只做表达转换绝不能让模型自由发挥数据内容。比如物流轨迹里最新一条显示“运输中”Prompt 可以决定怎么说得更委婉但不能把“运输中”说成“已签收”。3. 手写一套可跨端复用的 Agent Skills定义、实现与调度3.1 Skill 定义文件一份清单两处消费Skill 定义文件是整个体系的基石。我习惯叫它 manifest格式用 YAML。它有一个很特殊的属性同时被调度器和大模型两方消费。大模型靠description决定要不要调用这个技能调度器靠entry和inputs决定怎么加载和执行。所以这份文件必须写得像对外 API 文档一样严谨。下面是一份实际可用的 manifest 示例name: order_status_query version: 1.2.0 title: 订单状态查询 description: 当用户询问订单状态、发货进度、物流配送、包裹到哪了等与订单履行进度相关的问题时 使用该技能查询订单当前状态。用户提供订单号时直接查询没有订单号时不要猜测 返回参数缺失由上层追问。 不要用于查询商品详情、退款金额、优惠券信息这些由其他技能处理。 entry: type: function runtime: python handler: app.skills.order_status.handler:run timeout_ms: 3000 inputs: order_id: type: string required: true pattern: ^[A-Z0-9]{6,20}$ description: 用户订单号通常由字母和数字组成 outputs: schema: app.skills.order_status.schema:OUTPUT_SCHEMA几个字段的实践经验description要写“用户会怎么说”不要写“系统能干什么”。“查询订单履行进度”这种描述对系统人员很清晰但用户不会这么说话要写成“发货进度、包裹到哪了、什么时候送到”这类自然表达。必须写反例。“不要用于查询商品详情、退款金额”这个反例能把误用率降一个量级。没有反例的后果是模型什么场景都想用同一个技能虽然能查到数据但回答完全答非所问。inputs里的pattern和enum要尽量给全。模型构造参数时如果没有任何格式约束它会用自然语言里的各种变形去猜比如把“订单号是 20241031A”猜成带汉字校验直接失败白白浪费一轮交互。3.2 用 Python 实现工单状态查询 Skill定义文件写好后接下来的问题就是 handler 怎么写。以订单状态查询为例import re from typing import Any def run(**kwargs) - dict[str, Any]: ctx kwargs.get(ctx, {}) order_id str(kwargs.get(order_id, )).strip() if not re.fullmatch(r[A-Z0-9]{6,20}, order_id): return {ok: False, reason: invalid_order_id} # 实际项目里这里调用订单服务 # order order_service.query(order_id, timeoutkwargs.get(timeout_ms, 3000)) order mock_query_order(order_id, ctx) if order is None: return {ok: False, reason: order_not_found} return { ok: True, data: { order_id: order[order_id], status: order[status], status_text: order[status_text], updated_at: order[updated_at], }, }几个设计要点都是踩过坑才总结出来的第一入口统一为run(**kwargs)。所有 Skill 的 handler 都遵循这个签名调度器不需要知道每个 Skill 的自定义参数结构只需要把模型返回的参数整个传进去。kwargs里除了声明过的业务参数还会带一个ctx里面放 trace_id、标准用户 ID、平台标识、超时时间这类基础设施信息。第二返回值全部走ok/error结构。okFalse时必须给出 machine-readable 的reason比如invalid_order_id、order_not_found、upstream_timeout。上层可以根据 reason 决定是追问、重试还是转人工而不需要解析自然语言错误。第三不要在 Skill 内部维护 session 状态。同一 Skill 可能被并发调用保持无状态才能水平扩展。如果确实需要缓存用外部缓存服务别用进程内变量。第四参数校验放最前面。宁可返回invalid_order_id也不要把脏参数打到下游。否则下游服务的报警会被无效请求淹没真实故障反而发现不了。3.3 注册、编排和三级降级Skill 写完要注册。我们生产环境用的是“配置目录 启动扫描”的模式每个 Skill 一个目录发布时自动扫描注册避免手改注册表导致漏配。注册完了Agent 主循环的编排逻辑就四步用户输入拼进系统 PromptPrompt 里带上所有已注册 Skill 的 manifest 摘要模型决定调用哪个 Skill、给什么参数调度器按 manifest 里的inputs做参数校验不通过就走降级执行 handler把结构化结果回填 Prompt模型基于结果生成给用户的回答。降级策略分三级。参数校验失败时先追问澄清不让用户看到系统报错执行超时或下游报错时先回复“正在处理稍后告诉你”这个回复要允许异步补偿后续结果通过 Web 推送或 IM 主动卡片补发补偿也失败时转人工座席并把 trace_id 带上方便人工快速拉取上下文。级降级在用户体感上是最重要的因为多平台场景下用户的耐心阈值差异很大IM 端尤其没耐心。4. 同一批 Skills 在 Web、IM、API 三种接入形态下的适配差异4.1 Web 端长上下文、流式输出、可交互中间态Web 端是三种形态里接入最舒服的因为它的宽容度最高。长会话让我们可以把多轮选择历史都保留上下文窗口压力小流式输出对用户体验提升也很大模型在“选技能”阶段就能给前端推“正在查询物流信息”的状态用户不会觉得系统卡死。实际操作上Web 端我们用 WebSocket 或 SSE 做流式推送。有个细节值得分享Agent 内部“即将调用哪个 Skill”这个事件也作为一条消息推给前端前端把它渲染成步骤条。实测下来用户等待焦虑明显降低因为大家能看到系统在一步步做事而不是转圈。这个设计只改前端Agent 侧只是多暴露一个事件钩子成本很低。另外Skill 执行完返回结构化数据后Web 端可以直接渲染表格、卡片不必依赖模型转述。比如物流轨迹函数侧返回 JSON 数组前端直接画地图和时间线又快又准。这要求 Skill 输出里保留结构化字段别在返回给 Web 端之前就让模型转成一段话。多技能组合场景Web 端是可用性最高的。“我上个月买的东西到哪了”这种输入需要先调订单列表 Skill 找出最近订单拿到 order_id 后再调物流轨迹查询。在 Web 端因为上下文长模型可以一步步完成这两个调用中间过程还能展示出来。IM 端这种组合就要谨慎原因后面说。4.2 IM 端消息截断、超时回调、身份映射IM 端是坑最多的地方。企业微信、钉钉、飞书、Slack 各有各的怪癖但共性问题就三件处理好了就稳了。第一消息长度与格式限制。不同的 IM 平台对单条消息长度、卡片字段都有上限而且限制差异很大。我们的做法是让 Skill 输出里带一个summary字段IM 端只消费 summary完整数据通过详情页短链跳转。也就是说Skill 从一开始就要考虑多端消费不能只输出一份完整数据。第二回调超时。多数 IM 平台要求机器人在很短时间内响应回调否则会重试或直接报错。Skill 只要执行超过 1.5 秒就先回一条“正在查询请稍等”然后异步执行完再主动推送结果。这里的挑战在于“先响应后推送”需要端上支持主动消息接入前要先确认平台能力别做完了才发现某个平台根本不支持主动推送。第三用户身份映射这是 IM 端最容易翻车的点。企业内部 IM 拿到的是企业通讯录 ID订单系统存的是平台用户 ID两边对不上。我们统一在接入层做转换把 platform_user_id 映射成标准 user_id 再塞进 ctxdef build_im_ctx(request): corp_id request.headers[X-Corp-Id] uid request.json[sender_id] # 映射到业务侧统一的 user_id user_id identity_mapper.to_standard(corp_id, uid) return { user_id: user_id, platform: im, trace_id: request.headers.get(X-Trace-Id, gen_trace_id()), }这个映射不做好Skill 层的权限校验会全线崩溃而且表现为“部分用户报错、部分用户正常”排查起来非常费劲。4.3 API 端契约化输出、限流与错误码语义化开放 API 的接入方是第三方系统它不会看 Prompt也不接受一段叙述性的回答。所以 API 端的核心是让 Skill 输出“契约化”。输入侧除了按 manifest 的pattern和enum做严格校验还要对调用方做鉴权AK/SK 或 OAuth 都行。输出侧按 JSON Schema 吐结构化数据错误码语义化invalid_order_id、order_not_found、upstream_timeout这些错误码要有完整文档。第三方研发拿着错误码表就能定位问题不用来问“你们这个返回到底啥意思”。并发控制是 API 端特有的问题。Skill 本身只是声明了timeout_ms但 API 网关层必须做限流。第三方系统可能用 for 循环批量调用处理不好下游订单服务直接被打挂。限流策略别做得太复杂先按调用方维度做令牌桶再按 Skill 维度设置最大并发两层就够了。最后是幂等。API 端如果支持重试Skill 得保证幂等。查询类本来就幂等但写操作类 Skill 必须加 request_id 去重逻辑否则一次重试可能产生两笔工单。三端适配差异我用表格总结一下接入新平台前先填一遍表哪里要补逻辑一目了然适配维度Web 端IM 端API 端鉴权方式统一登录 / Session企业通讯录映射AK/SK / OAuth输出格式富文本 / 图表文本摘要 / 卡片JSON Schema超时策略可接受较长等待秒级响应 异步补偿按契约约定上下文保留长上下文全保留尽量短不保留上下文交互能力强弱无5. 上线后踩过的四个真实坑及完整排查链路5.1 路由命中率低根源是 description 写成了“系统语言”现象很典型用户说“帮我看看快递到哪了”Agent 没有调用物流查询 Skill反而直接回答“我无法查询物流信息”。这种问题上线第一周就会有反馈因为你测试集里写的是“查询物流轨迹”真实用户说的是“快递到哪了”。我的排查链路是这样走的第一步打开日志找到这次请求模型实际选择技能的过程。发现模型压根没把logistics_track_query列入候选。第二步查看系统 Prompt 里该 Skill 的 description 原文“查询订单物流信息支持输入订单号”。第三步对照用户的原始句子和 description发现“快递”“到哪了”这些词一个都没出现。模型做技能选择时主要靠语义匹配description 越像用户口语命中率越高。修复方式是把 description 从“系统功能名”改成“用户可能怎么说”description: 当用户询问快递、物流、包裹、发货、配送、到哪了、什么时候到货、快递单号等物流相关问题时 使用该技能查询物流轨迹。不要用于查询订单金额、商品详情。用离线回归集50 条真实脱敏用户问题验证路由命中率从 61% 提升到 88%。这条经验后来成为我们的铁律description 面向用户口语写面向系统功能写等于没写。另一个技巧是每改一次 description 就跑一遍离线回归别直接在生产环境试错。5.2 上下文被 Skill 输出撑爆输出长度设计问题现象比较隐蔽刚开始没注意上下文 token 增量越来越大账单涨得很快而且到了一定临界点模型开始“忘记”用户最开始说了什么答非所问。排查链路用 token 统计工具看每轮对话的上下文构成发现 assistant 的工具结果占了 60% 以上。再看是哪个 Skill 贡献的结果很清晰——物流轨迹返回了完整流转记录大促订单有 30 条记录每条还有时间、网点名、备注信息。这些全部塞进上下文。根因很简单Skill 输出面向“完整数据”设计没有面向“决策上下文”设计。模型根本不需要 30 条记录逐字出现在上下文里它只需要知道最新一条到哪了、总共几站、有没有异常状态。修复方式return { ok: True, data: { order_id: order_id, current_location: latest[location], current_status: latest[status], total_stations: len(tracks), recent_tracks: tracks[:3], # 只保留最近三条 has_abnormal: any(t[status] abnormal for t in tracks), detail_url: f/api/orders/{order_id}/logistics, }, }完整明细放进独立详情接口需要时跳转查看。这个改动让单轮平均 token 消耗降了约 35%模型总结也更准了。后来我们给所有 Skill 立了条规矩输出是给决策用的不是给转储用的。凡是超过三条的列表默认给摘要加详情链接。5.3 IM 端身份映射不一致引发的权限爆炸这个坑的表现是Web 端和 API 端都正常IM 端一查订单就报permission_denied而且不是全部用户是部分用户。排查链路先看 traceIM 请求里的 user_id 和订单数据里的 owner_id 完全对不上。再看接入层代码IM 平台传的是企业通讯录内部 ID而订单服务里 owner_id 是平台用户 ID。为什么是偶发因为部分用户早期通过 Web 注册IM 绑定关系已经建好新入职员工没走绑定流程映射表里没有记录查订单自然没权限。修复方案分两步。第一步在 IM 接入层强制“先绑定后使用”没绑定时引导用户跳转 Web 完成一次绑定绑定后才允许调用任何 Skill。第二步ctx 里统一注入标准化 user_idSkill 层永远只认标准 ID不感知平台差异。做完这两步所有 Skill 的鉴权问题一次性解决。这个坑给我的教训是接入新平台时第一件要弄清楚的不是接口字段对应关系而是用户身份链路怎么走通。身份映射不解决后面所有 Skill 的权限校验都是空的。5.4 重试风暴下游抖动时 Skill 层把故障放大了现象某个下午订单服务响应变慢结果 Agent 侧错误率冲高下游负载反而比平时更高。看了监控才知道订单服务 P99 从 80ms 涨到 2 秒后Skill 层每个请求的平均重试次数飙到 7 次。根因有两层。第一层Skill 内部写了 while 循环重试Agent 编排层发现okFalse后又重试一次两层重试叠加放大。第二层重试没有退避全是立即重试下游刚恢复一点又被新一轮重试压垮。修复方案Skill 内部只做一次调用不加业务重试。重试是编排层的统一职责不要每个 Skill 各搞一套。编排层用指数退避重试1 秒、2 秒、4 秒最多 3 次。加熔断器连续失败超过阈值直接短路进入快速失败状态。下游恢复前优先返回“稍后再试”的兜底文案不给下游增加额外负载。这个坑在单平台时不容易暴露因为调用量小重试几轮无所谓。到了多平台聚合流量后一个小抖动就可能被重试逻辑放大成事故。所以我把“重试必须统一收口在编排层”写进了团队规范Skill 层严禁自建重试循环。6. 性能与质量优化让 Skills 在多平台稳定跑起来6.1 加载预热、manifest 分层与连接池复用Agent Skills 看起来是轻量函数生产环境里加载成本不是零。Skill 目录越来越大之后三件事必须做发布时预热。注册中心维护了 Skill 目录上线后要对每个 Skill 做一次冒烟调用。否则 handler 里的 import 错误、配置缺失要等用户真正触发才暴露排障窗口很难看。我们是在 CI 里加了一步构建完扫描注册中心逐个 Skill 发探针请求任何异常直接卡发布流程。连接池复用。Skill 经常要调下游 HTTP 服务和数据库。每个 Skill 自己 new 连接池是大忌连接数会随 Skill 数量成倍涨。正确做法是由运行时持有共享的 aiohttp Client 实例和数据库连接池通过 ctx 注入给每个 handlerSkill 只负责用不负责建。manifest 分层注入。模型做技能选择时需要把所有 Skill 的 description 放进系统 Prompt。实测 50 个 Skill 全量注入后单轮 token 增加约 3000这个成本相当可观。优化方案是分层注入系统 Prompt 只放每个 Skill 的一句话摘要加参数列表模型初步选出候选 Skill 后再把候选的完整 description 注入做二次决策。实测命中率几乎不掉token 开销明显下降。Skill 数量越多这套收益越大。6.2 全链路 trace、离线回归与 Skill 级断言多平台叠加后一次用户请求可能经历“平台接入层 → Agent 主循环 → Skill → 下游服务”四个环节没有 trace_id 串联出了问题基本没法查。我们的做法很朴素平台接入层从请求头取 trace_id取不到就生成一个trace_id 塞进 ctx所有日志、下游 HTTP header、报警消息都带上日志平台按 trace_id 聚合出问题先搜 trace再顺藤摸瓜。回归测试建议不要只做端到端成本高、不稳定跑一次要等模型推理好几个来回。更实用的是 Skill 级回归集准备一批真实脱敏用户问题标注期望命中的 Skill 和期望参数每次改动 manifest 或 handler跑一遍回归检查三件事模型选技能是否正确、参数是否符合 schema、返回是否通过自定义断言。自定义断言的例子很简单order_id必须匹配正则status必须在枚举列表里summary非空。这套东西投入不大但能挡住绝大多数“改了一个 description 导致别的场景误用”的回归问题。多平台项目里质量保障的重点不是最后一个环节而是每个 Skill 的边界是否清晰、契约是否稳定。我自己做完这套体系后最深的体会是Skills 化带来的最大变化不在代码复用而在于“能力的边界”第一次变得可以讨论、可以评审、可以版本化管理。以前团队争论 Agent 到底能不能查物流得翻代码现在看一眼 manifest 里的 description 就达成共识。产品、运营、下游研发都基于同一份定义对齐预期这个价值往往比省下来的开发工作量更大。有精力的话下一步可以往技能库共享的方向走把不同团队沉淀的 Skill 变成组织级资产那就是这个系列之外的另一个大话题了。