腾讯云 AI Skills 实战：从零构建可编排的 Agent 技能体系

1. 从“聊天机器人”到“会干活的 Agent”，差的就是 Skills

最近在折腾 Agent 项目的人应该都有同感：单聊模型能力，各家大模型已经卷得差不多了，真正让开发者头疼的是怎么让 Agent 稳定地完成一套实际任务。我看了不少团队的做法，也踩过不少坑，最大的体会是——Agent 能不能“干活”，取决于它有没有一套规范、可复用、能被编排的“技能”。这个词最近在圈子里叫 AI Skills，很多云平台也把它当作核心能力在推，腾讯云 AI Skills 就是其中一个典型实现。

一开始我也把注意力全放在提示词上，觉得 Agent 聪明不聪明主要看 Prompt。后来做了一两个偏业务的落地项目才发现，提示词只是最表层的东西。真正让 Agent 从“能聊”变成“能干活”的，是你给它挂了哪些可调用的技能、这些技能怎么被选择、怎么传参、怎么容错、怎么跟外部系统对接。这也是我决定把腾讯云 AI Skills 的完整实践过程整理成文的原因。

这篇文章不会只贴一份配置截图就完事，我会从“AI Skills 到底解决什么问题”开始拆，然后带你走一遍在腾讯云上创建技能、发布服务、用代码调用、再接入多 Agent 编排的完整链路，最后把我在实际部署中遇到的坑和排查思路一并交代清楚。适合正在做智能体项目的开发者、准备把 Agent 能力产品化的技术负责人，以及刚接触 Agent 开发但想走正路、少踩弯路的入门者。

2. AI Skills 的本质，是把 Agent 的“临时发挥”变成“标准接口”

在聊具体操作之前，得先把概念掰扯清楚。很多人会把 AI Skills 和 Prompt、插件、Function Calling 混在一起，但它们解决的其实是不同层面的问题。

2.1 从提示词到函数调用，再到独立技能服务

先说第一个层面：提示词。提示词是给模型“看图说话”的说明书，它决定了模型面对一段输入时怎么组织输出。但它的问题是不稳定，换一个模型版本、换一种问法，结果就可能飘。第二个层面是函数调用，也就是 Function Calling。它让模型可以按照约定的 JSON Schema 去调用外部函数，这一步比裸提示词前进了一大截，因为模型终于能“动手”了，而不只是“动嘴”。

但函数调用仍然不够。它的问题在于：函数是散落在代码里的，一个函数服务于一个场景，换一个 Agent 项目，原来的函数基本没法直接迁移，得重新黏合业务逻辑。AI Skills 做的事情，是把“函数调用”再往前推一层，变成独立发布、独立维护、可被多个 Agent 按需调用的服务。

用生活化一点的类比：函数调用像是你家里的工具箱，每个工具都有固定用途，但拿来找邻居借、跨小区用就很费劲。AI Skills 则像是把工具打包成了标准接口的共享工坊，任何人只要按照约定下单，就能拿到服务，不需要关心工坊内部是怎么运作的。

2.2 腾讯云 AI Skills 的架构位置

腾讯云 AI Skills 从产品形态上看，处于模型层和应用层之间。模型层是混元、DeepSeek 这类大模型，应用层是你自己写的业务系统或者 Agent 编排框架。AI Skills 承担的角色是给模型提供可执行的原子能力，比如查天气、算个税、生成图片、查询数据库、调用内部 API 等等。

它和 Agent 的关系，我习惯用一句话总结：Agent 是大脑，Skills 是手脚。大脑负责理解任务、拆解步骤、判断该用哪个技能，手脚负责真正把事儿办了。没有 Skills，Agent 再聪明也只能输出文字建议；有了 Skills，Agent 才能真正处理业务请求。

这里要注意一个常见认知误区：Skills 不等于插件。插件往往是形态固定的扩展包，而 AI Skills 更强调“技能”的原子化和编排弹性。同一个技能可以被不同的 Agent 以不同的顺序调用，甚至可以在运行时动态决定参数组合，这是插件模型很难做到的。

2.3 为什么我推荐把技能“服务化”而不是“代码化”

