从本地开发环境跳到云端把 Agent 真正跑成 7x24 小时的“全能选手”再叠加一套 AI Skills 让模型有能力调用外部工具解决实际问题这里面的坑和思路都值得好好整理一下。这篇内容基于我自己在腾讯云上从零搭建、调试、上线一个完整 Agent 项目的全过程围绕“Agent 云端部署 AI Skills 落地”这条主线展开适合正在做 Agent 项目、准备把原型搬上云、或者研究技能编排的开发者参考。1. 内容整体设计与思路拆解1.1 为什么选择腾讯云作为 Agent 的落地环境先说结论Agent 不是跑不起来而是本地跑和云端跑完全是两码事。本地开发时我用一个 Jupyter Notebook 就能测完一轮 prompt 逻辑但 Agent 一旦需要对外提供接口、定时执行任务、保存长期记忆、被别人访问本地环境就立刻不够看了。我把整个项目放到腾讯云上最直接的原因是三个公网入口稳定可靠。Agent 的核心价值之一是“被调用”无论是通过微信小程序、网页端还是 API 网关都需要一个固定的公网地址。腾讯云的轻量应用服务器自带独立公网 IP绑定安全组之后就能快速暴露服务端口。资源隔离和扩展方便。Agent 跑起来之后要装 Python 依赖、数据库、缓存中间件还要可能挂一个对象存储来存日志和文件。云服务器上可以做相对独立的运行环境不会污染本地开发机。运维链路完整。CloudWatch 类的监控、告警、远程登录、快照备份这些都是生产环境的基本盘。我这次在业务跑稳之后就顺手打了个镜像后面万一系统被我折腾崩了五分钟就能恢复现场。我选择的实例规格是 2核4G 的轻量服务器系统镜像选了 Ubuntu 22.04 LTS。说实话这个配置在跑轻量级 Agent 应用时已经非常宽裕。如果后续接入更重的模型推理或者大规模向量检索再升级到 4核8G 或者单独用 GPU 实例也不迟。关键是先跑通链路不要在初期过度设计。1.2 AI Skills 到底是什么和 Agent 是什么关系先说一个特别容易被混淆的点AI Skills 不是 Prompt 模板也不是简单的“工具函数”。它是把一类特定任务的经验、上下文、工具调用方式和输出规范打包成一个可以被 Agent 自动发现和调用的独立单元。我习惯用一个比喻解释给团队听——Prompt 相当于给厨师一份菜谱Skill 则是把配菜洗好切好、调料按比例配好厨师只需要开火翻炒就行。AI Skills 的价值在于把“怎么做”这件事封装成了标准动作Agent 只需要理解“什么时候用”。在这个项目里我把 Skills 划分成三大类系统观测类检查 CPU、内存、磁盘、网络连接状态、监听端口等适合放在服务器自检场景。数据分析类读取日志文件、统计数据、做关键词聚合适合放在异常排查和业务报表场景。任务执行类调用对象存储上传文件、触发某个外部 API、执行定时清理等适合放在自动化运维场景。这些 Skills 叠加起来之后Agent 从一个只会聊天的对话模型变成了一个能实时掌握服务器状态、能查日志、能发起操作的“带手带脚”的操作系统入口。我用一句很直白的话总结Agent 是大脑AI Skills 是手和脚没有 Skills 的 Agent 只会在原地转圈。2. 腾讯云侧环境准备与基础搭建2.1 云服务器初始化与基础环境配置服务器拿到手别急着装 Agent先把地基搞干净。我这次花了大半天时间把底层的环境梳理完毕后面部署时一次通过基本没遇到依赖打架的情况。第一步是更新系统包这个不用多解释装上 Ubuntu 之后第一件就是这个sudo apt update sudo apt upgrade -y然后安装基础工具链包括 git、curl、vim、ufw 防火墙管理工具以及编译用的 build-essentialsudo apt install -y git curl vim ufw build-essential software-properties-commonPython 环境我直接选了 3.10太老的版本在跑 Agent 框架时会有兼容性问题。Ubuntu 22.04 自带 Python 3.10可以少折腾一步。注意不要动系统自带的 Python 环境用虚拟环境隔离项目依赖sudo apt install -y python3-venv python3-pip mkdir -p /opt/agent-project cd /opt/agent-project python3 -m venv venv source venv/bin/activate这里有个小建议所有项目相关的内容全部放到/opt/agent-project下面不要散落在 root 目录或者/home/ubuntu下面后面做备份和迁移会省很多心。第二步是配置防火墙。腾讯云控制台有安全组服务器内部还有 ufw双保险建议都设置好。我按最小化原则开放了必要端口22 端口SSH 登录用建议改成密钥登录禁用密码登录。80 和 443后面给 Agent 的 Web 入口和回调地址用。8000-8100Agent 内部服务端口具体可以自定义。3306 或 5432如果要用数据库再单独放行且一定要限制来源 IP别对全网络开放。安全组里原则很简单默认拒绝所有入站流量只放行你需要的端口。我见过不少人图省事直接开放全部端口结果服务器被扫描爆破最后重装系统的教训太深刻了。2.2 消息队列与 Redis 的环境准备本来这一步可以跳过但我的 Agent 方案里涉及异步任务和会话状态管理所以还是把 Redis 单独拎出来说。Agent 在运行过程中需要临时存储多轮对话内容、Skill 的执行状态、限流计数器等。Redis 作为高性能的键值数据库非常适合这种场景。安装很简单sudo apt install -y redis-server sudo systemctl enable redis-server sudo systemctl start redis-server装完第一件事就是改配置。默认 Redis 是没有任何密码保护的如果你的服务器公网 IP 被扫描到 6379 端口开放风险极大。打开/etc/redis/redis.conf文件找到requirepass这一行去掉注释并设置一个强度足够的密码requirepass Your_Strong_Password_Here同时把bind 127.0.0.1 -::1的注释状态确认一下默认只允许本机访问即可。改完之后重启 Redissudo systemctl restart redis-server验证一下 Redis 是否正常顺便测试密码认证是否生效redis-cli -a Your_Strong_Password_Here ping如果返回PONG说明一切正常。注意-a参数直接跟密码会出现在命令行记录里生产环境建议用REDISCLI_AUTH环境变量传密码这里为了演示方便就不绕弯了。改完 Redis 密码之后遇到过重启一直不生效的情况这里先卖个关子后面排错章节详细讲。2.3 域名解析与 HTTPS 配置Agent 在对外提供接口服务时如果走 HTTPS 协议需要有一个域名和对应的证书。腾讯云的域名解析服务里可以给服务器绑定一个二级域名比如agent.yourdomain.com然后通过 Nginx 反代到本地的 Agent 服务再把 SSL 证书挂到 Nginx 上。域名解析这一步在控制台的“添加记录”里选择 A 记录类型主机记录填agent记录值填服务器的公网 IPTTL 默认就好几分钟内就能生效。等ping agent.yourdomain.com能解析到服务器 IP 时这个域名就绑好了。接下来安装 Nginxsudo apt install -y nginx然后创建一个反向代理配置。我这里直接写了一个最常见的配置示例server { listen 80; server_name agent.yourdomain.com; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }保存到/etc/nginx/sites-available/agent然后软链到sites-enabled测试 Nginx 配置并重载sudo ln -s /etc/nginx/sites-available/agent /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx之后再用 certbot 申请免费证书sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d agent.yourdomain.com证书签发成功之后certbot 会自动修改 Nginx 配置并启用 HTTPS 跳转。整个过程只需要按照提示填邮箱、同意协议五分钟内就能搞定。有了https://agent.yourdomain.com这个入口之后Agent 服务的调用地址就正式确定下来了。3. AI Skills 的设计与实现细节3.1 Skill 设计的原则与标准结构在设计 Skills 时我踩过不少坑。最开始我把所有功能揉进一个大函数里Agent 根本不知道该在什么场景调用它。后来参考了社区里关于“技能编排”的讨论才总结出一套相对靠谱的设计原则核心就三条单一职责。一个 Skill 只做一件完整的事情。比如“查看系统负载”和“分析访问日志”必须拆成两个不同的 Skill不能混在一起。描述清晰。Skill 的描述字段就是给大模型看的“说明书”必须写清楚这个 Skill 能做什么、输入参数是什么、适用场景是什么。描述写得越精确Agent 匹配到正确 Skill 的概率越高。输出结构化。每个 Skill 的返回结果尽量用 JSON 或者 Markdown 表格这种结构化格式方便 Agent 直接读取并组织成自然语言答案。标准结构参考下面这个模板我一直建议团队所有成员写 Skill 时按这个规范来class BaseSkill: name: str skill_name description: str 该技能的作用和适用场景 parameters: dict { type: object, properties: {}, required: [] } def execute(self, **kwargs): raise NotImplementedError名称用英文小写加下划线描述用中文写清楚场景参数定义遵循 JSON Schema 规范。这样一来无论 Skill 内部用的是 Python 脚本、Shell 命令还是直接调用外部 API对外暴露的接口都是统一规范的。接触到agent skill和skill和agent的区别这两个热词时我意识到很多人还是把“Skill”当成“Agent”的一部分来看。但实际工程上更好的理解是Skill 是一个可复用的能力单元它可以被不同的 Agent 调用也可以独立测试和升级。相当于把“能力”和“使用能力的智能体”解耦了整个系统才能灵活地不断加新技能。3.2 实战写一个服务器健康检查 Skill我先拿“服务器健康速览”这个 Skill 举例代码量不大但非常实用。写完这个之后我对 Agent 如何调度 Skill 的理解深了很多。这个 Skill 的功能是采集 CPU、内存、磁盘、网络 IO 和系统负载信息然后返回一份结构化报告。Python 的psutil库可以很轻松地拿到这些数据。先安装依赖pip install psutil然后定义 Skillimport psutil import json import datetime def server_health_quick_report(): cpu_percent psutil.cpu_percent(interval1) memory psutil.virtual_memory() disk psutil.disk_usage(/) load_avg psutil.getloadavg() boot_time datetime.datetime.fromtimestamp(psutil.boot_time()).strftime(%Y-%m-%d %H:%M:%S) report { timestamp: datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S), cpu_percent: cpu_percent, memory_percent: memory.percent, memory_available_gb: round(memory.available / (1024 ** 3), 2), disk_percent: disk.percent, disk_free_gb: round(disk.free / (1024 ** 3), 2), load_avg_1_5_15: list(load_avg), boot_time: boot_time } return json.dumps(report, ensure_asciiFalse, indent2) if __name__ __main__: print(server_health_quick_report())这个函数用psutil.cpu_percent做了一次间隔为 1 秒的采样拿到的是相对准确的实时 CPU 使用率。内存那块直接用了virtual_memory()磁盘分区用了根目录/的使用情况。如果想监控其他挂载盘改路径就行。这里多返回了 boot_time 和 load_avg是为了让 Agent 有更丰富的上下文去判断服务器是不是刚重启过、负载是否持续偏高。3.3 进阶写一个日志分析 Skill服务器健康检查只是开胃菜实际排查问题的时候最有用的 Skill 是“日志分析”。这个 Skill 接收一个日志文件路径和一组关键词扫描日志内容并统计每个关键词出现的次数同时提取出包含关键词的最新若干行上下文。核心代码不复杂import os import re from collections import Counter def analyze_log(file_path, keywords, tail_lines20): if not os.path.exists(file_path): return {error: f日志文件不存在: {file_path}} keyword_counter Counter() matched_lines [] with open(file_path, r, encodingutf-8, errorsignore) as f: for line in f: for kw in keywords: if re.search(kw, line, re.IGNORECASE): keyword_counter[kw] 1 if len(matched_lines) tail_lines: matched_lines.append(line.strip()) break result { file_path: file_path, keywords: list(keyword_counter.keys()), occurrences: dict(keyword_counter), sample_lines: matched_lines } return json.dumps(result, ensure_asciiFalse, indent2)注意读取日志时用了errorsignore因为日志文件时不时会有非 UTF-8 编码的字符不加这个参数可能会在读到某一行时直接抛异常中断整个函数。这个细节不跑实际日志根本发现不了。调用示例python3 analyze_log.py /var/log/nginx/access.log 5xx error timeout返回的结果会告诉 Agent 每个关键词出现了多少次同时给出最新的匹配样例。Agent 拿到这个结果后可以进一步判断是不是发生了大量 5xx 错误、是不是频繁出现 timeout再给出针对性建议。这套链路走通之后Agent 就不再是“据说服务器有问题”而是“服务器现在有问题这是证据这是可能的原因”。4. 实操过程在腾讯云上把 Agent 和 Skills 跑起来4.1 Agent 主体框架的选择与编排思路在 Agent 框架的选择上我试过几种方案最后选择了一条灵活性比较高的路线FastAPI 做服务入口内部通过 OpenAI Function Calling 机制做模型和 Skill 的对接用 Redis 存会话状态整个流程自己编排。这个选择有几个理由。第一FastAPI 是 Python 生态里最成熟的异步 Web 框架写起来快调试也直观。第二Function Calling 是目前主流大模型都支持的标准化能力可以兼容不同模型厂商的接口只改配置就能切换模型。第三整个编排逻辑放在自己手里排查问题时不受框架黑盒限制。服务的主入口代码如下from fastapi import FastAPI, HTTPException from pydantic import BaseModel import uvicorn app FastAPI(titleAgent Skills API) class ChatRequest(BaseModel): session_id: str message: str class SkillCallRequest(BaseModel): skill_name: str parameters: dict app.get(/health) def health_check(): return {status: ok} app.post(/chat) async def chat(req: ChatRequest): # 调用大模型带上 skills 描述返回模型决策结果 pass app.post(/skills/execute) async def execute_skill(req: SkillCallRequest): # 根据 skill_name 找到并执行对应 skill pass if __name__ __main__: uvicorn.run(app, host0.0.0.0, port8000)这是最基础的骨架。chat接口负责接收用户输入并调用大模型skills/execute是给模型回调用的模型决定调用 Skill 之后由 Agent 服务把 Skill 真正执行起来。分开两个接口的好处是便于日志追踪和安全控制可以在/skills/execute上加独立的鉴权逻辑防止别人直接调你的 Skill。4.2 Skill 注册与 Agent 自动调度实现Skill 注册是整个系统最关键的一环。所有 Skill 的信息会汇总成一个列表每次调用大模型时这个列表都会作为参数传给模型。模型根据用户的提问从列表里选出最合适的 Skill并生成对应的参数然后返回结果。我把 Skill 注册表做成了一个简单的 Python 字典集中管理SKILL_REGISTRY { server_health_quick_report: { description: 获取服务器的CPU、内存、磁盘、负载和启动时间的实时状态适用于查看服务器是否异常或做健康检查。, parameters: { type: object, properties: {}, required: [] } }, analyze_log: { description: 分析指定日志文件中关键词出现的次数并返回最新的匹配日志行适用于排查5xx错误、timeout、异常堆栈等问题。, parameters: { type: object, properties: { file_path: { type: string, description: 日志文件的绝对路径例如 /var/log/nginx/access.log }, keywords: { type: array, items: {type: string}, description: 要搜索的关键词列表例如 [5xx, timeout] } }, required: [file_path, keywords] } } }然后构建模型调用请求时把注册表里的 Skill 描述转换成标准的 tools 格式传给模型def build_tools_from_registry(registry): tools [] for name, meta in registry.items(): tools.append({ type: function, function: { name: name, description: meta[description], parameters: meta[parameters] } }) return tools大模型返回的如果是tool_calls程序会解析出 Skill 名称和参数然后调用真正的执行函数。这里我写了一个分发器def dispatch_skill(skill_name, arguments): if skill_name server_health_quick_report: return server_health_quick_report() elif skill_name analyze_log: return analyze_log(**arguments) else: return {error: f未知的 Skill: {skill_name}}这样一个最简可用的“Agent 自动调度 Skills”闭环就跑通了用户说“帮我看看服务器状态”模型从注册表里选出server_health_quick_reportAgent 执行并返回结果模型再把结果整理成自然语言回复给用户。4.3 用 Nginx 反代和 HTTPS 把 Agent 发布上线代码写完之后要把 FastAPI 服务真正跑在云服务器上并暴露到公网。直接用python run.py的方式在终端里跑服务一旦退出登录进程就挂了根本不适合线上环境。这里我用了systemd来管理 Agent 服务进程。先创建 systemd 服务文件/etc/systemd/system/agent.service[Unit] DescriptionAgent Skills API Server Afternetwork.target redis-server.service [Service] Userubuntu WorkingDirectory/opt/agent-project EnvironmentPATH/opt/agent-project/venv/bin EnvironmentOPENAI_API_KEYsk-your-key ExecStart/opt/agent-project/venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000 Restartalways RestartSec3 [Install] WantedBymulti-user.target注意几个关键点服务绑定的地址是127.0.0.1而不是0.0.0.0这样服务只在本机监听外部流量统一由 Nginx 转发。多一层保护不直接把业务端口暴露到公网。Environment里配置 API Key 等敏感信息不要在代码里写死。如果你用的不是 OpenAI 官方接口而是其他兼容接口还需要把OPENAI_API_BASE一并配好。Restartalways保证进程意外退出后能自动拉起配合云监控的告警基本能做到无人值守。配置好后执行sudo systemctl daemon-reload sudo systemctl enable agent sudo systemctl start agent查看一下运行状态sudo systemctl status agent如果一切正常Nginx 已经配好 HTTPS就可以通过https://agent.yourdomain.com/health在浏览器里访问到{status:ok}了。到这一步Agent 的基础服务已经正式上线。接下来就是不断往 Skill 注册表里加新技能比如把腾讯云对象存储COS的上传功能封装成一个 Skill把定时清理日志做成一个 Skill整个 Agent 的能力就越来越接近“全能”了。4.4 与对象存储能力的结合可选加分项有了公网服务和 Skills 机制后我顺手给 Agent 加了一个对象存储操作 Skill。腾讯云 COS 的 Python SDK 封装得挺清爽安装pip install cos-python-sdk-v5核心代码大概长这样from qcloud_cos import CosConfig from qcloud_cos import CosS3Client secret_id os.getenv(COS_SECRET_ID) secret_key os.getenv(COS_SECRET_KEY) region ap-guangzhou config CosConfig(Regionregion, SecretIdsecret_id, SecretKeysecret_key) client CosS3Client(config) def upload_to_cos(local_path, cos_bucket, cos_key): response client.upload_file( Bucketcos_bucket, LocalFilePathlocal_path, Keycos_key ) return {status: success, cos_key: cos_key, etag: response.get(ETag)}接入之后我可以直接在对话里说“把今天 /var/log/nginx/access.log 上传到 COS 并生成下载链接。”Agent 会依次触发日志分析 Skill 和 COS 上传 Skill完成任务。这种组合型任务正是“Agent AI Skills”架构最擅长处理的场景。5. 常见问题与排查技巧实录5.1 Redis 修改密码后重启失效的问题还记得前面卖关子的 Redis 密码问题吗我修改requirepass之后重启 Redis结果怎么都不生效客户端连接时一直报NOAUTH Authentication required但用新密码又连不上最后发现重启后 Redis 读取的根本不是我改的那份配置文件。检查步骤是这样的先确认 Redis 启动时用的哪个配置文件。用systemctl status redis-server查看进程启动命令或者用ps aux | grep redis看启动参数十有八九会发现问题。我在 Ubuntu 上遇到的情况是 Redis 安装后同时存在/etc/redis/redis.conf和/etc/redis/redis.conf.default启动服务默认读取的是前者。如果启动命令里带了--config /xxx参数则优先读那个路径。修改完配置后除了重启服务还应该验证一下redis-cli -a 新密码 ping返回 PONG 才说明真的生效了。如果配置没问题还是不生效很可能是忘了执行systemctl daemon-reload导致 systemd 还在用旧的服务定义。这个细节容易忽略也最容易折腾人。5.2 Agent 始终匹配不到正确的 Skill这是我在实际使用中碰到的第二个高频问题。模型并没有调用我提供的 Skill而是直接基于自己的知识去回答结果全程都在一本正经地胡说八道。排查下来发现问题出在 Skill 的description描述太模糊。我之前写的描述是“分析日志”模型根本不知道日志路径是什么、要分析什么内容、分析之后能做什么。后来改成“分析指定日志文件中关键词出现的次数并返回最新的匹配日志行适用于排查5xx错误、timeout、异常堆栈等问题”之后命中率大幅提升。总结三条非常实用的调优技巧描述里明确说明 Skill 的“适用场景”。模型很擅长匹配用户意图和场景描述而不是匹配函数名。参数说明要具体。以“日志文件路径”为例如果说“文件的绝对路径例如 /var/log/nginx/access.log”模型就会主动往这个方向带。如果只写“路径”模型可能连该传什么都不清楚。针对同一问题提供多个 Skill 时用描述区分边界。如果一个 Skill 负责“查询服务器监控”另一个负责“查询数据库监控”描述里一定要写清楚“仅适用于应用服务器”“仅适用于数据库节点”避免模型选错。5.3 端口开放了却访问不了服务云服务器上部署服务后经常出现“端口明明在监听但外部就是访问不了”的情况。排查顺序建议是这样先用ss -lntp确认服务是否在监听目标端口。如果确认监听的是127.0.0.1:8000外部访问不了是正常的因为 Nginx 反代还没配好或者 Nginx 挂了。如果监听的是0.0.0.0:8000外部还不通那就跑去看腾讯云控制台安全组的入站规则有没有放通这个端口。有个很容易踩的坑是用了ufw之后明明sudo ufw allow 8000了但因为有旧规则优先匹配流量还是被拦截。检查时用sudo ufw status numbered列出所有规则按顺序检查必要时先删除旧的冲突规则。另外如果是自己用 systemd 启动的服务改完代码后要记得重启服务别在改了代码之后发现线上还是旧逻辑然后开始怀疑网络问题。这个低级错误我也犯过现在都习惯每次改完代码执行一遍sudo systemctl restart agent再说。5.4 依赖库冲突与虚拟环境隔离因为服务器上可能同时跑多个 Python 项目依赖版本不同的情况非常常见。比如一个项目需要pydantic的 1.x 版本另一个项目需要 2.x 版本如果放在同一个环境里必炸无疑。我的建议简单粗暴每个项目都必须使用独立的虚拟环境。开头部署时我就把 Agent 项目放进了/opt/agent-project/venv所有依赖全在这个虚拟环境里安装。systemd 启动服务时ExecStart里也明确指定了虚拟环境里的 uvicorn 路径这样就不会依赖全局 Python 环境。如果用 virtualenv 还是遇到了同类包版本冲突建议把依赖导出后用pip install -r requirements.txt重新装一遍装之前先清掉旧环境rm -rf venv python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt重新装完再启动服务很多奇怪的“运行时异常”都会消失。最后再分享一点个人体会折腾这个项目下来我最大的感受是AI Agent 开发的技术门槛正在肉眼可见地降低真正拉开差距的地方在于“把能力拆成什么粒度、怎么描述能力、怎么做边界控制”。AI Skills 这套思路本质上是在给模型配置一套“可插拔能力”而且是模型自己可以判断“什么时候用哪个能力”。这比硬编码一堆 if-else 要优雅得多也比让模型完全自由发挥稳定得多。如果你正在做自己的 Agent 项目建议第一件事就是把常用的几个操作先封装成标准的 Skill然后让模型去调度试过一轮之后你会回来感谢这个思路的。另外一个很重要的点是务必将安全边界做好。Agent 一旦有了执行能力就必须要有权限控制Skill 里涉及删除、修改、上传等敏感操作的一定要有确认机制或独立的鉴权流程。我自己的 Agent 项目里默认情况下 Skill 只有“读”权限需要写操作时必须走二次确认。这个习惯延续到现在帮我躲过了不少潜在事故。这整套东西跑起来之后后面可以扩展的方向非常多把模型换成更强大的推理模型、给 Skill 增加自动学习能力、把会话记忆从 Redis 换成向量数据库实现长期记忆都是顺手的事情。核心的“Agent Skills”骨架搭对了后续所有迭代都是往上加积木。如果你的 Agent 也打算走到云端或者正在为“模型只会聊天不会干活”发愁希望这篇内容能帮你少踩几个坑。有更好玩的想法欢迎在评论里聊起来。
从本地到云端：AI Agent与AI Skills的落地实践
从本地开发环境跳到云端把 Agent 真正跑成 7x24 小时的“全能选手”再叠加一套 AI Skills 让模型有能力调用外部工具解决实际问题这里面的坑和思路都值得好好整理一下。这篇内容基于我自己在腾讯云上从零搭建、调试、上线一个完整 Agent 项目的全过程围绕“Agent 云端部署 AI Skills 落地”这条主线展开适合正在做 Agent 项目、准备把原型搬上云、或者研究技能编排的开发者参考。1. 内容整体设计与思路拆解1.1 为什么选择腾讯云作为 Agent 的落地环境先说结论Agent 不是跑不起来而是本地跑和云端跑完全是两码事。本地开发时我用一个 Jupyter Notebook 就能测完一轮 prompt 逻辑但 Agent 一旦需要对外提供接口、定时执行任务、保存长期记忆、被别人访问本地环境就立刻不够看了。我把整个项目放到腾讯云上最直接的原因是三个公网入口稳定可靠。Agent 的核心价值之一是“被调用”无论是通过微信小程序、网页端还是 API 网关都需要一个固定的公网地址。腾讯云的轻量应用服务器自带独立公网 IP绑定安全组之后就能快速暴露服务端口。资源隔离和扩展方便。Agent 跑起来之后要装 Python 依赖、数据库、缓存中间件还要可能挂一个对象存储来存日志和文件。云服务器上可以做相对独立的运行环境不会污染本地开发机。运维链路完整。CloudWatch 类的监控、告警、远程登录、快照备份这些都是生产环境的基本盘。我这次在业务跑稳之后就顺手打了个镜像后面万一系统被我折腾崩了五分钟就能恢复现场。我选择的实例规格是 2核4G 的轻量服务器系统镜像选了 Ubuntu 22.04 LTS。说实话这个配置在跑轻量级 Agent 应用时已经非常宽裕。如果后续接入更重的模型推理或者大规模向量检索再升级到 4核8G 或者单独用 GPU 实例也不迟。关键是先跑通链路不要在初期过度设计。1.2 AI Skills 到底是什么和 Agent 是什么关系先说一个特别容易被混淆的点AI Skills 不是 Prompt 模板也不是简单的“工具函数”。它是把一类特定任务的经验、上下文、工具调用方式和输出规范打包成一个可以被 Agent 自动发现和调用的独立单元。我习惯用一个比喻解释给团队听——Prompt 相当于给厨师一份菜谱Skill 则是把配菜洗好切好、调料按比例配好厨师只需要开火翻炒就行。AI Skills 的价值在于把“怎么做”这件事封装成了标准动作Agent 只需要理解“什么时候用”。在这个项目里我把 Skills 划分成三大类系统观测类检查 CPU、内存、磁盘、网络连接状态、监听端口等适合放在服务器自检场景。数据分析类读取日志文件、统计数据、做关键词聚合适合放在异常排查和业务报表场景。任务执行类调用对象存储上传文件、触发某个外部 API、执行定时清理等适合放在自动化运维场景。这些 Skills 叠加起来之后Agent 从一个只会聊天的对话模型变成了一个能实时掌握服务器状态、能查日志、能发起操作的“带手带脚”的操作系统入口。我用一句很直白的话总结Agent 是大脑AI Skills 是手和脚没有 Skills 的 Agent 只会在原地转圈。2. 腾讯云侧环境准备与基础搭建2.1 云服务器初始化与基础环境配置服务器拿到手别急着装 Agent先把地基搞干净。我这次花了大半天时间把底层的环境梳理完毕后面部署时一次通过基本没遇到依赖打架的情况。第一步是更新系统包这个不用多解释装上 Ubuntu 之后第一件就是这个sudo apt update sudo apt upgrade -y然后安装基础工具链包括 git、curl、vim、ufw 防火墙管理工具以及编译用的 build-essentialsudo apt install -y git curl vim ufw build-essential software-properties-commonPython 环境我直接选了 3.10太老的版本在跑 Agent 框架时会有兼容性问题。Ubuntu 22.04 自带 Python 3.10可以少折腾一步。注意不要动系统自带的 Python 环境用虚拟环境隔离项目依赖sudo apt install -y python3-venv python3-pip mkdir -p /opt/agent-project cd /opt/agent-project python3 -m venv venv source venv/bin/activate这里有个小建议所有项目相关的内容全部放到/opt/agent-project下面不要散落在 root 目录或者/home/ubuntu下面后面做备份和迁移会省很多心。第二步是配置防火墙。腾讯云控制台有安全组服务器内部还有 ufw双保险建议都设置好。我按最小化原则开放了必要端口22 端口SSH 登录用建议改成密钥登录禁用密码登录。80 和 443后面给 Agent 的 Web 入口和回调地址用。8000-8100Agent 内部服务端口具体可以自定义。3306 或 5432如果要用数据库再单独放行且一定要限制来源 IP别对全网络开放。安全组里原则很简单默认拒绝所有入站流量只放行你需要的端口。我见过不少人图省事直接开放全部端口结果服务器被扫描爆破最后重装系统的教训太深刻了。2.2 消息队列与 Redis 的环境准备本来这一步可以跳过但我的 Agent 方案里涉及异步任务和会话状态管理所以还是把 Redis 单独拎出来说。Agent 在运行过程中需要临时存储多轮对话内容、Skill 的执行状态、限流计数器等。Redis 作为高性能的键值数据库非常适合这种场景。安装很简单sudo apt install -y redis-server sudo systemctl enable redis-server sudo systemctl start redis-server装完第一件事就是改配置。默认 Redis 是没有任何密码保护的如果你的服务器公网 IP 被扫描到 6379 端口开放风险极大。打开/etc/redis/redis.conf文件找到requirepass这一行去掉注释并设置一个强度足够的密码requirepass Your_Strong_Password_Here同时把bind 127.0.0.1 -::1的注释状态确认一下默认只允许本机访问即可。改完之后重启 Redissudo systemctl restart redis-server验证一下 Redis 是否正常顺便测试密码认证是否生效redis-cli -a Your_Strong_Password_Here ping如果返回PONG说明一切正常。注意-a参数直接跟密码会出现在命令行记录里生产环境建议用REDISCLI_AUTH环境变量传密码这里为了演示方便就不绕弯了。改完 Redis 密码之后遇到过重启一直不生效的情况这里先卖个关子后面排错章节详细讲。2.3 域名解析与 HTTPS 配置Agent 在对外提供接口服务时如果走 HTTPS 协议需要有一个域名和对应的证书。腾讯云的域名解析服务里可以给服务器绑定一个二级域名比如agent.yourdomain.com然后通过 Nginx 反代到本地的 Agent 服务再把 SSL 证书挂到 Nginx 上。域名解析这一步在控制台的“添加记录”里选择 A 记录类型主机记录填agent记录值填服务器的公网 IPTTL 默认就好几分钟内就能生效。等ping agent.yourdomain.com能解析到服务器 IP 时这个域名就绑好了。接下来安装 Nginxsudo apt install -y nginx然后创建一个反向代理配置。我这里直接写了一个最常见的配置示例server { listen 80; server_name agent.yourdomain.com; location / { proxy_pass http://127.0.0.1:8000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; } }保存到/etc/nginx/sites-available/agent然后软链到sites-enabled测试 Nginx 配置并重载sudo ln -s /etc/nginx/sites-available/agent /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx之后再用 certbot 申请免费证书sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d agent.yourdomain.com证书签发成功之后certbot 会自动修改 Nginx 配置并启用 HTTPS 跳转。整个过程只需要按照提示填邮箱、同意协议五分钟内就能搞定。有了https://agent.yourdomain.com这个入口之后Agent 服务的调用地址就正式确定下来了。3. AI Skills 的设计与实现细节3.1 Skill 设计的原则与标准结构在设计 Skills 时我踩过不少坑。最开始我把所有功能揉进一个大函数里Agent 根本不知道该在什么场景调用它。后来参考了社区里关于“技能编排”的讨论才总结出一套相对靠谱的设计原则核心就三条单一职责。一个 Skill 只做一件完整的事情。比如“查看系统负载”和“分析访问日志”必须拆成两个不同的 Skill不能混在一起。描述清晰。Skill 的描述字段就是给大模型看的“说明书”必须写清楚这个 Skill 能做什么、输入参数是什么、适用场景是什么。描述写得越精确Agent 匹配到正确 Skill 的概率越高。输出结构化。每个 Skill 的返回结果尽量用 JSON 或者 Markdown 表格这种结构化格式方便 Agent 直接读取并组织成自然语言答案。标准结构参考下面这个模板我一直建议团队所有成员写 Skill 时按这个规范来class BaseSkill: name: str skill_name description: str 该技能的作用和适用场景 parameters: dict { type: object, properties: {}, required: [] } def execute(self, **kwargs): raise NotImplementedError名称用英文小写加下划线描述用中文写清楚场景参数定义遵循 JSON Schema 规范。这样一来无论 Skill 内部用的是 Python 脚本、Shell 命令还是直接调用外部 API对外暴露的接口都是统一规范的。接触到agent skill和skill和agent的区别这两个热词时我意识到很多人还是把“Skill”当成“Agent”的一部分来看。但实际工程上更好的理解是Skill 是一个可复用的能力单元它可以被不同的 Agent 调用也可以独立测试和升级。相当于把“能力”和“使用能力的智能体”解耦了整个系统才能灵活地不断加新技能。3.2 实战写一个服务器健康检查 Skill我先拿“服务器健康速览”这个 Skill 举例代码量不大但非常实用。写完这个之后我对 Agent 如何调度 Skill 的理解深了很多。这个 Skill 的功能是采集 CPU、内存、磁盘、网络 IO 和系统负载信息然后返回一份结构化报告。Python 的psutil库可以很轻松地拿到这些数据。先安装依赖pip install psutil然后定义 Skillimport psutil import json import datetime def server_health_quick_report(): cpu_percent psutil.cpu_percent(interval1) memory psutil.virtual_memory() disk psutil.disk_usage(/) load_avg psutil.getloadavg() boot_time datetime.datetime.fromtimestamp(psutil.boot_time()).strftime(%Y-%m-%d %H:%M:%S) report { timestamp: datetime.datetime.now().strftime(%Y-%m-%d %H:%M:%S), cpu_percent: cpu_percent, memory_percent: memory.percent, memory_available_gb: round(memory.available / (1024 ** 3), 2), disk_percent: disk.percent, disk_free_gb: round(disk.free / (1024 ** 3), 2), load_avg_1_5_15: list(load_avg), boot_time: boot_time } return json.dumps(report, ensure_asciiFalse, indent2) if __name__ __main__: print(server_health_quick_report())这个函数用psutil.cpu_percent做了一次间隔为 1 秒的采样拿到的是相对准确的实时 CPU 使用率。内存那块直接用了virtual_memory()磁盘分区用了根目录/的使用情况。如果想监控其他挂载盘改路径就行。这里多返回了 boot_time 和 load_avg是为了让 Agent 有更丰富的上下文去判断服务器是不是刚重启过、负载是否持续偏高。3.3 进阶写一个日志分析 Skill服务器健康检查只是开胃菜实际排查问题的时候最有用的 Skill 是“日志分析”。这个 Skill 接收一个日志文件路径和一组关键词扫描日志内容并统计每个关键词出现的次数同时提取出包含关键词的最新若干行上下文。核心代码不复杂import os import re from collections import Counter def analyze_log(file_path, keywords, tail_lines20): if not os.path.exists(file_path): return {error: f日志文件不存在: {file_path}} keyword_counter Counter() matched_lines [] with open(file_path, r, encodingutf-8, errorsignore) as f: for line in f: for kw in keywords: if re.search(kw, line, re.IGNORECASE): keyword_counter[kw] 1 if len(matched_lines) tail_lines: matched_lines.append(line.strip()) break result { file_path: file_path, keywords: list(keyword_counter.keys()), occurrences: dict(keyword_counter), sample_lines: matched_lines } return json.dumps(result, ensure_asciiFalse, indent2)注意读取日志时用了errorsignore因为日志文件时不时会有非 UTF-8 编码的字符不加这个参数可能会在读到某一行时直接抛异常中断整个函数。这个细节不跑实际日志根本发现不了。调用示例python3 analyze_log.py /var/log/nginx/access.log 5xx error timeout返回的结果会告诉 Agent 每个关键词出现了多少次同时给出最新的匹配样例。Agent 拿到这个结果后可以进一步判断是不是发生了大量 5xx 错误、是不是频繁出现 timeout再给出针对性建议。这套链路走通之后Agent 就不再是“据说服务器有问题”而是“服务器现在有问题这是证据这是可能的原因”。4. 实操过程在腾讯云上把 Agent 和 Skills 跑起来4.1 Agent 主体框架的选择与编排思路在 Agent 框架的选择上我试过几种方案最后选择了一条灵活性比较高的路线FastAPI 做服务入口内部通过 OpenAI Function Calling 机制做模型和 Skill 的对接用 Redis 存会话状态整个流程自己编排。这个选择有几个理由。第一FastAPI 是 Python 生态里最成熟的异步 Web 框架写起来快调试也直观。第二Function Calling 是目前主流大模型都支持的标准化能力可以兼容不同模型厂商的接口只改配置就能切换模型。第三整个编排逻辑放在自己手里排查问题时不受框架黑盒限制。服务的主入口代码如下from fastapi import FastAPI, HTTPException from pydantic import BaseModel import uvicorn app FastAPI(titleAgent Skills API) class ChatRequest(BaseModel): session_id: str message: str class SkillCallRequest(BaseModel): skill_name: str parameters: dict app.get(/health) def health_check(): return {status: ok} app.post(/chat) async def chat(req: ChatRequest): # 调用大模型带上 skills 描述返回模型决策结果 pass app.post(/skills/execute) async def execute_skill(req: SkillCallRequest): # 根据 skill_name 找到并执行对应 skill pass if __name__ __main__: uvicorn.run(app, host0.0.0.0, port8000)这是最基础的骨架。chat接口负责接收用户输入并调用大模型skills/execute是给模型回调用的模型决定调用 Skill 之后由 Agent 服务把 Skill 真正执行起来。分开两个接口的好处是便于日志追踪和安全控制可以在/skills/execute上加独立的鉴权逻辑防止别人直接调你的 Skill。4.2 Skill 注册与 Agent 自动调度实现Skill 注册是整个系统最关键的一环。所有 Skill 的信息会汇总成一个列表每次调用大模型时这个列表都会作为参数传给模型。模型根据用户的提问从列表里选出最合适的 Skill并生成对应的参数然后返回结果。我把 Skill 注册表做成了一个简单的 Python 字典集中管理SKILL_REGISTRY { server_health_quick_report: { description: 获取服务器的CPU、内存、磁盘、负载和启动时间的实时状态适用于查看服务器是否异常或做健康检查。, parameters: { type: object, properties: {}, required: [] } }, analyze_log: { description: 分析指定日志文件中关键词出现的次数并返回最新的匹配日志行适用于排查5xx错误、timeout、异常堆栈等问题。, parameters: { type: object, properties: { file_path: { type: string, description: 日志文件的绝对路径例如 /var/log/nginx/access.log }, keywords: { type: array, items: {type: string}, description: 要搜索的关键词列表例如 [5xx, timeout] } }, required: [file_path, keywords] } } }然后构建模型调用请求时把注册表里的 Skill 描述转换成标准的 tools 格式传给模型def build_tools_from_registry(registry): tools [] for name, meta in registry.items(): tools.append({ type: function, function: { name: name, description: meta[description], parameters: meta[parameters] } }) return tools大模型返回的如果是tool_calls程序会解析出 Skill 名称和参数然后调用真正的执行函数。这里我写了一个分发器def dispatch_skill(skill_name, arguments): if skill_name server_health_quick_report: return server_health_quick_report() elif skill_name analyze_log: return analyze_log(**arguments) else: return {error: f未知的 Skill: {skill_name}}这样一个最简可用的“Agent 自动调度 Skills”闭环就跑通了用户说“帮我看看服务器状态”模型从注册表里选出server_health_quick_reportAgent 执行并返回结果模型再把结果整理成自然语言回复给用户。4.3 用 Nginx 反代和 HTTPS 把 Agent 发布上线代码写完之后要把 FastAPI 服务真正跑在云服务器上并暴露到公网。直接用python run.py的方式在终端里跑服务一旦退出登录进程就挂了根本不适合线上环境。这里我用了systemd来管理 Agent 服务进程。先创建 systemd 服务文件/etc/systemd/system/agent.service[Unit] DescriptionAgent Skills API Server Afternetwork.target redis-server.service [Service] Userubuntu WorkingDirectory/opt/agent-project EnvironmentPATH/opt/agent-project/venv/bin EnvironmentOPENAI_API_KEYsk-your-key ExecStart/opt/agent-project/venv/bin/uvicorn main:app --host 127.0.0.1 --port 8000 Restartalways RestartSec3 [Install] WantedBymulti-user.target注意几个关键点服务绑定的地址是127.0.0.1而不是0.0.0.0这样服务只在本机监听外部流量统一由 Nginx 转发。多一层保护不直接把业务端口暴露到公网。Environment里配置 API Key 等敏感信息不要在代码里写死。如果你用的不是 OpenAI 官方接口而是其他兼容接口还需要把OPENAI_API_BASE一并配好。Restartalways保证进程意外退出后能自动拉起配合云监控的告警基本能做到无人值守。配置好后执行sudo systemctl daemon-reload sudo systemctl enable agent sudo systemctl start agent查看一下运行状态sudo systemctl status agent如果一切正常Nginx 已经配好 HTTPS就可以通过https://agent.yourdomain.com/health在浏览器里访问到{status:ok}了。到这一步Agent 的基础服务已经正式上线。接下来就是不断往 Skill 注册表里加新技能比如把腾讯云对象存储COS的上传功能封装成一个 Skill把定时清理日志做成一个 Skill整个 Agent 的能力就越来越接近“全能”了。4.4 与对象存储能力的结合可选加分项有了公网服务和 Skills 机制后我顺手给 Agent 加了一个对象存储操作 Skill。腾讯云 COS 的 Python SDK 封装得挺清爽安装pip install cos-python-sdk-v5核心代码大概长这样from qcloud_cos import CosConfig from qcloud_cos import CosS3Client secret_id os.getenv(COS_SECRET_ID) secret_key os.getenv(COS_SECRET_KEY) region ap-guangzhou config CosConfig(Regionregion, SecretIdsecret_id, SecretKeysecret_key) client CosS3Client(config) def upload_to_cos(local_path, cos_bucket, cos_key): response client.upload_file( Bucketcos_bucket, LocalFilePathlocal_path, Keycos_key ) return {status: success, cos_key: cos_key, etag: response.get(ETag)}接入之后我可以直接在对话里说“把今天 /var/log/nginx/access.log 上传到 COS 并生成下载链接。”Agent 会依次触发日志分析 Skill 和 COS 上传 Skill完成任务。这种组合型任务正是“Agent AI Skills”架构最擅长处理的场景。5. 常见问题与排查技巧实录5.1 Redis 修改密码后重启失效的问题还记得前面卖关子的 Redis 密码问题吗我修改requirepass之后重启 Redis结果怎么都不生效客户端连接时一直报NOAUTH Authentication required但用新密码又连不上最后发现重启后 Redis 读取的根本不是我改的那份配置文件。检查步骤是这样的先确认 Redis 启动时用的哪个配置文件。用systemctl status redis-server查看进程启动命令或者用ps aux | grep redis看启动参数十有八九会发现问题。我在 Ubuntu 上遇到的情况是 Redis 安装后同时存在/etc/redis/redis.conf和/etc/redis/redis.conf.default启动服务默认读取的是前者。如果启动命令里带了--config /xxx参数则优先读那个路径。修改完配置后除了重启服务还应该验证一下redis-cli -a 新密码 ping返回 PONG 才说明真的生效了。如果配置没问题还是不生效很可能是忘了执行systemctl daemon-reload导致 systemd 还在用旧的服务定义。这个细节容易忽略也最容易折腾人。5.2 Agent 始终匹配不到正确的 Skill这是我在实际使用中碰到的第二个高频问题。模型并没有调用我提供的 Skill而是直接基于自己的知识去回答结果全程都在一本正经地胡说八道。排查下来发现问题出在 Skill 的description描述太模糊。我之前写的描述是“分析日志”模型根本不知道日志路径是什么、要分析什么内容、分析之后能做什么。后来改成“分析指定日志文件中关键词出现的次数并返回最新的匹配日志行适用于排查5xx错误、timeout、异常堆栈等问题”之后命中率大幅提升。总结三条非常实用的调优技巧描述里明确说明 Skill 的“适用场景”。模型很擅长匹配用户意图和场景描述而不是匹配函数名。参数说明要具体。以“日志文件路径”为例如果说“文件的绝对路径例如 /var/log/nginx/access.log”模型就会主动往这个方向带。如果只写“路径”模型可能连该传什么都不清楚。针对同一问题提供多个 Skill 时用描述区分边界。如果一个 Skill 负责“查询服务器监控”另一个负责“查询数据库监控”描述里一定要写清楚“仅适用于应用服务器”“仅适用于数据库节点”避免模型选错。5.3 端口开放了却访问不了服务云服务器上部署服务后经常出现“端口明明在监听但外部就是访问不了”的情况。排查顺序建议是这样先用ss -lntp确认服务是否在监听目标端口。如果确认监听的是127.0.0.1:8000外部访问不了是正常的因为 Nginx 反代还没配好或者 Nginx 挂了。如果监听的是0.0.0.0:8000外部还不通那就跑去看腾讯云控制台安全组的入站规则有没有放通这个端口。有个很容易踩的坑是用了ufw之后明明sudo ufw allow 8000了但因为有旧规则优先匹配流量还是被拦截。检查时用sudo ufw status numbered列出所有规则按顺序检查必要时先删除旧的冲突规则。另外如果是自己用 systemd 启动的服务改完代码后要记得重启服务别在改了代码之后发现线上还是旧逻辑然后开始怀疑网络问题。这个低级错误我也犯过现在都习惯每次改完代码执行一遍sudo systemctl restart agent再说。5.4 依赖库冲突与虚拟环境隔离因为服务器上可能同时跑多个 Python 项目依赖版本不同的情况非常常见。比如一个项目需要pydantic的 1.x 版本另一个项目需要 2.x 版本如果放在同一个环境里必炸无疑。我的建议简单粗暴每个项目都必须使用独立的虚拟环境。开头部署时我就把 Agent 项目放进了/opt/agent-project/venv所有依赖全在这个虚拟环境里安装。systemd 启动服务时ExecStart里也明确指定了虚拟环境里的 uvicorn 路径这样就不会依赖全局 Python 环境。如果用 virtualenv 还是遇到了同类包版本冲突建议把依赖导出后用pip install -r requirements.txt重新装一遍装之前先清掉旧环境rm -rf venv python3 -m venv venv source venv/bin/activate pip install --upgrade pip pip install -r requirements.txt重新装完再启动服务很多奇怪的“运行时异常”都会消失。最后再分享一点个人体会折腾这个项目下来我最大的感受是AI Agent 开发的技术门槛正在肉眼可见地降低真正拉开差距的地方在于“把能力拆成什么粒度、怎么描述能力、怎么做边界控制”。AI Skills 这套思路本质上是在给模型配置一套“可插拔能力”而且是模型自己可以判断“什么时候用哪个能力”。这比硬编码一堆 if-else 要优雅得多也比让模型完全自由发挥稳定得多。如果你正在做自己的 Agent 项目建议第一件事就是把常用的几个操作先封装成标准的 Skill然后让模型去调度试过一轮之后你会回来感谢这个思路的。另外一个很重要的点是务必将安全边界做好。Agent 一旦有了执行能力就必须要有权限控制Skill 里涉及删除、修改、上传等敏感操作的一定要有确认机制或独立的鉴权流程。我自己的 Agent 项目里默认情况下 Skill 只有“读”权限需要写操作时必须走二次确认。这个习惯延续到现在帮我躲过了不少潜在事故。这整套东西跑起来之后后面可以扩展的方向非常多把模型换成更强大的推理模型、给 Skill 增加自动学习能力、把会话记忆从 Redis 换成向量数据库实现长期记忆都是顺手的事情。核心的“Agent Skills”骨架搭对了后续所有迭代都是往上加积木。如果你的 Agent 也打算走到云端或者正在为“模型只会聊天不会干活”发愁希望这篇内容能帮你少踩几个坑。有更好玩的想法欢迎在评论里聊起来。