腾讯云AI Skills实战：从零构建可部署的Agent系统

1. 项目概述：从一个模糊想法到一套完整 Weapon

说实话，"全能 Agent 养成记"这种标题，我第一次看到时是有点犯嘀咕的。市面上的 Agent 教程要么把概念吹得天花乱坠，要么直接甩给你几段调 API 的示例代码，看完还是不知道怎么落地。但如果你把腾讯云 AI Skills、Agent 架构、部署流程这几块串起来，你会发现这其实是一个相当清晰的工程问题：怎么把大模型的能力拆成可复用的技能包（Skills），再把技能包组织成一个能干活的 Agent，最后部署到云上稳定跑起来。

这篇文章我想从一个实际做过的项目出发，把整个链路拆开揉碎讲清楚：腾讯云 AI Skills 到底解决什么问题，Agent 的架构怎么设计才不翻车，以及我在开发、部署、排错过程中踩过的那些文档里根本不会写的坑。内容会贴近实战，涉及不少代码和配置细节，阅读之前建议你先有一个腾讯云账号，并对 Python 和基础的大模型 API 调用有概念。没有的话也没关系，我会尽量把每个环节的原理和操作意图讲透，你完全可以照着一步步来。

读完之后，你应该具备的能力是：从零设计一个基于 Skills 机制的 Agent 项目，在腾讯云上完成从资源准备、Skill 代码开发、服务发布到 Agent 对接的全过程，并具备基本的排错和性能优化思路。

2. 先搞明白：AI Skills 在 Agent 架构里到底站在哪个位置

2.1 Skill 和 Agent 的关系，别搞混了

很多刚开始接触 Agent 开发的人，会把 Skill（技能）和 Agent 本身混为一谈。我的理解很简单：Agent 是大脑和调度中枢，Skill 是手脚和工具箱。Agent 负责理解用户的意图、制定执行计划、调用合适的 Skill、汇总结果并生成最终回答；而 Skill 则是某个具体能力的封装，它接收结构化的输入，执行一段确定性的逻辑，再返回结构化的结果。

打个比方，Agent 就像一家餐厅的店长，Skill 就是后厨里的各个工位。店长不需要亲自炒菜，但他要知道每个工位能做什么、下单需要什么参数、出餐大概要多久。你问"今天晚餐给我做个西红柿炒蛋"，店长（Agent）会把任务拆解成"找到西红柿和鸡蛋"“清洗食材”“切配”“炒制”几个环节，然后依次调度对应的工位（Skill）去执行。

在腾讯云 AI Skills 的体系里，Skill 的定义其实更偏向服务化：每个 Skill 往往是一个可以独立部署、独立扩展的代码服务，暴露出一组 API 接口供 Agent 调用。这和你在某些开源框架里看到的"给 LLM 写一个函数描述"是两回事，后者更像是 Function Calling 的轻量封装，前者则是一个完整的后端服务单元。

2.2 为什么选择腾讯云 AI Skills 这套方案

我在选型的时候，其实也对比过直接用云函数 + API 网关自己搭、用开源的 Agent 框架（比如 LangChain 生态）自己组装，以及使用腾讯云 AI Skills 这套托管方案。最后选择后者，核心原因有四个。

第一，Skill 生命周期被托管了。从一个 Skill 的创建、版本管理、灰度发布到回滚，平台层面都提供了一致的操作入口，不需要自己在 CI/CD 上折腾太多。对于小团队或者个人开发者来说，这能省下大量运维精力。

第二，它与腾讯云的大模型服务做了深度集成。Skill 可以很方便地调用平台的 LLM 能力，把模型的 API 密钥管理、限流、监控这些基础设施问题交给平台，自己的代码只需要关注业务逻辑。

第三，Agent 编排层和 Skill 层解耦清晰。Skill 只需要保证接口契约稳定，升级某个 Skill 的内部实现不影响 Agent 的整体调度；反过来 Agent 的策略调整也不需要动 Skill 的代码。这种边界感在项目变得复杂之后极其重要。