我在第一版 Agent 项目里，所有技能都是直接写在代码里的函数。项目跑起来没什么问题，但一旦技能数量超过十个，问题就来了：一是代码仓库越来越臃肿，每次加技能都要改主流程代码；二是技能之间出现耦合，改一个函数的入参，可能连带影响另一个逻辑；三是没法复用，换一个新项目，几乎所有技能都要重写。

后来我把技能全部迁移到腾讯云 AI Skills 上，本质上是做了一个“技能服务化”的改造。每个技能独立为一个服务，通过标准 HTTP 接口暴露，Agent 侧只保留技能 ID 和参数 schema。这个改造带来几个直接收益：

• 技能生命周期独立：某个技能要升级，不影响其他技能和 Agent 主流程
• 可观测性提升：每个技能的调用次数、耗时、失败率都有独立指标
• 不同 Agent 复用同一套技能池：新增 Agent 时只需要做编排，不需要重新发明轮子

说白了，这是把“面向代码编程”变成了“面向能力编排”。如果你的 Agent 要做成产品，这条路几乎是必走的。

3. 在腾讯云 AI Skills 上创建第一个技能：完整实操流程

接下来进入正题。我会以一个“智能日程助手”的技能为例，走一遍从创建技能到完成联调的完整过程。这个技能做的事情是：接收用户的一句话描述，解析出日程的时间、地点、事件，再调用一个模拟的日历服务完成创建并返回确认结果。

3.1 创建前的核心设计：意图、入参、出参与工具

创建技能的第一件事不是打开控制台，而是先在纸上把技能边界画清楚。我建议你至少想明白四个东西：意图、入参、出参、调用的外部工具。

以智能日程技能为例：

• 意图：提取用户文本中的日程信息，调用日历服务创建日程
• 入参：用户原始文本（例如“明天下午三点和产品团队开会，会议室 A201，时长一小时”）
• 出参：结构化日程对象，字段包括 title、start_time、end_time、location、participants
• 外部工具：一个模拟的日历创建 API，接收日程对象

这几个东西想清楚了，后面的配置就很顺。很多人创建技能失败，多半是没想清楚入参和出参的边界，结果模型的输出要么字段缺失，要么类型混乱。

3.2 一步步配置：从意图定义到提示词模板

登录腾讯云控制台，找到大模型知识引擎或者 AI 应用平台相关的入口，进入 AI Skills 管理页面，按照下面的步骤操作：

1. 新建技能：填写技能名称、描述、所属分类。技能描述我建议写详细一点，因为它会被 Agent 用来判断何时调用这个技能，描述越清晰，Agent 的选择准确率越高
2. 定义意图：在配置面板里填写技能的核心能力说明，也就是“这个技能是干什么用的”，语言要尽量贴近真实业务场景
3. 编写提示词模板：这是很关键的一步。提示词模板的作用不是让模型自由发挥，而是约束它“怎么用这个技能”。我会在模板里写明用户的输入格式、解析规则、输出 JSON 的结构要求，以及边界情况如何处理
4. 配置入参出参：在 schema 里定义参数的类型、是否必填、取值范围。注意，这里的参数不只是给模型看的，也是给后续调用方看的，定义了规范，谁都别乱来
5. 关联外部工具：如果你要调用的日历服务已经做好了 API，把地址和鉴权方式填进去，AI Skills 平台负责在模型生成结构化参数后发起实际调用
6. 保存并进行测试：在在线调试区域输入一段话，比如“下周三上午十点约张伟在咖啡厅聊预算”，看看返回的日程对象是否结构正确、字段是否齐全

这里有一个经验：提示词模板不要写成长篇大论，而是像“填空题”一样，把必须输出的字段用 JSON 表示出来，给一个示例。模型对示例的遵循度，远高于对一堆规则的遵循度。

3.3 参数设计中的两个关键细节

第一，时间类参数不建议让模型直接输出“明天下午三点”这种相对时间。最好在提示词里告诉模型，当前的时间戳是多少，让它转换成绝对时间再输出。我当时第一次测试就踩了这个坑，模型返回的 start_time 是“明天下午3点”，下游日历服务直接解析失败。后来在模板里加了“当前时间是 2025-XX-XX，请将相对时间转为具体年月日时分”之后，所有解析都正常了。

