做 Agent 做了两年多我最大的感受是别把 Agent 想成一个大模型聊天框它更像一条需要持续供电的自动化流水线。真正难的不是让模型“说对一句话”而是让模型能够稳定地调用工具、读取状态、执行动作、再根据结果修正下一步。最近我在腾讯云上把一套完整的 Agent 服务跑通了从 AI Skills 的拆分设计、云端部署到多 Skill 编排成真正的全能 Agent踩了不少坑也总结出了一套能直接复用的最佳实践。这篇文章就是这套实践的完整记录适合两类人看一是刚开始做 Agent 开发、不知道怎么组织提示词和工具代码的同学二是已经有 Agent 项目、但感觉结构越来越乱、想引入 AI Skills 这套工程化思路的开发者。1. 什么是 AI Skills它不是提示词仓库而是 Agent 的“肌肉记忆”1.1 从一张“技能卡片”说起如果你把 Agent 想象成一个员工那么大模型是他的大脑上下文是他的短期工作记忆而 AI Skills 就是他掌握的“专业技能包”。举个例子一个刚入职的运维工程师脑子里装着 TCP 协议和 Linux 命令这是模型本身的常识但“你们公司的 Redis 部署在哪个目录、重启要用哪条 systemd 命令、出现故障先看哪个日志”这类信息他不可能天生就知道这就是 Skill 要补上的东西。我第一次接触腾讯云 AI Skills 的时候第一反应是“这不就是配置文件加上回调接口吗”。实际用下来才发现它真正的价值在于把“技能”这个模糊概念变成了有明确输入输出契约的模块。每个 Skill 都有独立的描述信息、参数定义、校验规则和回调地址Agent 在运行时会根据当前请求自动判断该调用哪个 Skill而不是把所有命令都塞进一大段提示词里硬让模型理解。这一点解决了我之前项目中最大的痛点提示词越来越长工具函数散落各处改一个命令可能要把上下文全部翻一遍。Skill 把“该做什么”“怎么做”“返回什么”封装成一个独立单元Agent 只需要知道自己有哪些工具可用以及每个工具的触发条件剩下的执行细节全部交给 Skill 内部处理。1.2 Skill 与 Agent 的分工调度者与执行者要理解 AI Skills 这套架构必须先分清两个角色Agent 是大脑兼调度者Skill 是执行者。这里我用一个生活化的类比你开了一家餐厅你是主厨负责看单子决定先做哪道菜、用什么方法做Skill 就是你厨房里的半成品菜包——红烧肉料包、酸菜鱼料包每个料包都写好了配方、配比和操作顺序。主厨不需要记住每一道菜的全部细节只需要知道哪个料包对应哪道菜、什么时候下锅这就能大大提升出餐效率也降低了出错概率。在技术实现上Agent 会维护一个“可用 Skill 列表”每个条目包含 Skill 的名称、功能摘要、参数模式。当用户请求到达时Agent 根据请求内容做意图识别选择一个或多个 Skill 调用。这里有一个关键点Agent 不能盲目调用 Skill它需要先理解用户请求是否匹配某个 Skill 的触发条件。比如用户的请求是“帮我查一下 Redis 状态”Agent 会匹配到server_ops_assistant这个 Skill 的status动作而如果用户问“今天北京天气怎么样”这个 Skill 的触发条件明显不匹配Agent 就会去找别的 Skill。这里我强烈建议把 Skill 设计成“小而专”不要做一个全能 Skill 把所有操作都塞进去。我的一个早期项目就是把服务器监控、数据库备份、日志分析全部写进一个 Skill结果每次调用的输入参数要多复杂有多复杂模型经常把参数填错。拆成独立 Skill 后每个 Skill 的输入只有两三个字段模型一次就能生成正确参数。2. 腾讯云环境准备从零搭一个可被 Skill 调用的后端2.1 服务器与镜像选择在腾讯云上跑 Agent 服务第一步是准备一台能稳定运行后端进程的服务器。我首选的方案是轻量应用服务器而不是云服务器 CVM原因主要有三点一是轻量应用服务器的价格更低入门配置就能满足中小型 Agent 项目的需求二是它的控制台自带防火墙规则管理开放端口操作比 CVM 的安全组更直观三是预置镜像里直接有 Docker 版省去了手动安装的步骤。配置上我建议至少 2 核 4G系统选择 Ubuntu 22.04 LTS。为什么强调 Ubuntu因为大多数 AI 相关的运行环境比如 Python 3.10、Node.js 18、Docker Compose 这些在 Ubuntu 上的兼容性最好踩坑最少。镜像选择的时候注意看有没有“Docker”字样如果有就直接选带 Docker 的镜像如果没有也没关系后面手动装也很快。新服务器拿到手以后我通常会先做三件事更新系统包、创建非 root 用户、配置 SSH 密钥登录。这一步看似和 Agent 无关但决定了后面所有操作的安全底线。特别是当你的 Agent 要执行服务器命令时如果直接用 root 跑一个参数传错可能就把系统搞挂了。2.2 域名解析与二级域名的正确姿势Agent 服务需要暴露一个可以被外部调用的 HTTPS 地址这就涉及到域名和证书。如果你手头没有域名需要先买一个如果已经有域名关键操作是“怎么申请二级域名”——准确说不是申请而是在 DNS 解析里添加一条记录。我习惯把 Agent 的 Skill 回调地址规划成二级域名比如skills.example.com然后按照不同 Skill 继续划分路径像https://skills.example.com/skills/server_ops、https://skills.example.com/skills/redis_helper。这样做的好处是以后不管加多少 Skill入口域名始终只有一个只需要在 Nginx 里按路径转发到不同后端服务进程即可。域名解析的操作步骤很简单登录腾讯云 DNS 解析控制台选择你的域名添加记录主机记录填skills记录类型选 A 或 CNAME。如果服务器有公网 IP 且不打算频繁更换直接用 A 记录指向服务器公网 IP如果服务器可能迁移建议用 CNAME 指向一个稳定的别名。添加完成后一般几分钟内就能生效可以用dig skills.example.com验证解析是否正常。二级域名配上之后别忘了申请 HTTPS 证书。腾讯云有免费的 SSL 证书可以申请申请后下载 Nginx 格式的证书文件配置到 Nginx 里就行。这一步不能省Agent 回调 Skill 时绝大多数云平台的鉴权机制都要求 HTTPS有些平台如果发现回调地址不是 HTTPS会直接拒绝注册。2.3 安全组策略只开该开的端口关于“腾讯云如何开放所有端口”这个问题我的建议是千万不要这么做。开放所有端口等于把服务器毫无遮拦地暴露在公网扫描之下一个 Redis 没设密码、一个 Docker API 端口没受控服务器就很容易被入侵。正确的姿势是只开放必要的端口。我常用的端口规划大概是这样的端口用途是否公网开放22SSH 管理建议只允许指定 IP80HTTP 流量用于跳转 HTTPS开放443HTTPS 回调开放8080后端服务调试端口不开放或仅内网6379Redis绝不开放公网操作路径分两种如果你是轻量应用服务器在控制台“防火墙”页面添加规则即可如果是 CVM需要到“安全组”里配置入站规则。配置规则时来源建议填0.0.0.0/0只用于 80、443 这类必须公开的端口SSH 端口最好限制为你办公网络的出口 IP这样即使密码泄露别人也无法从其他 IP 连上来。Redis 的 6379 端口我特别强调无论你的 Redis 是否设了密码都尽量不要暴露公网。Agent 服务访问 Redis 时通过内网 IP 或 localhost 访问就够了。如果非要公网访问至少也要设置强密码并且用防火墙把来源限制为 Agent 服务器的 IP。3. 写一个属于自己的 Skill以“服务器运维助手”为例3.1 定义 Skill 描述文件一个 Skill 最核心的组成部分是描述文件它告诉 Agent“我是谁、我能干什么、你需要给我什么参数”。我用一个实际项目中的例子来说明这个 Skill 的功能是服务器基础运维包括检查服务状态、重启服务、查看日志。描述文件我习惯用 YAML 格式因为可读性最好name: server_ops_assistant description: 服务器基础运维助手支持检查服务状态、重启服务、查看服务日志 version: 1.0.0 input: - name: action type: enum enum: [status, restart, logs, health_check] required: true description: 操作类型查询状态、重启服务、查看日志、整体健康检查 - name: service type: string required: false description: 目标服务名如 redis、docker、nginx - name: lines type: integer required: false default: 50 description: 查看日志时返回的行数 output: - name: result type: string description: 执行结果的文本摘要这里有三个设计细节值得反复琢磨。第一description字段要写得足够具体Agent 是靠文字描述来理解这个 Skill 适用场景的。如果你写“处理服务器问题”模型在面对“帮我看一下数据库为什么连不上”时就很犹豫该不该调用这个 Skill但如果你写成“服务器基础运维支持检查 redis、docker、nginx 等常见服务的运行状态并执行重启”模型就能精准匹配。第二action用枚举类型比用自由字符串好一万倍。如果不限定取值模型可能传一个restart_service也可能传一个service_restart你的后端就要处理各种奇怪的变体。限定枚举后模型只能在给定范围内选择后端逻辑就可以写得很干净。第三required和default字段必须精心设计。action是必填项没有它 Skill 根本无法执行service在restart动作下必填在health_check动作下可以空着。如果你的描述文件不支持这么细的校验至少在后端代码里做好参数检查不要让一个错误参数导致整个服务崩溃。3.2 后端回调逻辑从请求验签到结果回传Skill 的后端就是一个普通的 HTTP 服务接收 Agent 平台转发过来的请求执行操作后返回结果。我习惯用 Python Flask 写因为代码量最小、调试最方便。下面是一个简化但完整的回调实现from flask import Flask, request, jsonify import subprocess app Flask(__name__) SKILL_TOKEN your-token-here app.route(/skills/server_ops, methods[POST]) def server_ops(): # 1. 验签 token request.headers.get(X-Skill-Token) if token ! SKILL_TOKEN: return jsonify({error: unauthorized}), 401 # 2. 解析参数 payload request.get_json() action payload.get(action) service payload.get(service, ) lines payload.get(lines, 50) # 3. 执行动作 if action status: if not service: return jsonify({error: service is required}), 400 cmd [systemctl, is-active, service] elif action restart: if not service: return jsonify({error: service is required}), 400 cmd [systemctl, restart, service] elif action logs: if not service: return jsonify({error: service is required}), 400 cmd [journalctl, -u, service, -n, str(lines), --no-pager] elif action health_check: cmd [uptime] else: return jsonify({error: unknown action}), 400 # 4. 执行并返回 try: result subprocess.run(cmd, capture_outputTrue, textTrue, timeout30) return jsonify({result: result.stdout.strip() or result.stderr.strip()}) except subprocess.TimeoutExpired: return jsonify({error: command timeout}), 504 if __name__ __main__: app.run(host0.0.0.0, port8080, debugFalse)这段代码虽然简单但包含了 Skill 回调的四个关键环节验签、参数解析、动作分发、结果回传。验签是很多初学同学最容易忽略的一步——你的服务地址一旦公开任何人都可以伪造请求来调用你的 Skill 执行重启操作这是很危险的。我这里用了一个简单的 header token 做示例生产环境建议用 HMAC 签名或者云平台推荐的密钥交换方式。动作分发那里要注意systemctl restart是特权操作普通用户没有权限执行。所以我实际部署时会给这个服务配置一个专用的 systemd unit用Userroot跑或者在 sudoers 里配好免密权限但这不是说让整个服务裸奔而是要在应用层做好权限校验确保只有经过 Agent 鉴权的请求才能走到执行这一步。3.3 用 Docker 把 Skill 推到腾讯云容器镜像服务Skill 代码写完之后我习惯先用 Docker 本地跑通再打包推到腾讯云容器镜像服务最后在服务器上拉取运行。这样做的最大好处是环境一致本地怎么跑服务器上就怎么跑不会出现“我本地好好的放到服务器上就挂了”的问题。先写一个简单的 DockerfileFROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY app.py . EXPOSE 8080 CMD [python, app.py]本地验证通过后登录腾讯云容器镜像服务。这里有个经常踩的坑腾讯云容器镜像服务的登录用户名不是你的腾讯云账号而是 API 密钥的 SecretId密码是 SecretKey。如果你之前没创建过 API 密钥需要先去控制台创建。登录命令长这样docker login ccr.ccs.tencentcloud.com --username你的API密钥ID --password你的API密钥SecretKey登录成功后给本地镜像打标签并推送docker tag server-ops-skill:latest ccr.ccs.tencentcloud.com/命名空间/镜像仓库:latest docker push ccr.ccs.tencentcloud.com/命名空间/镜像仓库:latest命名空间和镜像仓库需要提前在容器镜像服务控制台创建。推完之后在服务器上拉取并运行docker pull ccr.ccs.tencentcloud.com/命名空间/镜像仓库:latest docker run -d --name server-ops-skill --restartalways -p 127.0.0.1:8080:8080 \ -e SKILL_TOKENyour-token-here \ ccr.ccs.tencentcloud.com/命名空间/镜像仓库:latest注意我把端口绑定到了127.0.0.1:8080而不是0.0.0.0:8080。因为外部的 HTTPS 请求会先经过 Nginx 转发真正到后端服务时走的是本机回环地址这样即使防火墙误开了 8080 端口外部也无法直接访问到 Docker 容器。4. 把 Skill 接入 Agent编排与上下文管理4.1 多 Skill 的注册与路由当你的 Skill 数量多起来以后如何让 Agent 高效地选择正确 Skill 就变成一个很考验设计能力的问题。我第一次接入三个 Skill 时直接在系统提示词里把所有 Skill 的描述和参数格式贴了一遍结果模型经常混淆参数明明该调 Redis Skill 却跑去调日志 Skill。后来我换了一个思路给 Agent 提供的不再是“完整的参数格式”而是一个 Skill 索引。索引里只写 Skill 名称、一句话功能摘要和触发条件示例。比如可用技能列表 1. server_ops_assistant服务器基础运维。触发示例查一下 redis 状态、重启 nginx、查看 docker 日志。 2. redis_helperRedis 专用管理。触发示例查看 Redis 内存使用、修改 Redis 配置、Redis 慢查询分析。 3. log_analyzer日志分析。触发示例分析 nginx 错误日志中的 5xx 分布、统计应用日志中的异常关键词。模型先根据索引判断该用哪个 Skill确认后再向平台发起回调平台会带着完整参数去请求 Skill 后端。这样每个 Skill 的详细参数说明不需要全部塞进提示词Agent 的上下文负担大大减轻准确率也明显提升。这是我在实践中学到的最有价值的一个编排经验给模型的信息不是越多越好而是越准越好。另外Skill 的命名和描述一定要和它实际做的事情高度一致。别起那种花里胡哨的名字什么“万能助手”“超级大脑”模型和你自己都很难判断这个 Skill 什么时候该上场。用“动作式”命名比如restart_service、query_metrics一看就知道是什么场景。4.2 上下文记忆Redis 的正确使用姿势Agent 要成为“全能”光有 Skill 还不行还需要记忆。没有记忆的 Agent 每次对话都像第一次见面一样用户上一句话说“把刚才那个服务重启一下”它就懵了——刚才是哪个服务我推荐用 Redis 做 Agent 的短期记忆存储因为读写快、支持过期时间、数据结构也足够丰富。但 Redis 的使用有一个关键前提它必须和 Agent 服务运行在同一内网环境而且不要暴露公网。之前看到很多同学在腾讯云服务器上安装 Redis默认配置下bind 127.0.0.1protected-mode yes这意味着外网访问不了只有本机能连这其实是安全的好事。但如果你需要让另一台服务器上的 Agent 服务访问 Redis就要把bind改成内网 IP并设置一个强密码。下面是 Redis 作为记忆存储的典型数据设计# 会话上下文key 是 session_idvalue 是 JSON 格式的上下文消息 SET session:{session_id} {last_service:redis,last_action:restart,timestamp:1699999999} EX 1800 # Skill 调用历史用 List 存储 LPUSH skill_history:{session_id} {skill:server_ops_assistant,action:status,ts:1699999999} LTRIM skill_history:{session_id} 0 99设置过期时间很重要不然 Redis 内存会被无限增长的历史记录耗尽。我一般把短期记忆的过期时间设为 30 分钟超过这个时间的会话视为结束新的请求从空白上下文开始。这样既不会把上下文搞得太乱也让用户觉得 Agent 还在“记得”刚才的事。这里再专门说一个点很多同学喜欢把大量的系统提示词、工具描述、历史消息一次性塞给模型导致上下文窗口很快被占满。我的建议是历史消息要经过“压缩”再放回去比如只保留最近 5 轮对话更早的内容用一句摘要代替比如“用户之前请求重启 redis 服务结果成功”。这种压缩策略能让 Agent 在长对话中保持稳定表现。4.3 让 Agent 学会“自我修正”全能 Agent 和普通 Agent 的一个显著区别是普通 Agent 执行失败就直接报错全能 Agent 会根据错误信息调整策略重新尝试。这个“自我修正”能力的设计在腾讯云 AI Skills 的最佳实践中可以这样落地Skill 回传的结果除了最终输出之外还可以附带状态码和错误信息Agent 看到非成功状态后不是简单抛给用户而是分析错误原因调整参数后再次调用同一个 Skill或者切换备用 Skill。举个例子用户在对话中做了两步操作第一步让 Agent 修改 Redis 密码第二步让它重启 Redis。如果第二步重启失败Skill 回传的错误信息是“Failed to restart redis.service: Unit redis.service not found”普通 Agent 就会回答“重启失败错误信息已经返回给你了”而带自我修正的 Agent 会先判断“redis.service 不存在可能服务名不叫 redis叫 redis-server”然后自动调用server_ops_assistant的 status 动作传入serviceredis-server确认服务名后重新发起重启。实现这个逻辑关键是在提示词里给模型一个明确的错误处理策略当 Skill 调用返回 error 状态时先不要直接回复用户按以下顺序处理 1. 判断错误信息中是否包含“not found”“does not exist”等关键词可能是服务名或参数有误尝试修正后重试。 2. 如果错误信息提示权限不足则提示用户需要更高权限不要盲目重试。 3. 连续两次重试仍失败则把完整错误信息返回给用户并给出可能的排查方向。这个策略听起来简单但确实是我试过所有方案里最有效的一种。它本质上是在模型和 Skill 之间加了一层“容错协议”让整个系统不再是“一条路走到黑”而是有回旋余地的。5. 常见问题与排查技巧实录5.1 Agent execution terminated due to error 快速定位这个报错信息很多做 Agent 开发的同学应该都不陌生——Agent execution terminated due to error。它太笼统了几乎不告诉你具体是什么环节出的问题。我整理了一份自己的排查顺序基本能覆盖 90% 的情况。先查回调是否超时。大多数云平台默认的 Skill 回调超时时间在 30 到 60 秒之间如果你的 Skill 后端执行了一个耗时的命令比如journalctl全量日志查询就容易超时。解决办法是给后端加异步化改造先把请求接受下来返回“任务已开始执行”随后通过回调接口回传最终结果。再查返回格式是否符合约定。平台可能要求 Skill 返回固定的 JSON 结构比如{result: ...}如果你的后端多返回了一个字段或者返回了纯文本、HTML平台在解析时就可能报这个错误。我遇到过最离谱的一次是后端某条异常路径返回了 Python 的None结果 JSON 序列化后变成null平台直接不认。最后查模型输出是否被截断。如果 Agent 的上下文很长模型生成调用参数时可能没生成完就被 token 上限截断导致平台收到一个不完整的请求体。这种情况可以通过缩短上下文、压缩历史消息来解决而不是盲目增大 token 上限。5.2 Redis 修改密码后重启一直失败这个问题的典型场景是安装好 Redis 后修改了redis.conf里的requirepass然后重启 Redis结果服务起不来了。在 Agent 项目里如果 Redis 挂了记忆功能就全废整个 Agent 就像失忆了一样所以这个问题值得单独拿出来说。我遇到的常见原因有三个。第一个是 systemd 服务文件里的启动命令没有指定配置文件。默认情况下 Redis 的 systemd unit 可能不会自动读取你修改的那个redis.conf你改了requirepass但服务启动时用的是默认无密码配置可能导致客户端连接时鉴权失败而且重启时语法检查也过不去。排查方法是用systemctl cat redis看 ExecStart 参数确认配置文件路径。第二个原因是密码强度不够。Redis 的requirepass有最小长度限制太短的密码启动时会报错。解决办法是换一个更长的密码一般建议 16 位以上。第三个原因比较隐蔽如果你同时开启了 AOF 持久化旧数据文件里的写入操作如果包含了旧的认证信息会在加载 AOF 时卡住或失败。这种情况下可以先备份 AOF 文件然后临时注释掉requirepass启动确认能起来后再重新设置密码。排查命令的顺序我是这样的systemctl status redis journalctl -u redis -n 50 redis-cli ping redis-cli -a 新密码 ping先看服务状态再看日志最后用客户端测试密码是否生效。这套顺序可以帮你快速判断是配置问题、权限问题还是数据文件问题。5.3 Docker 登录与推送的鉴权问题把 Skill 镜像推到腾讯云容器镜像服务时有两个高频报错。一个是denied: requested access to the resource is denied这通常是命名空间或仓库地址拼错了或者该账号没有这个镜像仓库的写权限。另一个是unauthorized: authentication required这是登录没成功。登录不成功的原因大多数时候不是密码错了而是用户名填错。再次强调腾讯云容器镜像服务的登录用户名是 API 密钥的 SecretId不是你的 QQ 号、手机号或自定义的用户名。如果你看不到密码字段检查一下是不是用了子账号密钥子账号密钥需要有容器镜像服务的操作权限否则即使 SecretId 填对了也会被拒绝。还有一个小坑docker login 的凭证默认存放在本机配置里如果是在服务器上推送镜像要先确认服务器时间是否准确证书校验对时间偏差很敏感时间不对会导致握手失败报certificate signed by unknown authority。跑一下date -u看看时间如果偏差超过两分钟用 NTP 同步一下再重试问题就解决了。6. 这套架构还能往哪里延展6.1 从常驻服务器到函数计算Skill 后端目前是跑在常驻 Docker 容器里的但有一个明显的问题大部分时间这个后端处于空闲状态却在持续消耗服务器资源。如果 Agent 调用量有波动比如白天高、晚上低可以考虑把一些低延迟要求的 Skill 迁到函数计算服务上。函数计算的好处是按调用计费没有流量时基本零成本。不过要注意冷启动问题——函数计算实例从零启动到就绪可能需要几百毫秒到几秒。如果 Agent 平台的回调超时时间很短冷启动超时的风险就很高。我的建议是高频的、需要常驻内存的 Skill比如带模型缓存、长连接池的留在 Docker 里低频的、无状态的纯计算型 Skill比如文本格式化、数据校验适合放函数计算。6.2 给 Skill 加一层可观测性当 Agent 开始调用多个 Skill链路就变长了用户请求→Agent 平台→Skill 后端→Redis→外部命令。一旦出问题排查链路会非常痛苦。我的做法是把每一次 Skill 调用都记录成结构化日志至少包含以下字段请求 ID、Session ID、Skill 名称、动作、参数摘要、耗时、返回状态、错误信息。把这些日志集中发送到腾讯云日志服务再配几个简单的告警规则比如“Skill 调用失败率超过 5%”“平均耗时超过 5 秒”就可以在用户发现问题之前先一步感知异常。这一步看起来增加了工作量但却是 Agent 项目从“demo 能跑”进化到“线上可靠”的关键一环。还有一个经验每次更新 Skill 后端时别急着替换旧版本先在另一个端口起一个 v2 实例用测试会话验证通过后再切流量。因为 Agent 的编排逻辑是模型动态决定的你很难用单元测试覆盖所有调用路径留一个灰度环境会让你在线上出问题时能快速回滚。AI Skills 这套体系目前对我来说最大的收获不是某个具体功能而是逼着我把 Agent 开发从“写提示词”升级到了“设计系统”。提示词只是告诉模型怎么说话Skill 才是真正让 Agent 动手干活的能力单元。在腾讯云上跑完这一整套流程之后我明显感觉自己对 Agent 项目的把控力上了一个台阶——代码结构清晰了问题定位快了团队里新同学接手项目也不需要从零啃那一大坨提示词。如果你也正在做 Agent 项目我建议可以从一个小场景开始先拆一个 Skill 出来跑通回调、部署、编排全链路再逐步扩展成全能 Agent。这个过程的每一步都会有新的认知但每解决一个问题你的 Agent 就会真正“全能”一点点。