第四，成本起步低、弹性好。Skill 按实际调用量计费，没有流量的时候几乎不产生费用；流量上来之后平台自动扩容，不用提前备机器。

2.3 一个标准 Agent + Skills 项目的运行链路

在进入实操之前，我先把整个系统的运行链路画在脑子里，这会对后面的代码理解非常有帮助：

1. 用户向 Agent 发起一个自然语言请求。
2. Agent 根据请求内容，结合当前可用的 Skill 列表，进行意图识别和任务规划。
3. Agent 生成一个或多个 Skill 调用计划（包括参数填充），然后通过 HTTP 调用对应 Skill 服务。
4. Skill 服务执行真实的逻辑：可能是查数据库、调外部 API、做计算、甚至再调一次 LLM 来完成子任务。
5. Skill 返回结构化结果给 Agent。
6. Agent 汇总所有结果，生成面向用户的最终回答。

这个链路里，最考验工程设计的是第 2 步和第 3 步：怎么保证 Agent 正确地选择了 Skill，并且填对了参数。这块我在后面"常见问题"部分会专门讲，因为参数幻觉这件事，真的是能用哭你。

3. 环境准备与基础设施搭建

3.1 账号准备与服务开通

在腾讯云上开发 Agent Skills，首先需要完成账号注册和企业或个人实名认证。这里提醒一句，注册过程中如果提示"网络环境异常"，多半是你的出口 IP 被风控了，换一个网络环境或者稍后再试通常就能解决，我个人遇到过几次，不一定是你操作的问题。

登录云控制台之后，依次开通以下服务：

• 云函数 SCF：Skill 服务的主要运行载体。
• API 网关：给 Skill 提供公网访问入口，Agent 通过它来调用 Skill。
• 大模型服务（比如 ChatGLM / DeepSeek 等，视平台可用情况而定）：Agent 的推理底座和 Skill 内部可能用到的 LLM 能力。
• 日志服务 CLS：集中收集 Skill 运行日志，排错必备。
• 对象存储 COS：存放模型输出、临时数据、配置文件等。

如果你要做的 Skill 涉及结构化数据存储，建议再开一个云数据库 MySQL 或者 Redis，按需选择就行。

3.2 本地开发环境配置

我本地的开发环境是 macOS + Python 3.10。代码管理用 Git，依赖管理用 pip 的 requirements.txt，虚拟环境用 venv。在开始写代码之前，建议把以下工具装好：

• Serverless Framework（如果腾讯云提供了对应的 CLI 插件）：可以用配置文件定义云函数和 API 网关的联动，实现一键部署。
• 腾讯云 API 的 Python SDK：直接在 SDK 市场或者 pip 源里装官方包。
• Postman 或者 curl：本地调试 Skill 服务用。
• Docker：有些依赖比较复杂的 Skill 服务，建议先把环境在本地容器里跑通，再打包上传。腾讯云的云函数支持自定义镜像，这样起服务更可控。

这里有一个非常关键的操作习惯：环境变量和密钥严禁硬编码进代码里。腾讯云的云函数控制台提供环境变量配置能力，API 密钥、数据库密码这些都要放到环境变量中读取。我第一次做的时候图省事直接把密钥写死在代码里，结果代码要分享给队友的时候还得先脱敏，非常尴尬，而且一旦代码仓库泄露后果不堪设想。

3.3 理解 Skill 的目录结构和发布单元

一个典型的腾讯云 AI Skills 项目，在代码层面通常长这样：

my_skill/ ├── src/ │ ├── index.py # 云函数入口文件 │ ├── skill.py # Skill 的核心逻辑 │ ├── tools/ # 内部工具函数集 │ ├── prompts/ # 存放提示词模板 │ └── config.py # 配置读取 ├── requirements.txt # 依赖声明 ├── serverless.yaml # 云函数和网关的部署配置 └── README.md

这个结构并不复杂，但它划分出了一个清晰的边界：入口文件负责和平台运行时对接，Skill 文件负责业务逻辑，tools 目录放通用能力，配置单独隔离。这样的好处是，你想把某个 Skill 从一个平台迁到另一个平台时，只需要重写 index.py 这一薄层，核心业务逻辑完全不动。