第二，可选参数要显式声明。比如“参与者”可能为空，这个技能也要能正常返回，而不是每次都强制要求模型凑一个参与者出来。在 schema 里把 required 和 optional 分开，模型的行为会规矩很多。

3.4 一个可复用的提示词模板参考

下面这个模板是我在腾讯云 AI Skills 上调出来的版本，你可以直接拿去改：

你是日程解析助手。请从用户输入中提取日程信息，输出为 JSON 对象。 当前时间：{current_time} 输出结构要求： { "title": "日程标题，字符串", "start_time": "开始时间，格式为 YYYY-MM-DD HH:mm", "end_time": "结束时间，格式为 YYYY-MM-DD HH:mm", "location": "地点，字符串，没有则为空字符串", "participants": ["参与者，字符串数组，没有则为空数组"] } 规则： 1. 如果用户输入中没有明确结束时间，默认持续 1 小时。 2. 所有相对时间（如“明天”“下周三”）必须转换为具体的日期时间。 3. 只输出 JSON，不要输出其他内容。 示例输入：明天下午三点和产品团队开会，会议室 A201，时长一小时 示例输出：{"title": "产品团队会议", "start_time": "2025-06-11 15:00", "end_time": "2025-06-11 16:00", "location": "会议室 A201", "participants": ["产品团队"]} 用户输入：{user_input}

这个模板的核心思想是：把规则压缩到最少，把示例给足，让模型按示例的“样子”去执行。

3.5 联调验证：在线调试与 API 测试

配置完成后，在平台自带的调试器里做几组测试用例。我建议至少测这几类：

• 标准完整输入（时间、地点、事件都齐全）
• 缺失部分信息（没有地点）
• 模糊时间表达（“大后天”“下周一早上”）
• 无效输入（一句话乱码，或者完全不相关的内容）

测完之后打开调用日志，逐条看模型的输出质量，重点看有没有反复出现字段缺失、格式错误。发现问题就回去调提示词模板，不要指望一次就能调到完美。我在日程这个技能上，前后调了大概五版模板才算稳定。

4. 本地 Agent 联动腾讯云 AI Skills：代码级对接方案

技能创建好之后，只等于你有了一个“可供调用的服务”，真正要让 Agent 跑起来，还得在你的代码项目里接入这个服务。这一节讲两种最常见的方式：直接 HTTP 调用，以及通过 liteLLM 这类网关做统一接入。

4.1 用 API 调用技能：我选 Python 而不是 SDK

腾讯云 AI Skills 发布后，会暴露一个标准的 HTTP 接口。我习惯直接用 Python 的 requests 库去调，而不是在项目里引入全套 SDK。原因有两个：一是减少依赖，项目里不用为了一个接口装一堆包；二是排查问题方便，请求和响应都清晰可见。

下面是一个最简调用示例：

import requests import json # 实测中我把 base_url、api_key 放在环境变量里，方便多环境切换 base_url = "https://your-endpoint.tencentcloudapi.com" api_key = "your-api-key" def call_skill(skill_id, user_input): url = f"{base_url}/skills/{skill_id}/invoke" headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json" } payload = { "input": user_input, "session_id": "test-session-001" } resp = requests.post(url, headers=headers, json=payload, timeout=30) resp.raise_for_status() return resp.json() if __name__ == "__main__": result = call_skill("calendar-skill", "明天下午两点和客户开需求评审会") print(json.dumps(result, ensure_ascii=False, indent=2))

几点说明：

• 我在调用时把超时设成 30 秒，因为模型推理加工具调用整体耗时较长，时间太短容易误报失败
• session_id 建议每次请求带上，方便在平台上按会话维度追踪日志
• 如果技能内部还要调外部 API，整体耗时可能会到 5-10 秒，属于正常范围，调用方要有心理预期

4.2 把 AI Skills 挂到 liteLLM 网关后面，好处在哪里

有些场景下，你本地 Agent 不是直接对接某一个模型，而是通过 liteLLM 这类代理网关统一管理多个模型和多个服务。AI Skills 也可以被“伪装”成一个模型端点，挂到 liteLLM 网关后面，好处是 Agent 侧只认 OpenAI 兼容的接口，不用为每个技能单独写一套适配代码。

