去年年中我开始折腾 Agent最初只是拿开源框架跑了个能聊天的 Demo真正让它会干活是最近三个月的事。中间踩了不少坑也把腾讯云上的一套部署链路反复推倒重来了好几轮最后才沉淀出这套全能 Agent的养成方案。今天不聊概念直接把我从云服务器选型、Skills 设计、部署上线到线上调优的完整过程拆开讲适合正在做 Agent 开发、想把原型推到线上稳定运行的开发者参考。先对齐一下认知我理解的AI Skills是给 Agent 预先封装好的一组可复用能力单元——可以是工具调用、知识检索、代码执行也可以是某个业务场景的完整处理流程。它和传统函数库最大的区别在于Skill 是面向大模型的任务描述既要有机器可执行的实现代码也要有模型能理解的自然语言说明。把这层想清楚后面的所有设计才不会跑偏。1. 为什么我坚持用Skills而不是直接堆 Prompt很多刚开始做 Agent 的人喜欢把所有指令塞进系统提示词里让模型自己临场发挥。短期看没问题等技能一多Prompt 会变得臃肿不堪模型的选择准确率直线下降而且每加一个新能力都要改写核心提示词维护成本完全失控。1.1 Agent 与 Skill 的边界谁负责思考谁负责执行我习惯用一句话界定两者Agent 负责判断该做什么Skill 负责解决怎么做到。前者是大脑后者是手脚。举个实际例子。我做过一个 DevOps 辅助 Agent它需要执行运维操作、查日志、分析异常。如果把这些能力全部写进 Prompt模型面对查一下 Nginx 报错这类请求时往往不知道该先调用哪个工具甚至自己编造命令。但拆成独立的 Skills 后Agent 的决策变成了查日志这个 Skill 是否匹配用户意图匹配了就去执行整个链路清晰且可控。从框架层面看当前主流的 Agent 框架无论是 LangChain 还是更底层的自研调度层都支持把 Skill 作为一个独立注册单元挂载到 Agent 上。Skill 内部可以包含工具定义、参数 Schema、执行逻辑甚至嵌套子 Agent。这种高内聚、低耦合的结构是我推荐 Everyone 采用的主因——单测好写、故障好隔离、扩展只需新增目录不用动核心代码。1.2 Skill 与 Agent 的关系从全包到导演制如果把项目比作拍电影Agent 是导演Skill 是演员。导演不需要亲自完成每一个动作但要知道哪个演员擅长什么并在合适的时机发出正确的调度指令。在腾讯云上的实际部署里我通常跑一个 Agent Core 服务再挂上若干 Skill 容器或函数直接用云函数、容器实例做 Skill 载体都很成熟。Agent Core 持有全局会话状态和记忆Skill 无状态化地执行单一任务两者之间通过内部协议通信。这套架构的好处是 Skill 可以独立扩缩容比如日志分析类 Skill 负载高了单独给它加副本就行不会影响对话主链路。顺带一提在我的项目里skill和agent是可以互相转化的。一个复杂的 Skill 内部如果逻辑足够复杂我会直接把它实现为一个子 Agent——它有独立的上下文窗口和决策循环。这不算过度设计当某个技能的步骤超过五步且有分支判断时子 Agent 的鲁棒性明显优于一条龙式函数。2. 腾讯云上搭建 Agent 开发环境的完整链路标题里写了腾讯云 AI Skills 最佳实践环境搭建是第一步。这块我踩过的坑不少尤其是服务器选型和端口配置典型的一步错步步错。2.1 服务器选型与规格推荐别在这上面省钱Agent 服务对资源的要求分两部分Agent Core 本身是轻量级 API 服务2C4G 完全够用但如果你像我一样要在本地跑 Embedding 模型、做 rerank 或者执行代码类 SkillCPU 和内存就要往上提。我的主力配置是腾讯云轻量应用服务器 4C8GSSD 系统盘带宽按量计费。原因有三轻量服务器性价比高4C8G 能覆盖绝大多数 Agent 场景自带的基础监控够用不用额外折腾腾讯云内网连 COS、CLS 等服务延迟极低对 Skill 里常见的文件读写、日志采集非常友好。如果要做大规模并发我建议直接上海量计算或容器服务轻量服务器定位是开发和中小规模生产。但第一台机器没必要一步到位4C8G 起步跑起来看监控再做垂直扩容比一开始就上高配划算得多。2.2 从零到一安装运行时、Docker 与镜像管理我的部署思路是能容器化就容器化。Agent Core、Skill 服务、中间件Redis、PostgreSQL全部用 Docker Compose 编排好处是迁移、回滚、环境一致性都有保障。以我用的腾讯云容器镜像服务TCR为例本地构建好镜像后推送到 TCR 的速度远快于 Docker Hub尤其在晚高峰时段体感差距非常明显。推送命令很简单# 登录 TCR 实例 docker login ccr.ccs.tencentcloud.com -u 账号 -p 密码 # 给镜像打标签 docker tag my-agent-core:latest ccr.ccs.tencentcloud.com/my-project/agent-core:latest # 推送 docker push ccr.ccs.tencentcloud.com/my-project/agent-core:latest这里有个容易被忽略的点镜像标签管理。我吃过亏直接用latest做生产标签结果某次回滚时发现线上跑的是三小时前的旧镜像排查了老半天。后来我所有生产镜像都打上具体的版本号如v1.2.3或 Git commit hashlatest只用于开发环境。这个习惯救了我不止一次。2.3 开发调试链路远程开发与热更新经验在云上开发 Agent我推荐直接用 VS Code Remote-SSH 连接服务器代码同步、断点调试都很顺手。热更新方面Agent Core 用watchdog自动重载Skill 类的 Python 服务用uvicorn --reload。不过热更新只适合开发上了生产环境我一定会把自动重载关掉。原因很简单Agent Core 是有状态的会话、记忆都在内存里进程一重启全部丢失。我线上用的是gunicorn多 worker 模式配合 graceful reload新代码通过滚动发布逐步生效客户端基本无感知。3. Skills 的落地让 Agent 真正学会做事的三个层次环境准备好了重点来了——怎么设计一个真正好用的 Skill 体系。我把它拆成三个层次工具化封装、记忆设计、编排策略。3.1 第一层从 API 到 Skill 的工具化封装一个 Skill 最理想的形态是对模型友好、对开发者简单。它至少要提供三样东西一段自然语言描述告诉模型这个 Skill 是干什么的、什么时候用、有什么注意事项一份参数 Schema明确需要哪些入参、必填还是选填一段可执行代码真正完成这个任务拿我写过的日志排查 Skill举例。它的自然语言描述长这样当日志分析过程中出现关键词ERROR时调用该 Skill 聚合最近 30 分钟的 ERROR 日志并按频率排序输出 Top10若 ERROR 包含Connection refused额外提示检查目标端口连通性。这段描述让模型能准确判断触发时机不至于在用户随口问今天天气时去翻日志。参数 Schema 我用 JSON Schema 定义开发时顺手就把它作为校验层模型传参不规范直接报错重试别让它带病执行。{ name: log_analyzer, parameters: { type: object, properties: { keyword: { type: string, description: 日志关键字 }, time_range: { type: string, description: 时间范围如 30m、1h } }, required: [keyword] } }执行代码就纯粹了接参数、查日志、返回结构化结果。在腾讯云上查日志可以直接调 CLS 的 API几行代码搞定不用自己去服务器翻文件。3.2 第二层记忆机制设计与上下文管理没有记忆的 Agent 像金鱼聊完就忘。记忆这块我踩的坑最多总共分两类短期记忆和长期记忆。短期记忆就是对话轮次里的上下文这个简单把最近 N 轮对话塞进请求即可。但 N 不能无限大——上下文窗口有限塞太满模型容易迷失重点响应延迟也高。我做的是滑动窗口 摘要压缩超过窗口阈值就把前面的历史交给一个总结 Skill压缩成摘要再带着摘要继续对话。实测效果不错既保留了关键信息又控制了 token 开销。长期记忆更复杂要有存储、要有索引、要有检索。我用的方案是把重要信息用户偏好、项目背景、历史决策等写入 PostgreSQL需要时用向量化检索召回。腾讯云的向量数据库目前已经很成熟但我个人小规模场景还是习惯自建 ES 或 pgvector成本更低、可控性更强。这里有一个从实践中总结的经验记忆不是为了记住而记住要在写入时就想好什么信息未来会被检索。我早期什么都往记忆里塞结果检索时噪声一大堆召回质量很差。后来定了个原则只存影响未来决策的信息——比如用户明确说过的偏好、项目约束条件、已经确认过的结论其他闲聊类内容一概不持久化。3.3 第三层多 Skill 编排与任务规划单个 Skill 再强也只是孤岛。真正的全能 Agent价值在于怎么把多个 Skill 串联成一个完整流程。我的做法是引入一个 Planner 模块。收到用户请求后Planner 先拆解意图再决定调用哪些 Skill 以及调用顺序。比如用户说帮我分析这个服务最近一小时为什么变慢Planner 会拆成查监控指标Skill A→ 看异常日志Skill B→ 检查数据库慢查询Skill C→ 汇总原因并给出建议Skill D 或直接让 Core 生成报告。编排有两种实现路径。一种是显式编排我在代码里定义一个工作流哪些 Skill 按什么顺序执行是写死的——适合业务流程非常明确的场景如定期巡检。另一种是隐式编排完全让模型根据用户请求动态决定调用序列——适合开放式问题但稳定性需要调优。我的线上架构是两者结合高频、确定性强的任务用显式工作流其他开放任务走模型动态编排。这也算是我对编排这个热词的一点实践经验。有一点提醒大家动态编排别让模型自由发挥到不可控。我会给 Planner 一个可调用 Skill 的清单和各自约束还会设最大调用次数比如不超过 5 个 Skill防止模型在某些场景下陷入死循环式的连环调用既费 token 又容易出错。4. 线上稳定运行安全配置与故障恢复的实战笔记Agent 跑起来只是第一步线上的稳定性和安全性才是大头。这一章我写的全是自己实际踩过的坑。4.1 腾讯云安全组与端口开放的正确姿势很多新手包括曾经的我在腾讯云上开放端口时很豪放。记得我第一次部署 Agent 服务为了省事直接在安全组里放行了所有端口结果第二天服务器 CPU 飙高一看日志全是扫描和暴力破解尝试。所幸线上没有敏感数据不然后果不堪设想。后来我把安全组的规则收敛成了一套标准模板端口/范围协议来源 IP用途22TCP我的办公网络 IPSSH 管理8080TCP内网 / 负载均衡Agent API 服务5432TCP仅同一 VPC 内网PostgreSQL不暴露公网6379TCP仅同一 VPC 内网Redis不暴露公网所有端口所有协议拒绝兜底规则这套规则的逻辑很简单公网暴露面越小越好中间件服务一概走内网访问。Agent Core 的 API 如果需要被外部调用通过腾讯云的 API 网关或负载均衡转发而不是直接暴露服务器端口。网关层还能顺带做鉴权、限流、日志审计一举多得。4.2 Redis 等中间件的生产环境坑点标题里我有印象看到有人问修改 Redis 密码之后再重启就一直失败的问题。这个问题我不仅遇到过还折腾过很久根因大多出在启动命令或配置文件的优先级上。现象是你改了requirepass然后重启 Redis结果发现新密码不生效或者干脆连不上。最常见的坑有两个。第一用了命令行参数方式改密码但配置文件中没有同步更新重启后命令行参数丢失回到了旧配置第二Redis 以 systemd 服务方式启动ExecStart里带了--requirepass参数这个参数的优先级高于配置文件你在配置文件里改的密码根本没被加载。正确的排查顺序是先确认 Redis 启动方式systemctl status redis还是直接redis-server /etc/redis/redis.conf再确认配置来源ps aux | grep redis看看启动命令里有没有携带参数确认你要改的密码和实际进程用的配置是同一个文件# 修改前先备份 cp /etc/redis/redis.conf /etc/redis/redis.conf.bak # 修改 requirepass 字段 sed -i s/# requirepass foobared/requirepass MyStrongPassword123/ /etc/redis/redis.conf # 重启并验证 systemctl restart redis redis-cli -a MyStrongPassword123 ping验证这一步非常重要改完不验证等于没改。我后来养成了习惯任何中间件配置变更后第一时间做连通性测试而不是改完就完事。4.3 日志监控与预警没有监控的 Agent 就像裸奔Agent 服务相比传统 Web 服务有一个显著差异它的运行路径是动态的输入千变万化模型输出也有随机性。这种不确定性让故障排查变得更难——同样的请求这次成功下次失败可能只是因为模型抽样的温度参数不同。所以日志与监控必须做充分。我在腾讯云上接的是 CLS日志服务所有 Agent Core 和 Skill 的结构化日志都往 CLS 打。关键指标有三类调用指标每次请求的耗时、token 消耗、模型名称、成功/失败状态链路指标用户请求触发了哪些 Skill、每个 Skill 的耗时、是否出现循环调用错误指标模型 API 报错、Skill 执行异常、上下文超长截断等预警规则我设了两条最实用的一是错误率超过 5% 持续 5 分钟二是用户请求触发的平均 Skill 数突然翻倍。这两个指标一旦异常十有八九是上游模型 API 抖动或编排逻辑发生回归。有一次预警半夜响了我爬起来一看原来是某个 Skill 的第三方数据源接口改版返回格式变了导致 Skill 内部解析异常。由于日志里把 Skill 名、报错堆栈都打了出来排查只花了十分钟修复也简单——升级 SDK 版本即可。如果没有日志这种问题可能要到用户投诉才暴露。5. 从能跑到好用性能优化与效果调优的实测记录部署稳定了不等于体验好。用户感知最强烈的两个指标一是响应速度二是回答质量。这一章我记录几条实测有效的调优路径。5.1 Prompt 与上下文优化不要让模型读长篇小说大模型的响应延迟和输入 token 长度强相关。我在优化响应速度时第一个动作永远是压缩上下文。具体做法有三条。第一Skill 描述写精炼只保留触发条件和执行要点不要长篇大论描述太长既占 token 又让模型抓不住重点。第二历史消息做截断和摘要早期对话压缩成摘要而不是全量携带。第三Skill 返回结果只保留必要字段比如日志分析只返回 Top10 的统计结果而不是原始日志全文。有个小技巧我会在每次模型请求前用一段程序逻辑对即将发送的消息做一次token 预估算。如果超出窗口的 70%就先触发历史摘要再发送。这样能有效卡住请求体大小避免塞不下被截断或太长了响应慢。5.2 缓存与并发设计降低重复计算成本Agent 的很多计算是可复用的。比如同一个文档的向量化结果如果文档没变没必要每次重新 Embedding。我引入了两层缓存语义缓存把用户请求做 Embedding在向量库里找相似度超过阈值的旧请求直接返回之前的答案。适合用户反复问类似问题的场景节省一次完整的模型调用。结果缓存对耗时较长的 Skill 结果做短时缓存如 5 分钟比如云资源巡检报告短时间内重复请求直接返回缓存。并发设计上我的 Agent Core 是无状态设计会话状态放 Redis所以可以水平扩展。我把 Core 部署了三个副本前面挂负载均衡实测并发能力翻了接近三倍。但有一点必须提醒无状态 Core 有状态会话Redis这套组合一定要注意 Redis 的持久化配置。如果 Redis 没配 AOF/RDB一旦 Redis 重启所有在线会话全部丢失用户那边表现为聊着聊着就失忆了。这个坑我踩过一次之后把 Redis 的appendonly yes和定期 RDB 快照都打开了会稳妥很多。5.3 效果评估与迭代用真实 Case 驱动改进调优不能靠感觉得有评估体系。我的做法是维护一个回归测试集里面收集真实用户需求和各种边界情况大约一百条左右。每次改动 Skill 的提示词、参数 Schema 或编排逻辑后就用这个测试集跑一遍人工打分对比改动前和改动后的效果差异。这个测试集是我整个项目里最值钱的东西。没有它你会发现每次改动都像是在盲调——今天觉得效果好明天又觉得不对缺乏客观依据。回归测试集我会放在腾讯云 COS 上跑的时候拉取到本地执行版本也纳入 Git 管理。每次改动后对比效果有明确提升才合入主分支。这套流程看着笨重但长期下来能让 Agent 的能力持续正向演进。6. 踩坑实录我会遇到的典型问题盘点既然标题里带了最佳实践我就把从开发到上线这一路踩过的坑集中做个盘点给后来者当路标。每个问题我都标注了根因和解决思路方便检索。6.1 模型乱调用Skill 的问题现象是用户问了一个很简单的问题模型却触发了一连串 Skill 调用甚至把毫不相关的 Skill 也拉进来。根因通常有两个一是 Skill 描述写得模糊模型分辨不了适用边界二是参数 Schema 设计太宽松模型自由发挥的空间太大。解法仔细打磨每个 Skill 的描述明确触发条件和不适用范围参数 Schema 里加description说明每个字段的取值逻辑能枚举就枚举能约束就约束。还有一个技巧给每个 Skill 加一个拒绝条件段当用户意图不符合时模型可以直接选择不调用这比强行调用好得多。6.2 Docker 镜像推送到腾讯云 TCR 时的鉴权问题推送镜像到腾讯云容器镜像服务时偶尔会遇到unauthorized: authentication required。多半是登录态过期或凭据问题。重新执行docker login即可。还有一种情况是镜像命名空间不对。TCR 的仓库路径规则是实例域名/命名空间/镜像名:版本命名空间必须提前建好。我第一次用的时候忘了建命名空间一直报错建完之后马上通了。所以推送前先确认命名空间存在能省去不少排查时间。6.3 Agent 执行中途终止agent execution terminated due to error这个是我在 Agent 开发群里看到有人问过的问题我早期也被它卡过。表现是 Agent 在运行过程中突然停下报terminated due to error之类的错误。根因很多最常见的几个模型 API 返回了异常状态码超时、限流、上下文超长等某个 Skill 执行抛了未捕获的异常Agent 主循环被中断编排逻辑没有做兜底模型在某些输入下返回了不可解析的内容解法分三层第一所有 Skill 的执行入口加统一异常捕获任何异常都返回结构化错误信息而不是直接让异常穿透到 Agent 主循环第二所有模型 API 调用做重试机制指数退避并设置合理的超时时间第三Agent 主循环增加max_iterations限制并且对模型输出做格式校验解析失败就让模型重新生成一次。6.4 修改 Agent 配置后不生效这个问题很像上面提到的 Redis 密码修改失效的场景。可能是配置缓存、环境变量优先级、配置文件路径不一致导致的。统一建议把配置项收敛到一个地方用版本化管理修改后必须验证生效避免改了等于没改。7. 我踩过优先级最高的一个原则先让 Agent窄而深再谈广而全最后分享一个我目前理解最深的体会。我知道现在 Agent 开发者社区有一个趋势就是热衷做全能型 Agent——什么都会一点。但我个人强烈建议一开始只专注做好 1~2 个 Skill让它们足够可靠、足够准确再逐步扩展。原因很简单Agent 的可靠性是建立在每个 Skill 的可靠性之上的。如果一个 Skill 有 30% 的概率出错那五个 Skill 串联的流程整体成功率可能就掉到 20% 以下了——这在生产环境是不可接受的。我第一版全能 Agent就是贪多一个月时间堆了十几个 Skill结果没有一个好用。后来砍到只剩三个核心技能把每个技能的准确率从 60% 打磨到 95% 以上整体体验瞬间上来了。这是我在整个项目里最强的切身感受。在腾讯云上的部署链路也是同理先把一个 Skill 从开发、部署、监控到告警完整跑通形成标准化路径之后再复制到其他 Skill、其他服务上效率会高非常多。所谓最佳实践说到底就是先从一条最小可行的闭环跑出套路再用这套套路去批量复制成功。