4. 由浅入深：手把手实现一个能查天气的 Skill

4.1 Skill 的需求拆解和接口契约设计

纸上得来终觉浅，我用一个最常见的场景——"查询城市天气"——来演示整个 Skill 的开发流程。这个 Skill 的输入是一个城市名，输出是该城市当前的气温和天气状况。

在动手写代码之前，我强烈建议先把接口契约定下来。Skill 本质上是给 Agent 调用的，Agent 会根据你的接口描述来决定传什么参数、怎么解析返回值。所以这个契约必须机器可读、语义清晰。我通常的做法是用 JSON Schema 来描述。

{ "name": "weather_query", "description": "根据城市名称查询当前天气情况", "parameters": { "type": "object", "properties": { "city": { "type": "string", "description": "城市名称，例如：北京、上海、广州，如果是省会城市直接用城市名即可" } }, "required": ["city"] } }

这里每个字段都有讲究。name要短而唯一，Agent 靠它来索引 Skill；description要写清楚什么时候该用这个 Skill、参数怎么填，因为 Agent 是拿这段描述做语义匹配的，写得太笼统就容易误调用；description里对参数格式的说明越具体，Agent 填错参数的概率就越低。

4.2 核心代码：Skill 逻辑与云函数入口

天气数据我选择调用一个免费公开的天气 API。Skill 的核心逻辑文件 skill.py 大概是这样的：

import os import requests import json def query_weather(city: str) -> dict: """ 调用第三方天气 API 查询城市天气。 """ api_key = os.environ.get("WEATHER_API_KEY", "") url = f"https://api.weatherapi.com/v1/current.json?key={api_key}&q={city}&lang=zh" try: resp = requests.get(url, timeout=10) resp.raise_for_status() data = resp.json() return { "city": data["location"]["name"], "temperature": data["current"]["temp_c"], "condition": data["current"]["condition"]["text"], "humidity": data["current"]["humidity"], "wind_kph": data["current"]["wind_kph"], "last_updated": data["current"]["last_updated"] } except Exception as e: return {"error": f"天气查询失败: {str(e)}"}

云函数入口文件 index.py 则负责把腾讯云 API 网关传入的 HTTP 请求转换为对 skill.py 的调用，再把结果以标准格式返回：

import json from skill import query_weather def main_handler(event, context): """ 腾讯云 API 网关的 HTTP 触发事件结构里， body 字段是请求体字符串，需要自行反序列化。 """ try: if "body" in event and event["body"]: body = json.loads(event["body"]) else: body = event params = body.get("parameters", body) city = params.get("city", "") if not city: return { "statusCode": 400, "headers": {"Content-Type": "application/json"}, "body": json.dumps({"error": "缺少参数 city"}, ensure_ascii=False) } result = query_weather(city) return { "statusCode": 200, "headers": {"Content-Type": "application/json"}, "body": json.dumps(result, ensure_ascii=False) } except Exception as e: return { "statusCode": 500, "headers": {"Content-Type": "application/json"}, "body": json.dumps({"error": str(e)}, ensure_ascii=False) }

这里有一个细节值得你注意：main_handler里对事件结构做了一个兼容判断。因为 API 网关的 body 可能是字符串，也可能在测试时直接传了一个字典对象，多写这一层判断，能让你本地调试和线上运行的行为保持一致，避免很多"本地好好的，上去就 500"的尴尬。

4.3 部署到腾讯云云函数

部署我采用的是 Serverless Framework 的声明式配置。下面的 serverless.yaml 片段定义了一个云函数和对应的 API 网关触发器：

service: weather-skill-service provider: name: tencent runtime: Python3.6 region: ap-guangzhou environment: variables: WEATHER_API_KEY: ${env.WEATHER_API_KEY} functions: weather-skill: handler: index.main_handler events: - apigw: name: weather-skill-api parameters: serviceName: weather-skill-api serviceId: ${env.API_GATEWAY_SERVICE_ID} apiName: weatherQuery method: POST path: /weather enableCORS: false