这里我分享一下我在腾讯云服务器上配置 liteLLM 代理把 AI Skills 纳为自定义端点的思路（完整配置较长，这里给核心片段）：

model_list: - model_name: skill-calendar litellm_params: model: openai/your-skill-calendar-endpoint api_key: ${SKILL_API_KEY} api_base: https://your-endpoint.tencentcloudapi.com/skills/calendar custom_llm_provider: openai

配置完成后，你在本地代码里调用 model 名为 skill-calendar 的“模型”，实际上就是在调用腾讯云上的日程技能。这种方式适合已经有 liteLLM 网关、不想大规模改 Agent 代码的团队。

另外一个很常见的用法是，用 liteLLM 的fallbacks机制，把同一个技能配成多个可用端点，某个端点超时或失败时自动切换。我就在生产环境里给一个关键技能配了主备两个区域端点，实测故障切换对业务几乎无感。

4.3 Prompt 本地剥离：为什么 Agent 的“嘴”和“手”要分开

在接入技能的过程中，我强烈的建议是：不要把技能的调用逻辑写死在 Agent 的系统提示词里，而是让 Agent 通过“技能发现”去找到适合的技能。

我当时的做法是：在 Agent 的上下文里维护一份技能清单，每一项包括技能 ID、名称、描述、参数 Schema。Agent 在收到用户请求后，先根据清单判断要不要调用技能、调用哪个技能，然后构造出结构化调用请求，再交给执行器去真正调腾讯云 AI Skills 的接口。

这套设计的优点是：

• 新增技能时，只要在清单里加一项，Agent 自动具备新能力
• Agent 主提示词保持简洁，不容易被各种规则塞爆
• 换技能、下线技能都很灵活，不用改主流程

如果你用的是 LlamaIndex 或 LangGraph 这类框架，这个“技能发现-调用执行”的流程可以被很好地抽象成 Node 结构，调试也更直观。

5. 多 Agent 场景下的技能编排：我在腾讯云上的生产实践

单技能能跑通之后，下一个问题自然就是：多个技能怎么编排？尤其是当你需要让多个 Agent 协作完成一个复杂任务时，技能的编排方式直接决定了系统的上限。

5.1 技能池 + 路由层：让 Agent 学会“找对工具”

我先创建一个技能池，把所有技能统一注册到腾讯云 AI Skills。然后在 Agent 之上加一个路由层，路由层的工作是：看懂用户请求 -> 判断需要哪些技能 -> 决定调用顺序 -> 汇总结果。

我用三个 Agent 做了一个小规模落地项目：

• 意图分诊 Agent：负责理解用户请求，判断属于哪个业务域，并输出技能调用序列
• 执行 Agent：按照序列逐个调用腾讯云 AI Skills 上的技能，捕获执行结果
• 校验 Agent：检查执行结果是否符合预期，不满足就打回重跑

三个 Agent 共享同一个技能池。新增一个技能时，只需要在分诊 Agent 的技能清单里登记，后续执行和校验逻辑不需要动。

5.2 一个实用的多技能协同案例：会议纪要自动生成

举一个我们真实跑通的场景：用户在 IM 里丢入一段会议录音转写文本，并说“帮我生成会议纪要给参会人”。

这个任务拆解出来需要三个技能：

路由层的意图分诊 Agent 收到请求后，先调用 meeting-transcript 提取结构化信息，然后调用 calendar-query 关联日程，最后把整理好的纪要丢给 message-push 推送。整个过程用了不到 20 秒，而人工去做，光是整理纪要就是这个时间的好几倍。

这里有一个经验：不要试图让一个技能干所有事。技能越原子，复用性越强，编排越灵活。你要是把“提取会议要点”和“推送消息”揉成一个技能，下一个场景想做“只推送不提会议”，就得重写技能。

5.3 技能编排中的 Action 字段设计

腾讯云 AI Skills 在调用时会返回一个标识，表明这个技能属于“工具调用”动作。在多 Agent 编排时，我给每个技能调用都附加了一个统一的协议，核心字段包括：

