从零构建AI技能工程：Agent工具编排与云函数部署实践

在 Agent 开发圈里待久了你会发现一个很有意思的现象很多人花大量时间调 Prompt、搭框架最后却卡在工具怎么给 Agent 用这件事上。模型要调用一个函数你得写 JSON Schema要管鉴权要处理并发还要考虑工具之间的互斥一套下来比写业务逻辑还累。腾讯云的 AI Skills 正是冲着这个痛点来的——它把工具、技能、提示词编排放进一个标准化工程里让 Agent 的手脚不再是一堆散落的函数而是一套可复用、可部署、可被任意上层 Agent 调用的能力单元。这篇文章我会从零开始拆解一套完整的 AI Skills 实践路径覆盖技能定义、模板注入、工具编排、云端部署到联调排错的全过程适合正在做 Agent 落地、又不想被工程细节拖垮的开发者参考。1. Skill 和 Agent 先别混为一谈AI Skills 到底解决什么问题很多刚接触腾讯云 AI Skills 的人第一个困惑就是这玩意儿和 Agent 框架有什么区别我直接用 LangChain 或者自研一套工具调用体系不行吗先说结论AI Skills 不是又一个 Agent 框架它更像是 Agent 的外挂能力仓库——负责把模型能干的活标准化、模块化、可复用化而 Agent 本身负责决策和编排。两者是上下游关系不是替代关系。1.1 Skill 的定位从写死逻辑到声明能力传统做法里你想让 Agent 调用一个 API通常要经历这些步骤写函数、定义入参出参、生成 JSON Schema、处理鉴权、挂到 Agent 的 tools 列表里。这套流程每次新加一个功能都要重来一遍而且不同 Agent 之间的工具定义往往没法互相复刻换个项目就废了。AI Skills 的做法是把这一整套能力封装标准化了。你只需要写一份技能描述文件描述这个技能干什么、入参出参是什么、有哪些约束再配上具体的执行逻辑云函数也好、HTTP API 也好系统会自动帮上层 Agent 生成工具调用协议。Agent 看到的是一个技能名 参数列表不用关心背后是 HTTP 还是 COS 还是数据库操作。这就是技能和函数的本质区别——技能是带语义、带约束、可被发现的能力单元。拿我实际做的例子来说。我在腾讯云 Cloudbase 上建了一个 AI Skills 工程里面放了一个关键词聚合分析技能输入一堆文本输出高频词和聚合结果。这个技能在下游既可以被聊天机器人调用也可以被数据分析 Agent 调用甚至可以被一个定时任务主动触发。如果我当初只是写了个云函数那每次接入新上层应用都要重新写适配层但用 AI Skills我只改了一份工程配置所有接入方自动生效这份收益在项目大了之后特别明显。1.2 AI Skills 适合什么场景不适合什么场景基于我这段时间的实操AI Skills 最适合的是有明确边界、可重复调用、需要暴露给多个上层应用的能力场景。比如内容分类给一段文本打标签、分领域数据清洗输入脏数据输出标准化格式信息抽取从非结构化文本里抽实体、抽关系代码生成辅助按模板生成代码片段私有知识库问答把检索能力封装成一个技能供不同 Agent 复用反过来如果你的能力纯粹是一次性的、不打算复用或者核心逻辑严重依赖某种私有的长对话上下文那 AI Skills 可能不是最优选择——它更适合无状态、输入输出清晰的工具型能力。把全项目的记忆系统塞进 Skill 里那是拿刀叉喝汤使错了劲。2. 环境准备与工程骨架Cloudbase 上的第一个 AI Skills 工程腾讯云 AI Skills 目前是在 Cloudbase云开发体系里运行的所以第一步是把 Cloudbase 环境搭好。这里强调一个容易踩的坑AI Skills 不是单独的一个控制台入口而是在 Cloudbase 的AI 能力模块里。很多人一开始在云函数控制台翻半天找不到入口就是因为跑错了地方。2.1 开通 Cloudbase 环境与配套依赖登录腾讯云控制台搜索Cloudbase进入云开发控制台。如果是从零开始需要先开通按量付费环境然后等着环境初始化完成。这一步没什么技术含量但有几个配置细节会影响后续体验区域选择尽量和你其他云资源保持一致避免跨地域调用产生额外延迟记录好环境 ID后续的 skill.yaml 和多处 API 调用都要用到确认当前账号有 CloudBase 相关权限否则 AI Skills 控制台会提示权限不足开通环境之后Cloudbase 默认会带上云函数、云数据库、云存储这些基础能力。AI Skills 工程本质上是建立在这些能力之上的所以环境就绪后还需要在AI 能力模块里确认 AI Skills 是否已经启用。如果没有需要手动开通一下这一步通常几分钟之内就能生效。2.2 初始化目录结构与 skill.yaml 的写法工程骨架是 AI Skills 的核心我建议你直接在本地建一个干净的目录结构参考这样一个约定my-ai-skill/ ├── skill.yaml ├── prompt/ │ └── skill_prompt.md └── functions/ └── keyword-aggregator/ ├── index.js └── package.jsonskill.yaml是这个工程的大脑它声明了技能的名称、描述、参数以及运行方式和资源调度方式。下面是我实际用过的一个配置模板你可以直接拿来改name: keyword-aggregator version: 1.0.0 description: 对输入文本进行关键词提取和聚合分析返回高频词及聚合结果 author: your-name parameters: - name: text type: string description: 待分析的原始文本内容 required: true - name: top_n type: integer description: 返回前 N 个高频词默认值为 10 required: false default: 10 runtime: provider: cloudbase function: keyword-aggregator这里的重点是parameters和runtime两块。parameters定义了上层 Agent 如何调用这个技能模型会根据这里的描述自动填参数所以描述一定要写清楚否则模型传参时会靠猜效果很不可控。runtime指明实际的执行载体是哪个云函数这样技能定义和执行逻辑就解耦了。2.3 本地调试的方法一次跑通再上传直接写完就往云端传是新手最容易犯的错因为 AI Skills 平台对参数校验是比较严格的稍微有类型不匹配上层 Agent 调用时就会报错。我的习惯是先本地把云函数逻辑跑通再配置技能描述最后才上传。Cloudbase 的 Node.js 运行时和本地 Node 环境差异不大本地起一个 HTTP 服务模拟云函数入口输入测试用例验证核心逻辑基本就能把 80% 的 bug 挡在云外。调试时还有个小技巧在本地环境模拟函数的event结构时一定要严格按照云函数入参的格式来构造。AI Skills 在调用函数时参数会被封装成固定的结构如果你本地用的字段名和线上不一致排错会非常痛苦。我一般会写一个 mock 文件把 event 的样例固定下来每次改造逻辑都先跑一遍 mock 数据。3. 注入模板化思维系统提示词和 Skill 提示词的工程组合如果说 skill.yaml 是 AI Skills 的骨架那提示词就是它的灵魂。Agent 在调用技能之前模型要先理解这个技能是什么、什么时候该用、参数怎么填这些认知完全来自提示词。但提示词不是随便写一段话丢进去就行它需要和系统提示词、技能描述三者形成一套组合逻辑。3.1 把 System Prompt 做成可插拔的模板我在这次实践中发现很多人把系统提示词写成了一个巨大的 JSON 字符串塞给模型这种做法维护成本极高。更好的方案是模板化 渲染把固定部分和动态部分分开固定部分写技能使用规则和输出格式约束动态部分由上层应用传入上下文。举个例子我的 Agent 项目里系统提示词模板大概是这样的你是一个全能助手可以调用以下技能完成用户请求 - 关键词聚合分析对文本进行关键词提取和聚合 - 内容分类对文本进行多标签分类 使用技能时严格遵守以下规则 1. 必须先分析用户意图再决定是否调用技能 2. 参数必须严格按照技能描述中的要求传入 3. 如果技能执行失败要基于返回信息向用户说明原因这部分在上层 Agent 初始化时是固定的但在 AI Skills 工程里技能描述本身又会被独立读取。所以系统提示词里只需要写有哪些技能、什么时候用具体参数说明不要重复粘贴——避免两份描述不一致导致的调用失效。这是个非常隐蔽但很致命的问题我踩过一次技能描述里参数叫text系统提示词里我习惯性写成了content结果模型调用时按提示词来传参全部失败。3.2 技能内部 Prompt 与外部 Prompt 的分工AI Skills 支持在工程里维护一份技能内部提示词这份提示词不直接暴露给 Agent 的主对话而是在技能执行时辅助模型理解本次调用。它的典型用途是当技能有多个执行分支时根据入参动态决定走哪个分支。我在 keyword-aggregator 这个技能里就给内部提示词写了一个规则如果top_n小于 5走精简模式只提取核心实体词如果top_n大于等于 5走完整模式额外输出词频分布和建议标签。模型在技能内部会基于这个提示词做二次推理这样的分层设计让技能的灵活性高了很多。实践证明外部提示词管选择、内部提示词管执行是一个很稳的组合方式。外部提示词告诉模型什么时候用这个技能内部提示词告诉模型具体怎么跑两者职责清晰调试时可以独立优化不需要每次改动都全量测试。4. 工具内置与编排把管道上的每个环节做成可组合的乐高一个实用的 Agent 技能内部往往不止一步逻辑。拿关键词聚合分析来说它至少包含文本清洗、分词、词频统计、结果排序四个环节。如果这四个环节全部写在一个云函数里代码会越来越臃肿后续想改一个环节都得牵动全局。所以我的实践思路是把每一步拆成独立工具然后在 Skill 层面做编排。4.1 用四个内置工具串起一个完整管道Cloudbase 的 AI Skills 支持在一个技能工程里内置多个工具每个工具对应一个函数或一个 API 调用。整个管道是文本清洗工具负责去标签、去特殊字符、统一大小写分词工具基于词表做中文分词返回候选词列表词频统计工具对分词结果做 MapReduce 风格聚合输出词频字典结果格式化工具按top_n截断并生成最终 JSON 结构每个工具都是独立的云函数他们的输入输出通过 Skill 编排层串起来。好处是当某一步算法升级时我只需要替换那一个函数其他环节不用动。坏处是链路变长单次调用的时延会有增加但权衡下来收益大于成本——尤其是在多人协作的团队里。4.2 编排配置的核心字段依赖关系如何声明工具编排的配置写在 skill.yaml 的workflow或tools区域里具体取决于控制台版本它的核心是声明每一步的inputFrom和outputTo。我用一个简化版来说明workflow: - name: clean function: clean-text inputFrom: [text] outputTo: [clean_text] - name: segment function: segment-text inputFrom: [clean_text] outputTo: [word_list] - name: count function: count-frequency inputFrom: [word_list] outputTo: [freq_dict] - name: format function: format-result inputFrom: [freq_dict, top_n] outputTo: [result]这段配置是整条管道的乐高拼图说明。当你配置完 workflow 之后Skill 运行时会产生一份完整的执行拓扑上层 Agent 只需要调用一次技能后面四个工具会自动按顺序执行。这也是 AI Skills 最有价值的地方——Agent 看到的是一个技能 若干参数背后却是一条完整的数据管道。4.3 尽量保持工具无状态缓存和中间结果放在哪里管道跑起来之后一个现实问题就是每一步的中间结果存在哪我的建议是尽量保持工具无状态中间结果通过事件的context字段向后传递不要写到云数据库里除非有审计需求。原因有两点一是提高并发能力无状态函数可以水平扩展而不担心共享状态冲突二是降低成本数据库写入是额外开销对短生命周期数据来说纯属浪费。如果你的某个工具确实需要做缓存比如分词词表加载很慢那就用 Cloudbase 的临时存储或内存缓存注意设置合适的 TTL避免缓存穿透。我在分词工具里就加了一个词表缓存冷启动耗时从 1.2 秒降到了 300 毫秒左右效果立竿见影。5. 从本地到云端的部署链路上传、验证和版本管理工程写完、本地调通之后就到了部署环节。AI Skills 的部署流程和传统云函数部署大同小异但有几个坑只有实际部署过才会遇到。我在这部分会把完整的链路和注意事项都讲清楚。5.1 使用 Cloudbase 框架 CLI 的上传流程我推荐用 Cloudbase 官方的 CLI 工具来部署核心命令是tcb framework deploy执行这个命令之前需要确保已经安装了 Cloudbase CLI并且已经用有权限的账号完成了登录认证。推荐用 API 密钥的方式认证在腾讯云访问管理控制台创建一个子账号只授予 CloudBase 相关的权限然后用这个子账号的密钥来做 CLI 登录。这样做比直接用主账号安全得多即使密钥泄露也能快速吊销。工程上传后可以在控制台的 AI Skills 列表里看到你的技能和对应的云函数。你还需要做一个发布操作把草稿状态切换到已发布上层 Agent 才能在运行时发现这个技能。这一步我见过很多人漏掉导致明明上传成功却调用不到排查半天发现在草稿箱里躺着。5.2 上线后的三种验证方式部署完成不代表万事大吉至少要用三种方式验证技能是否真正可用控制台测试页在 AI Skills 详情页直接填写参数调用确认返回结构和预期一致函数日志去云函数控制台查看最近一次调用的日志输出确认中间步骤没有静默报错上层 Agent 实测通过自然语言发一个请求观察 Agent 是否能正确选择技能并传参这三种方式缺一不可。控制台测试能验证技能本身函数日志能验证底层异常Agent 实测能验证意图识别 参数映射这条链路的准确性。尤其是第三种很多技能在控制台测试一切正常但真的让 Agent 自主调用时会出现参数乱传、回应格式错乱等问题原因多半是技能描述写得不到位——模型没看明白这个技能到底是干嘛的。5.3 版本管理灰度发布和回滚的实操办法AI Skills 的版本管理沿用云函数的版本机制我在实践中的流程是这样的每次改动先在本地打 tag部署时新建一个版本别名测试通过后再把别名切到默认流量。如果线上出了问题可以直接把别名指回上一个稳定版本实现秒级回滚。这里有一个值得注意的细节AI Skills 的发布状态和云函数版本不是强绑定的。也就是说你可以更新云函数的代码和版本但技能的version字段还停留在旧值。为了让上层 Agent 感知到变化我建议每次重大更新都同步 bumpskill.yaml里的version并更新description里的变更说明比如注明支持新增 XX 参数。这样 Agent 在运行时能感知到技能版本变化不会继续用旧的行为模式去调用。6. 踩坑实录Coding Agent 调用 Skill 时的三个高频问题最后一部分我总结三个我在实践中反复踩到的坑它们几乎每个都在真实项目里出现过而且表现非常隐蔽。如果你正打算把 AI Skills 接入某个 Coding Agent 或其他上层应用这几种情况值得提前预防。6.1 参数类型不匹配模型把字符串传给了数组AI Skills 在生成调用协议时会严格校验参数类型。但 LLM 在自主调用场景下经常会把入参搞错——最常见的是把数组类型传成了一个以逗号分隔的字符串。比如我定义了一个tags参数类型是array模型却传成了tag1,tag2。如果不做兼容处理函数端做tags.map()就会直接抛异常。我的解决方案是在函数入口加一个参数容错层。先判断类型如果是字符串就按分隔符拆成数组再做后续处理。这个容错逻辑虽然不优雅但在生产环境下能救回至少一半的调用失败。6.2 描述词太模糊Agent 该用的时候不用不该用的时候乱用技能描述写得太短模型就无法准确判断什么时候该触发这个技能。我最初给 keyword-aggregator 写的描述只有一句分析关键词结果 Agent 经常在用户问天气的时候也去调用它。后来我把描述扩展为description: 对用户提供的原始文本进行关键词提取和聚合分析。 当用户希望从一段长文本中快速了解主题、关键词或热门实体时使用。 也适用于内容分类、标签推荐、自动摘要前置处理等场景。 如果用户没有提供文本仅询问关键词概念不应调用此技能。改完描述之后调用准确率有了肉眼可见的提升。这个经验可以总结成一句话描述里不仅要说能做什么还要说什么时候该做、什么时候不该做。这是模型做工具选择时最重要的决策依据。6.3 超时与冷启动的平衡Coding Agent 等不起 5 秒Coding Agent 这类应用对延迟的敏感度非常高——用户正在写代码如果你返回一次技能调用的时间超过 3 秒体感就会很卡。云函数的冷启动是延迟的主要来源尤其是 Node.js 运行时加载依赖较多的场景。我做了三件事来缓解一是精简依赖把非必要的 npm 包移到懒加载里二是设置合适的并发实例数保证常用技能有热实例三是在客户端加了一个超时重试机制——如果第一次调用超时第二次大概率能命中热实例耗时能降到 500 毫秒以内。这套组合拳实测下来把平均调用耗时从 2.8 秒压到了 1.2 秒左右Coding Agent 的用户体感终于不那么拖沓了。踩过这些坑之后我的整体感受是AI Skills 最大的价值不是让你少写代码而是让你把能力从代码里解放出来变成可被描述、可被编排、可被复用的一种资产。它把 Agent 的落地门槛从工程化拉回到了配置化逻辑化这对想做 Agent 产品的人来说是一条很值得投入的路径。如果你正在设计自己的 Agent 能力层不妨从一个小技能开始先把一条管道跑通再逐步扩展成能力矩阵。你会发现当技能足够多、编排足够顺的时候Agent 的表现会上一个很大的台阶——那才是全能 Agent真正开始成型的样子。