部署命令只需要执行sls deploy。平台会自动帮你把依赖打包、上传、创建 API 网关并完成绑定。部署成功后，你会得到一个公网 URL，形如：

https://service-xxxx-xxxx.gz.apigw.tencentcs.com/weather

这个 URL 就是 Agent 调用 Skill 的地址。到这里，一个最简单的 Skill 已经具备雏形了。

4.4 本地调试的技巧

在实际开发中，我不建议每次都部署到云端再调试，这一步耗时太长。我的习惯是本地用 Flask 起一个模拟服务，把 index.py 里的 main_handler 逻辑包一层，直接通过 curl 调用测试。

from flask import Flask, request from index import main_handler import json app = Flask(__name__) @app.route("/weather", methods=["POST"]) def handler(): event = { "body": request.get_data(as_text=True), } result = main_handler(event, None) return result["body"], result["statusCode"], {"Content-Type": "application/json"} if __name__ == "__main__": app.run(port=8000, debug=True)

这样本地请求http://localhost:8000/weather就等同于调用云上服务。等到本地逻辑完全调通，再走一次部署流程，十年少踩一半的坑。

5. 进阶：给 Agent 加上记忆与多 Skill 编排

5.1 为什么只有 Skill 还不够

单一 Skill 只是把你从"手动调 API"升级到了"自动调 API"，距离"全能 Agent"还差得远。一个真正好用的 Agent，至少要解决两个更高维度的问题：跨请求的状态记忆和多 Skill 的协同规划。

先说话记忆。用户上一次问"北京的天气怎么样"，下一次问"那上海呢？"，如果 Agent 不讲上下文，就不会知道"那"指的是一座城市，而是直接把"那"当城市名传给天气 Skill，返回一个报错。所以 Agent 需要一个记忆模块，把对话的关键信息保存下来，在后续任务规划时作为上下文注入。

再说多 Skill 协同。用户说"帮我安排明天下午的会议，如果下雨就改成线上，同时提醒我提前准备资料"。这个请求至少涉及三个 Skill：日程管理、天气查询、任务提醒。Agent 需要制定一个执行顺序：先查天气，再根据天气结果决定日程类型，最后创建提醒。这个过程里，某一个 Skill 的输出会作为另一个 Skill 的输入参数。

5.2 记忆模块的工程实现

记忆可以分成两种：短期工作记忆和长期持久记忆。短期记忆通常就是当前会话的上下文列表，存在内存或 Redis 里，设置过期时间；长期记忆则需要落到数据库，记录用户偏好、历史事实等"值得记住"的信息。

我当前项目的实现比较简单但够用：用 Redis 存会话上下文，用 MySQL 存储用户画像和偏好标记。Agent 在每次收到新请求时，先从 Redis 取回最近 N 轮对话记录，拼接到 Prompt 里；当识别到用户主动给出新偏好时（比如"以后开会都提前十分钟提醒我"），提取这条信息写入 MySQL。

这里要说一个容易踩的坑：不要试图把所有历史对话都塞进 Prompt。一方面大模型的上下文窗口有限，另一方面无关历史信息会显著降低意图识别的准确率，甚至让模型"分心"。我的经验是每个会话最多保留最近 5~8 轮，冗余信息宁可丢。

5.3 多 Skill 编排的两种模式：固定流程 vs 动态规划

多 Skill 编排我尝试过两种思路，各有优劣。

第一种是固定流程编排——代码写死执行顺序。比如"会议安排流程"就是：查天气 → 判断类型 → 创建日程 → 设置提醒。优点是可解释性强、稳定可控，缺点是只对预设好的场景有效，一旦用户请求超出流程范围就直接失败。

第二种是动态规划编排——把当前能用的 Skill 列表和用户请求一起交给大模型，让模型自己决策调用顺序和参数。这种模式灵活度高，但风险也高：模型可能生成了不存在的 Skill 名，或者跳过必要的校验步骤。我在实践中通常会对模型输出的工具调用计划做一层"白名单校验和参数合法性预检"，不合法就拒绝并让模型重新生成。