{ "action": "invoke_skill", "skill_id": "calendar-query", "params": { "participants": ["张三", "李四"], "time_window": "2025-06-15~2025-06-19" }, "retry_count": 2, "fallback_skill": "calendar-query-bak" }

这个协议有几个作用：执行 Agent 拿到之后可以直接解析并调用；校验 Agent 能根据 action 类型做更精确的合法性检查；重试和降级策略也可以在协议层面统一配置，而不是在代码里散落各处。建议你在设计技能编排时，也先定义一个统一的调用协议，这比每个 Agent 各写各的调用逻辑要规范得多。

6. 腾讯云基础设施层的配套准备工作

Agent 要跑得稳，光有技能编排还不够，底层的云服务器、数据库、镜像仓库这些配套也得跟上。这一节整理我在这类项目部署时经常碰到的几个基础设施事项。

6.1 服务器选型与二级域名申请

我跑这类 Agent 服务用的是一台腾讯云轻量应用服务器，配置是 2 核 4G，日常跑几个技能服务的 API 转发完全够用。但如果你的 Agent 要频繁调大模型推理，建议 CPU 升到 4 核，内存升到 8G，不然推理时的并发一上来，进程容易被直接打挂。

在上面部署服务时，用 IP 访问既不美观也不方便配 HTTPS，我申请了腾讯云的二级域名来做服务暴露。流程不难：在腾讯云控制台绑定域名，到 DNS 解析处添加一条 A 记录，指向服务器 IP，等生效后用http://your-subdomain.example.com访问即可。

注意一点：如果想用 443 端口走 HTTPS，需要在腾讯云上申请 SSL 证书，然后配置 Nginx 反向代理，把location /转发到本地 8000 端口（你自己的服务监听端口）。证书是免费的，免费版有效期一年，到期前要记得续期，我因为忘记续期吃过一次服务中断的亏。

6.2 Redis：技能调用的缓存与状态管理

Agent 服务里 Redis 是我必装的组件，主要用来做两件事：

• 缓存 AI Skills 的调用结果，比如某些查询型的技能结果在十分钟内是相同的，直接走缓存，省一次模型调用的费用
• 保存 Agent 的会话状态，让多轮对话能延续上下文

安装和配置很简单，但有一点必须提醒：修改 Redis 密码之后重启服务，一定要确认配置文件中requirepass的写法正确。我遇到过几次这种情况，密码文件的权限不对，导致 Redis 进程启动后不读新密码，客户端全部报NOAUTH Authentication required。排查半天才发现是修改密码时不小心多了一个空格字符。

建议修改完密码后，用下面这条命令验证：

redis-cli -a '你的新密码' ping

返回PONG才说明密码生效。如果返回NOAUTH，多半是服务没重启成功或者密码配置有问题，不要急着继续调试业务代码，先把登录关过了再说。

6.3 把 Agent 服务镜像化，推送到腾讯云容器镜像服务

当你的 Agent 服务要上生产环境，用 Docker 镜像比在服务器上裸跑进程要靠谱得多。我在腾讯云上把服务打成镜像，推送到腾讯云容器镜像服务（TCR）里管理，然后拉取到云服务器运行。

推送镜像的基本流程如下：

1. 本地构建镜像：docker build -t your-image-name:0.1.0 .
2. 登录腾讯云镜像仓库：docker login ccr.ccs.tencentcloud.com，输入镜像仓库的账号密码
3. 给本地镜像打上仓库地址的 tag：

docker tag your-image-name:0.1.0 ccr.ccs.tencentcloud.com/your-namespace/your-image-name:0.1.0

4. 推送镜像：

docker push ccr.ccs.tencentcloud.com/your-namespace/your-image-name:0.1.0

推送时最容易遇到的坑是镜像过大导致超时推送失败。我在打包 Agent 镜像时发现，Python 基础镜像加上依赖包轻轻松松就超过 1GB。后来改用 slim 基础镜像，把不需要的编译工具全部省掉，镜像体积降到 400MB 左右，推送速度明显提升。

如果你遇到推送不上去的问题，先检查本机 Docker 是否登录成功，再确认命名空间是否写错，最后看镜像 tag 是否包含了完整的仓库地址。这三个点排查完，绝大多数推送问题都能解决。