一个偏稳妥的折中方案是：对高频固定场景用规则流程，对长尾开放场景走动态规划。就像一个经验丰富的老员工，熟活靠肌肉记忆，新活靠临场分析。两种模式在代码上可以封装成统一的 SkillRunner 接口，切换时只影响编排层的一个配置项。

5.4 一个动态编排的伪代码示例

def agent_execute(user_request, available_skills, memory): context = memory.get_recent_context(session_id) plan = llm_plan( user_request=user_request, available_skills=[s.summary() for s in available_skills], context=context ) # plan 形如： # [ # {"skill": "weather_query", "params": {"city": "北京"}}, # {"skill": "schedule_event", "params": {"time": "明天下午", "type": "online"}} # ] results = {} for step in plan: skill = find_skill(step["skill"]) if not skill: return {"error": f"未知 skill: {step['skill']}"} results[step["skill"]] = skill.invoke(step["params"]) final_answer = llm_answer(user_request, results) memory.add_context(session_id, user_request, results) return final_answer

注意这个循环里，每步执行前都对 Skill 名做了存在性校验，这就是前面说的"白名单校验"。另外，把每步的执行结果都存入 results 字典，最终一并交给大模型生成自然语言答案，这个设计比"边执行边让模型说话"要稳定得多。

6. 在腾讯云上把 Agent 跑起来：发布与集成全流程

6.1 Skill 服务的发布与版本管理

写完 Skill 代码之后，部署并不是一次性的动作，后续你一定会改代码。腾讯云云函数的版本管理机制通常包含"发布新版本"和"创建别名"两个核心概念：版本是某个时刻代码与配置的固化快照，别名可以理解成一个可移动的标签，指向任意版本。

我推荐的工作流是：日常迭代都在 $LATEST 版本上进行，用测试事件测通了之后，再发布成一个编号版本（比如 v1、v2），然后把别名"prod"从旧版本切换到新版本。这样线上流量始终走 prod 别名，出了问题只需要把别名切回上一个稳定版本，就完成了秒级回滚。

这个机制特别适合 Skill 这种"可能随时要调整 prompt 或者工具逻辑"的服务。你永远不知道用户的哪句话会触发一个你没见过的边界情况，所以"可秒级回滚"不是锦上添花，而是保命底线。

6.2 Agent 本体与 Skill 的连接配置

Agent 本体在腾讯云上可以是一个独立的云函数、一个容器服务实例，甚至就是一个跑在 CVM 上的 Python 进程。它和 Skill 服务之间通过 API 网关互通。我在设计这层连接时，会在 Agent 的配置中心维护一个 Skill 注册表，形如：

{ "skills": [ { "name": "weather_query", "endpoint": "https://service-xxx.gz.apigw.tencentcs.com/weather", "auth_token": "sk_live_xxxxx", "timeout_ms": 15000 }, { "name": "schedule_event", "endpoint": "https://service-yyy.gz.apigw.tencentcs.com/schedule", "auth_token": "sk_live_yyyyy", "timeout_ms": 30000 } ] }

在实际调用 Skill 时，Agent 需要在这个注册表里查询 endpoint，并携带鉴权 token。这里的 token 建议每个 Skill 单独分配，不要所有 Skill 共用一个。这样某个 Skill 的密钥泄露了，你只需要吊销那一个 token，而不至于把所有服务都暴露出去。

由于 Skill 的 endpoint 通常是公网地址，建议在 API 网关层面开启鉴权能力，同时给 Skill 服务设置一个较小的调用量阈值。防的是误调用或者恶意刷量，而不是什么高深攻击。

6.3 端到端联调要关注什么

整个链路联调时，我最关心的只有三个指标：时延、失败率、参数正确率。

时延方面，每个 Skill 服务的响应时间会因为第三方 API 的波动而起伏，所以 Agent 调用 Skill 时一定要设置超时时间，并做好超时后的降级处理（比如返回"该功能暂时不可用，请稍后再试"）。参数正确率则需要你去看真实对话日志，统计 Agent 生成 Skill 调用参数时，有多少次传错了城市名、传错了时间格式。这类问题通常不是代码 bug，而是 Skill 的 description 写得不够清楚，需要你反复迭代提示词描述。

我有一个习惯：每次联调完，把用户的原话、Agent 的规划结果、Skill 的入参出参，完整地打印成一条结构化日志存到 CLS 里。等到积累了两三百条之后，再去做统计，你会惊讶地发现自己设计时完全没想到的失败场景。

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

7.1 Agent 调用了错误的 Skill

这是我在项目中遇到最多的问题，尤其当注册表里有多个功能相似的 Skill 时。比如有"天气查询"和"空气质量查询"两个 Skill，用户明明问的是"今天北京的空气适合跑步吗"，Agent 却调了天气查询而不是空气质量查询，结果空气质量数据就缺失了。

排查思路：首先确认 Skill 的 description 写得是否足够区分度高。不要把两个 Skill 的描述都写成"查询天气相关信息"，而是要明确写出适用场景差异："当用户询问温度、天气状况时使用；当用户询问空气质量指数、PM2.5 时使用另一个"。其次，可以在 Agent 的提示词中附上一句"选择 Skill 时请优先匹配用户具体需求中最关键的实体词"。如果这样还不行，就考虑拆分或者合并 Skill：要么让一个 Skill 同时返回两类数据，要么干脆去掉功能边界不清晰的那个。

7.2 Skill 返回 200 但 Agent 解析失败

HTTP 状态码 200 只能代表函数运行没抛异常，不代表数据格式是 Agent 想要的。比如我遇到过某次天气 API 在极端天气下返回了一个额外字段，导致我的解析代码 KeyError，函数捕获了异常后返回了一段中文错误信息，HTTP 状态码却是 200。Agent 拿到这段错误信息，误以为是正常结果，就直接交给了大模型生成答案，结果用户看到一段"Error: 天气查询失败"。

从那以后，我的返回值约定里加了一条硬规则：业务失败必须以非 200 状态码返回，或者至少在返回值里加一个 status 字段，让 Agent 能够明确区分"成功但数据有缺失"和"彻底失败"。这个约定在和外部团队协作时尤其重要，因为不是每个人都看过你的返回结构。

7.3 调用第三方 API 时的不稳定与重试策略

调用外部 API（比如天气、股票行情、地图服务）最让人头疼的问题就是不稳定性，网络抖动、限流、接口变更都是家常便饭。我在 Skill 层做了两级容错。

第一级，是代码内的重试机制。对超时和 5xx 类错误做指数退避重试，最多重试 2 次，每次间隔 1 秒、2 秒；对 4xx 类错误不做重试，因为这是调用方的问题，重试也没用。

第二级，是缓存。对天气、新闻这类实时性要求不高的数据，我加了一层 10 分钟级别的缓存，减少外部 API 的压力。实测下来，使用了 Redis 缓存之后，Skill 的平均响应时延从 2.8 秒降到了 400 毫秒左右，成绩非常可观。

7.4 云函数冷启动导致的高延迟

云函数在长时间没有请求后，下一次请求往往会有 1~2 秒的冷启动延迟。如果你的 Agent 对时延敏感（比如语音交互场景），冷启动是致命的。

我的应对措施有两个：一是设置"预置并发"，让平台保持一定数量的实例常驻，牺牲一点成本换实时性；二是把依赖包尽量精简，避免在 import 阶段加载重型库。比如把import pandas这种拖速度的调用，改成只 import 自己真正用到的子模块，冷启动时间能从 3 秒降到 1 秒内。

7.5 安全：如何防止 Skill 被滥用

Skill 暴露公网后，面临着被恶意刷量、撞接口、甚至通过注入恶意 Prompt 来套取内部逻辑的风险。我在安全这块做了四件事：