6.4 用 Docker Compose 管理 Agent 全家桶

当你的 Agent 服务还需要 Redis、MySQL、Nginx 做支撑时，我建议直接用 Docker Compose 把它们管理起来，而不是手动一个个docker run。

下面是我在一个 Agent 项目里的 compose 文件片段，你改改服务名和端口就能用：

version: "3.8" services: redis: image: redis:7-alpine container_name: agent-redis ports: - "6379:6379" command: ["redis-server", "--requirepass", "${REDIS_PASSWORD}"] volumes: - redis-data:/data restart: unless-stopped agent-api: image: ccr.ccs.tencentcloud.com/your-namespace/your-agent-image:0.1.0 container_name: agent-api ports: - "8000:8000" environment: - REDIS_HOST=redis - REDIS_PORT=6379 - REDIS_PASSWORD=${REDIS_PASSWORD} - AI_SKILLS_API_KEY=${AI_SKILLS_API_KEY} depends_on: - redis restart: unless-stopped volumes: redis-data:

depends_on保证了 Redis 先启动，restart: unless-stopped保证了进程意外退出后能自动拉起。这个配置让整个 Agent 服务的运维成本低了很多。

7. 常见问题与排查技巧实录

做 Agent 项目最耗时间的不是写代码，而是排查各种莫名其妙的问题。我把实际过程中遇到的高频问题整理成表，再挑几个重点展开说说。

7.1 技能调用返回结果不稳定，字段缺失

这个问题的典型表现是：同一段输入，十次调用里有八次返回正常，两次出现某个字段为空或者格式错误。排查思路是这样的：

先看平台侧日志，确认模型输出到底长什么样。如果模型输出本身就不稳定，那问题多半在提示词模板，建议把规则再收紧，给更多示例。如果模型输出正常，但下游解析失败，那问题出在接口协议上，检查字段名是否拼写一致、类型是否匹配。

我还有一个习惯：把每次技能的输入输出都打印到日志里，用 JSON 格式记录。排查的时候直接按时间倒序看日志，一眼就能定位是模型的问题，还是代码的问题。

7.2 Agent 在编排过程中“乱调”技能

这种情况多见于技能池较大、技能描述不够清晰的时候。Agent 把“查天气”的技能调用来处理“设置提醒”的任务，看起来像脑子不清醒，但实际上是因为两个技能在描述里都提到了“时间”这个关键词，路由层被干扰了。

解决办法是在技能描述里增加“排除性”措辞，明确标注这个技能不处理什么。比如日程技能描述里加上“本技能只负责日程创建，不负责天气查询、不负责消息推送”。实测下来，这个改动对命中准确率的提升很明显。

7.3 Redis 密码修改后重启不生效的完整排查

这个坑我在热词里也看到了，相信不少人遇到过。现象是：改了 Redis 配置文件的requirepass，重启服务后用客户端连接，依然提示NOAUTH Authentication required。

完整排查步骤：

1. 检查配置文件是否真的被 Redis 加载了：redis-cli config get requirepass
2. 如果没有返回新密码，说明加载的不是这个配置文件，检查启动命令里redis-server后面跟的配置路径
3. 检查密码里是否包含空格或特殊字符，如果有，一定要用引号包裹
4. 修改配置后用redis-server /etc/redis/redis.conf显式指定配置文件重启，避免默认配置覆盖

这个流程走完，九成八以上的密码不生效问题都能解决。

8. 我的一些经验体会

整套跑下来，我觉得 Agent 项目真正难的不是选模型，而是把你手上已有的能力都变成能被 Agent 稳定调用的标准技能。腾讯云 AI Skills 给了这套标准化一个不错的落地载体，但工具只是基础，真正的功夫在技能拆分、协议设计、编排逻辑这些看起来不那么“AI”的事情上。

最后再说一个我个人的习惯：每新增一个技能，先写一份一页纸的技能说明，包含用途、入参出参、限制条件、典型调用示例。这份文档既是给 Agent 路由层做标注的依据，也是团队协作时的接口契约。别小看这一步，它能帮你省下大量联调和排查的时间。