• 强制携带鉴权 token，且 token 定期轮换，至少每月一次。
• 在 API 网关层配置 IP 黑白名单，只允许 Agent 服务的出口 IP 访问。如果 Agent 和 Skill 同在腾讯云内网，建议直接走内网访问，不经公网。
• 对 Skill 输入做长度和正则校验。比如城市名最长 20 个字，只允许中文和英文字符，防止有人传一段超长字符串把你的 API 打挂。
• 对第三方 API 密钥做隔离。Skill 进程运行时只能读取到自己的密钥，密钥存储放在云上配置中心，不落盘到代码目录。

7.6 常见错误码与应对速查表

8. 从"能用"到"好用"：性能优化与成本控制经验

8.1 请求合并与数据缓存

当 Agent 的一次任务需要连续调用多个 Skill 时，多个 Skill 之间可能存在数据依赖。比如"查北京天气"和"查杭州天气"如果只是两个独立调用，完全可以合并成一个 Skill 接收城市列表参数，一次请求获取多城市数据。我在天气场景里确实这么做了，效果立竿见影：请求次数下降一半，总时延也下降了 40%。

数据缓存可以分层设计。第一层是 Agent 层的内存缓存，第二层是 Redis 缓存，第三层才是真正的第三方 API。命中率高的情况下，外部 API 的调用量能下降 80% 以上，这直接反映在账单上。

8.2 优化 Agent 调用 Skill 的提示词策略

大模型在生成 Skill 调用参数时，有时会自作主张地"帮你补全"缺失信息。比如用户只说"查天气"，模型可能就默认填了"北京"。这个行为在演示时看起来很智能，在真实场景里其实很危险，因为用户想要的可能是别的地方。

我的做法是在提示词里显式声明规则："如果用户没有明确提供参数，请先询问用户，不要自行猜测填充。"同时，在 Skill 的参数 Schema 里，把必填字段标得非常清楚。模型看到这类强约束，通常会表现得更加谨慎。

8.3 成本观测与预算控制

Serverless 架构的好处是用多少付多少，但这也意味着成本非常不可预测。我给自己的项目设了三道保险：第一，在每个 Skill 的 API 网关上设置 QPS 上限；第二，在代码层对第三方 API 做每日调用量统计，超过阈值就告警；第三，每月固定时间查看云账单，把调用趋势和业务动作对应起来。

一个容易被忽略的成本点是大模型的输入 Token 消耗。如果你的 Prompt 里每次都把所有历史记录、系统说明、Skill 描述全部塞进去，Token 消耗会非常可观。我的建议是：系统说明和 Skill 描述尽量精简，历史记录只保留关键摘要而非原文，能用规则解析的信息就不让模型过一遍。

9. 基于真实踩坑经验的四条铁律

把这段项目的经验总结成四条铁律，送给正准备动手的各位。

第一，接口契约先于代码。在写任何 Skill 之前，先把 API 的入参、出参、错误码、鉴权方式这四个要素定义清楚，并且用文档固定下来。没有契约的开发，后面 Agent 接你的 Skill 时只会感受到绝望。

第二，一切自动化，一切可观测。Skill 每一次调用的入参、出参、耗时、错误，都必须留痕。否则出了问题你连从哪儿查都不知道，只能靠猜。

第三，Agent 规划优先做保守设计。没有校验的规划结果就是定时炸弹。每一个 Skill 名、每一个参数、每一个下游调用，都要做合法性校验。宁可在规划阶段多问用户一句，也不要让模型瞎猜出一个无法执行的计划。

第四，做好开箱即用的本地调试环境。本地起服务、本地跑测试集、本地模拟 API 网关事件，这些常被忽视的基础设施，才是你长期开发效率的最大保障。

我在实际做这个项目的过程中，最有价值的一步其实不是写 Agent 本身，而是不断在"用户请求 → Skill 调用"这条链路上发现系统性的薄弱点，再用工程手段去补强。这个过程没有一招鲜的秘籍，唯一能依靠的就是反复地、真实地使用它，让它暴露问题，再逐步修出韧性。希望这篇偏实战的记录，能帮你少绕一些我走过的弯路。