Agent+AI Skills实战：左手右手腾讯云，从架构设计到部署踩坑全记录

做 Agent 这几年我最大的感受是模型选型往往不是瓶颈真正拖垮项目的是“Agent 之外的工程细节”。比如怎么让 Agent 真正调用你手上的云资源怎么把重复的运维、代码检查、日志分析沉淀成可复用的能力腾讯云 AI Skills 这套组合恰好能解决这些问题。这篇文章我围绕“让 Agent 真正变全能”这条主线把完整的实践路径拆开讲清楚从概念设计、架构选型到在腾讯云上部署、写 Skill、蹚坑排查全程给可直接抄作业的方案。不管你是刚入门的 Agent 学习者还是已经在做 AI 应用开发的工程师只要手头有云服务器、想让你自己的 Agent 具备调用外部工具的能力这篇文章都值得花十分钟看完。1. 先搞清楚Agent 和 AI Skills 到底是什么关系1.1 Skill 是 Agent 的能力单元现在聊到 AI Agent很多人第一反应是 LangChain、AutoGPT 这类框架但核心概念其实很简单Agent 大模型 规划能力 工具执行能力。大模型负责“想”但光想没用得有人替它“做”。这个“做”的动作目前在社区里最通用的组织方式就是 Skill。Skill 是什么狭义讲它是一个结构化的技能包一段给模型看的能力说明、一组执行动作、必要的脚本或 API 调用逻辑。广义讲它是你希望 Agent 掌握的某项“专项技能”的完整封装。比如“查询腾讯云服务器列表”可以做成一个 Skill“对最近提交做代码审查”也可以做成一个 Skill。Skill 解决的核心问题是让 Agent 的能力能被注册、被检索、被复用而不是每一次都靠模型现场瞎猜。我自己维护的 Agent 项目里最初所有工具调用逻辑都写在提示词里模型经常不知道该调用哪个函数。后来把所有能力改造成 Skill 结构每个 Skill 都有清晰的触发描述和执行脚本模型选工具的准确率肉眼可见地提升了。1.2 Skill 和 Agent 到底有什么区别很多朋友问Agent 不是已经可以做任务了吗为什么还要多此一举搞个 Skill我用一个生活化的例子说明。把 Agent 想象成一家公司的“万能员工”它聪明、执行力强但它刚入职什么工具都不会用也不知道你们公司的流程。Skill 就是贴在员工手边的“标准化作业指导卡”顾客投诉了怎么处理、服务器报警了先看哪个指标、代码合并前要做哪些检查。员工接到任务后先翻卡片再按卡片上的步骤干活。也就是说Agent 是“执行主体”Skill 是“执行方法论”。换个角度理解区别Agent 负责拆解任务、制定计划、决定调用什么能力它像大脑。Skill 负责把某个具体能力做扎实它像可更换的工具包。一个 Agent 可以同时挂载几十个 SkillSkill 越多Agent 能处理的场景越广也就越接近“全能”。1.3 为什么这套实践要围绕腾讯云展开选择腾讯云不是因为“大厂云更高级”而是从 Agent 落地的实际诉求反推出来的。一个真正能用的 Agent总要跑在一个 7x24 小时在线的环境里。个人电脑随时关机本地跑模型不方便给外部提供服务所以一台云主机基本是标配。我选择腾讯云的原因很具体轻量应用服务器便宜、镜像市场里有现成的 Ubuntu 环境、安全组规则和 API 密钥体系成熟而且腾讯云的 SDK 覆盖了计算、存储、数据库、域名解析等几乎所有云产品这对 Agent 调用云上资源极为友好。而且腾讯云有一个天然优势Agent 要变强就必须连接真实世界而云服务器本身就是用户最常见的一批“真实资源”。让 Agent 学会调用腾讯云 API 去查实例、拉日志、改解析比单纯让它聊聊天有用得多。2. 设计一个能落地的 Agent Skills 架构2.1 直接从单体框架起步的教训我最早做 Agent 时动辄上重型编排框架项目结构庞大、概念一大堆最后连自己都搞不清楚数据流走到哪一步了。后来踩了坑才明白个人项目首先追求的是低成本跑通而不是架构上的“政治正确”。现在推荐大家使用的架构是“单 Agent 多 Skill”模式。一个大模型作为统一的推理入口接收用户请求自主决定使用哪个 Skill每个 Skill 是一个独立的目录互不干扰。这个架构的特点是简单直接、调试方便特别适合个人开发者和中小团队。整个系统运行在腾讯云的一台 Linux 云主机上由四部分组成模型接入层负责连接可直连的模型服务作为 Agent 的推理引擎Agent 核心负责理解用户意图、规划步骤、选择并调用 SkillSkill 注册表一个固定目录存放所有已安装的 SkillAgent 启动时自动扫描外部环境包括云账号 API、服务器自身、外部服务等。这套架构用成熟之后再考虑引入多 Agent 协作、任务队列、复杂记忆机制这些进阶能力。初期如果直接铺开大概率会陷入调试泥潭。2.2 Skill 的文件结构怎么组织写 Skill 之前先选好文件结构。目前社区里比较通行的做法是“一个 Skill 一个目录”目录下必须有主描述文件可选放脚本、参考文档等比如下方的结构skills/ ├── list_cvm_instances/ │ ├── SKILL.md │ └── scripts/ │ └── list_instances.py ├── check_disk_usage/ │ ├── SKILL.md │ └── scripts/ │ └── disk_usage.py └── review_code/ ├── SKILL.md └── scripts/ └── review.shSKILL.md 是技能包的说明书前端必须有 YAML 格式的元信息后面是正文指令。元信息里最核心的字段是 name 和 descriptionAgent 在选择技能时主要靠 description 的语义相关度做判断所以这一段不能敷衍。2.3 设计一份高质量 SKILL.md我打磨了很多版 SKILL.md 之后总结出一个可靠模板。以下面这个“查询腾讯云 CVM 实例”的 Skill 为例--- name: list_cvm_instances description: 查询腾讯云 CVM 实例列表及其运行状态。当用户提到“看看我的服务器”“实例是不是挂了”“帮我巡检一遍所有 CVM”时使用。 --- 当用户需要查看腾讯云服务器实例状态时按以下步骤操作 1. 执行 python3 scripts/list_instances.py。 2. 脚本会输出 JSON 格式的实例信息包含实例ID、名称、地域、状态、公网IP、规格。 3. 将 JSON 内容整理为易读的表格展示给用户。 4. 如果某个实例状态不是“RUNNING”在回复中明确标红提醒。 注意 - 脚本从环境变量读取 TENCENTCLOUD_SECRET_ID 和 TENCENTCLOUD_SECRET_KEY。 - 如果调用失败先检查环境变量是否配置不要重复执行脚本超过三次。这份 SKILL.md 是合格的description 给出了具体触发场景模型能准确匹配用户需求正文步骤写得足够细模型照着做就能完成闭环标注了失败兜底路径避免模型陷入死循环。记住SKILL.md 不是写给程序员看的注释而是写给“另一个模型”看的操作指南。语言要准确、步骤要明确、边界要清晰。3. 在腾讯云上从零部署一套 Agent3.1 服务器选型与安全组配置腾讯云上先准备一台云主机。个人项目选轻量应用服务器就够了我实测 2核4G 的配置跑一个 Agent 进程加上几个 Skill 脚本毫无压力经济实惠。系统镜像选择 Ubuntu 22.04软件生态好Python 环境也干净。购买时重点关注安全组。很多新手一上来为了省事把“所有端口”全放开了这是极大的安全隐患而且大概率被扫描爆破。我的安全组规则长这样方向协议端口来源IP用途备注入站TCP:22我的办公IP/32SSH登录不推荐对全互联网开放入站TCP:800.0.0.0/0HTTP转发供 Webhook 或 API 使用入站TCP:4430.0.0.0/0HTTPS转发供 Webhook 或 API 使用入站TCP:80800.0.0.0/0Agent 调试端口正式环境建议内网访问上面“开放所有端口”的操作我强烈不建议做。安全组遵循最小授权原则只放行业务必需的端口系统防火墙也开启并保持默认策略。Agent 是一个长期运行的服务被攻击的代价远高于你花两分钟配置规则的代价。3.2 初始化环境与配置模型接入服务器拿到手后不建议直接用 root 跑业务。我一般新建一个普通用户用最小权限运行 Agent 服务。初始化命令贴在下方adduser deploy usermod -aG sudo deploy su - deploy mkdir -p ~/agent/{skills,logs,scripts}然后安装 Python 环境和依赖。推荐用 uv 管理 Python 包比 pip 快得多处理依赖关系也更省心curl -LsSf https://astral.sh/uv/install.sh | sh source $HOME/.local/bin/env cd ~/agent uv venv .venv source .venv/bin/activate uv pip install tencentcloud-sdk-python openai python-dotenv模型接入这一环很容易出现网络问题。如果云主机选在国内地域访问境外模型服务时经常出现连接超时或延迟抖动这基本属于网络可达性问题不是代码 bug。我的实践结论是既然服务已经部署在腾讯云上模型服务也优先选国内可直连的供应商例如腾讯云本身提供的模型服务或者国内有合规接入点的第三方模型这样网络延迟和稳定性都有保障。比较保险的选型路径是先在云主机上用 curl 测试目标模型 API 的连通性再决定是否集成。模型密钥不要写死在代码里统一放在 ~/agent/.env 中MODEL_API_KEYyour_model_api_key_here MODEL_BASE_URLhttps://api.your-provider.com/v1 TENCENTCLOUD_SECRET_IDyour_secret_id_here TENCENTCLOUD_SECRET_KEYyour_secret_key_here腾讯云的 SecretId 和 SecretKey 在访问云 API 时用强烈建议不要直接使用主账号密钥去访问管理控制台创建一个只具备 CVM 只读权限的子账号把子账号的密钥配到环境变量里即使泄露也能把损失控制住。3.3 把 Agent 进程做成系统服务Agent 进程如果只是用 nohup 启动一旦机器重启就全忘了。正确的做法是交给 systemd 管理让它在后台常驻、崩溃后自动拉起。我写了一个 service 单元文件放在 /etc/systemd/system/agent.service[Unit] DescriptionMy AI Agent Service Afternetwork-online.target Wantsnetwork-online.target [Service] Userdeploy WorkingDirectory/home/deploy/agent EnvironmentFile/home/deploy/agent/.env ExecStart/home/deploy/agent/.venv/bin/python main.py Restartalways RestartSec10 [Install] WantedBymulti-user.target启动命令如下sudo systemctl daemon-reload sudo systemctl enable agent sudo systemctl start agent sudo systemctl status agent用 systemd 托管之后日志查看非常方便journalctl -u agent -fAgent 进程有任何输出都能实时看到排查问题省下大量时间。以前我用 nohup日志散落各处出问题连个线索都找不到换了 systemd 之后这个痛点彻底解决。3.4 给 Agent 一个稳定的对外入口Agent 如果想要提供对外服务比如接收 Webhook 或者给它套一个类 OpenAI 的 API需要暴露 HTTP 服务。首先要解决域名绑定和备案问题。腾讯云的控制台里有完整的备案指引流程不算复杂按官方指引提交资料即可大概一两周能下来。备案通过后在 DNS 解析控制台添加一条 A 记录把二级域名解析到云服务器公网 IP。这里推荐用 Nginx 做反向代理终止 TLS 并转发到本地服务端口。一个最小配置示例server { listen 443 ssl http2; server_name agent.example.com; ssl_certificate /etc/nginx/ssl/fullchain.pem; ssl_certificate_key /etc/nginx/ssl/privkey.pem; location / { proxy_pass http://127.0.0.1:8080; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; } }如果不想维护 Nginx 和证书也可以考虑腾讯云 API 网关。把 Agent 服务注册为后端API 网关会提供默认的公网调用地址省去自己管证书的麻烦。这个方法适合快速 Demo生产环境我仍然建议走自定义域名。4. 把云资源变成 Agent 的“全能”技能4.1 第一个腾讯云 Skill查服务器状态前面已经给了 SKILL.md 的内容现在把配套的 Python 脚本写完。这个脚本调用腾讯云 CVM 的 SDK查询当前账号下所有实例的状态。腾讯云 Python SDK 的调用逻辑比较固定先声明凭证再构造 client最后发起请求。脚本代码如下#!/usr/bin/env python3 查询腾讯云 CVM 实例列表 import json import os from tencentcloud.common import credential from tencentcloud.common.profile.client_profile import ClientProfile from tencentcloud.common.profile.http_profile import HttpProfile from tencentcloud.cvm.v20170312 import cvm_client, models REGION os.environ.get(TENCENTCLOUD_REGION, ap-guangzhou) def list_instances(): cred credential.Credential( os.environ.get(TENCENTCLOUD_SECRET_ID, ), os.environ.get(TENCENTCLOUD_SECRET_KEY, ), ) http_profile HttpProfile(endpointcvm.tencentcloudapi.com) client_profile ClientProfile(httpProfilehttp_profile) client cvm_client.CvmClient(cred, REGION, client_profile) req models.DescribeInstancesRequest() resp client.DescribeInstances(req) instances [] for item in json.loads(resp.to_json_string()).get(InstanceSet, []): instances.append({ instance_id: item.get(InstanceId), name: item.get(InstanceName), zone: item.get(Placement, {}).get(Zone), status: item.get(InstanceState), public_ip: item.get(PublicIpAddresses, []), instance_type: item.get(InstanceType), }) return instances if __name__ __main__: result list_instances() for instance in result: print(json.dumps(instance, ensure_asciiFalse))把上面这个脚本保存到 skills/list_cvm_instances/scripts/list_instances.py记得加执行权限。测试一下能否跑通chmod x skills/list_cvm_instances/scripts/list_instances.py python3 skills/list_cvm_instances/scripts/list_instances.py脚本如果能正常输出 JSON 数组说明腾讯云 API 链路已经打通。这时候让 Agent 加载这个 Skill再问一句“帮我看下我有哪些服务器”Agent 就会自动执行脚本并整理回答。我实测下来SDK 默认输出的 JSON 结构对模型不友好字段层级深、命名复杂所以脚本里统一转换成了扁平化的字典列表模型拿到后一眼就能看懂。这个转换逻辑是所有云 API 类 Skill 的通用套路把复杂 API 响应加工成简单结构再交给模型。4.2 再从运维场景扩展两个高质量 Skill人一旦体会过“Agent 帮我查服务器”的爽感就想把它做成“全能运维助理”。我这里抛出两个非常适合扩展的场景大家可以直接套模板。第一个是高危操作会重启服务。这类 Skill 不能直接执行我加了一道确认机制。SKILL.md 中写法如下--- name: restart_cvm_instances description: 重启指定的腾讯云 CVM 实例。当用户要求重启实例、让某台服务器重新启动时使用。严禁在未获得用户明确确认的情况下执行。 --- 执行重启前必须按此流程操作 1. 向用户展示待重启实例的列表和当前状态。 2. 明确询问“确认要对以上 X 台实例执行重启操作吗此操作会导致服务短暂中断。” 3. 只有在用户明确回答“确认”“重启”等肯定语句后才运行 python3 scripts/restart_instances.py --instance-ids xxx。 4. 脚本返回后调用 list_cvm_instances Skill 验证实例状态是否恢复正常。这类“二次确认”写法是操作类 Skill 必加的安全护栏。模型本身没有操作权限概念全靠提示词约束容易失灵所以安全能力要在 Skill 层内置。第二个是代码审查场景。这个 Skill 适合开发者的日常利用 Agent 大模型的理解力配合脚本做提交检查--- name: review_recent_commits description: 审查 Git 仓库最近一次或指定次数的代码提交定位潜在的 Bug、安全问题和不合理实现。当用户说“帮我 review 下代码”“看看最近的提交”时使用。 --- 1. 运行 git log --oneline -10 查看最近的提交记录。 2. 运行 git diff HEAD~1 --stat 了解最近一次提交的改动范围。 3. 用户同意后运行 git diff HEAD~1 获取完整变更内容。 4. 逐文件分析变更重点关注空指针、SQL注入、硬编码密钥、缺少错误处理、逻辑边界错误。 5. 输出按“严重问题-建议优化-小问题”三个层级整理并标注文件与行号信息。代码审查 Skill 的价值在于它把模型的分析能力和仓库的真实变更串了起来一个人一天能高效审查多个仓库的提交。这类 Skill 的编写技巧是对“坏味道”明确枚举模型才知道该抓什么否则容易泛泛而谈。4.3 Skill 命中率怎么调到最高写了一大堆 Skill 之后新的问题出现了模型经常在多个 Skill 之间选错或者在不需要 Skill 的时候强行选一个。这个问题根源是描述写得不够精准。我的优化经验集中在三个地方。Skill 数量控制在 15 个以内。每次请求把全部 Skill 的元信息都塞给模型当候选技能超过 20 个选择准确率会急剧下降。数量多了就做分类比如运维类、开发类、信息查询类让 Agent 先定位分类再选技能。Description 前 20 个字最重要。模型的 attention 机制会对开头的语义格外敏感前 20 个字把触发条件写透比如“检查服务器是否被入侵”就比“服务器安全相关”命中率高得多。触发边界也要写清楚。描述里明确“何时不该用”比如“仅当用户提及腾讯云CVM时才使用”负例能大幅度减少误选。4.4 给 Agent 加上记忆让技能复用有上下文单一 Skill 只能完成一次性操作但真实业务往往是多次连续操作比如上午查了服务器异常下午排查原因晚上执行修复。想做到这点Agent 需要有跨会话的记忆能力。我当前的做法是在本地维护了一个 markdown 格式的 memory 文件记录关键结论同时给 Agent 提供一个“记忆管理 Skill”职责明确读取既有记忆补充更新内容。这样设计后Agent 面对多次开关的会话也能衔接上下文而不是每次都从零开始。唯一的记忆文件长期会爆炸所以需要定期压缩。我写了一个定时任务每天凌晨对 memory 文件做一次摘要归并把超过三十天的细碎记录删掉只保留核心经验。这个方案虽然简单但个人项目完全够用。5. 常见报错与排查实录5.1 agent execution provider 超时类问题很多人在 Agent 平台里上执行任务时遇到这类报错字面意思是“Agent 执行时响应超时了”实际代表某个执行组件在规定时间内没有返回结果。这背后最常见的原因是调用链路上某个 API 没在预期时间内响应——要么是模型服务太慢要么是服务器与目标 API 之间的网络不稳定要么是 SDK 默认超时时间设得太短。我第一次遇到时报错信息看起来很唬人结果逐层排查后发现只是模型服务端偶发延迟但 Agent 代码中的 HTTP 客户端 10 秒超时就断开了。解决方法是给 Agent 网络请求设置分层超时连接超时 5 秒读取超时 60 秒以上。在 OpenAI 兼容客户端中相关配置大致如下from openai import OpenAI client OpenAI( api_key..., base_url..., timeout60.0, max_retries3, )判断这类问题有一个通用思路先看是不是所有请求都超时如果是优先怀疑网络连通性可以在云主机上执行 curl 直接调目标 API 进行对照测试如果只是偶发超时则大概率是服务端波动把重试次数调上去同时把超时时间调宽松通常能解决。5.2 Skill 一直没被触发问题出在哪Skill 装了、文件格式也正确但 Agent 就是不用这是第二个高频问题。按照我的排查经验依次看三个地方。先检查 SKILL.md 的name是否为小写字母和下划线组合模型对非标准命名会难以理解。然后检查description是否带有明确的“触发场景引导”如果描述写得太泛比如“这是一个服务器工具”模型很难判断什么时候应该用它。最后是安装路径Skill 目录是否真的被 Agent 扫描到了这个可以通过 Agent 日志确认。还有一种情况容易被忽略当前用户的输入确实太模糊模型判断不出任何 Skill 适合触发。此时对用户侧的要求是尽量描述清楚任务。如果想验证 Skill 本身是否能被感知可以在用户输入中增加几个与 Skill 描述高度相关的词来测试然后观察模型行为是否变化。5.3 安全组放行了但端口仍不通这种问题如果在腾讯云上遇到通常先查安全组再查系统防火墙。很多时候两边端口我都放行了但调用仍然失败最后发现是云主机内部的 iptables 规则把包给拦了。执行如下命令检查sudo ufw status verbose sudo iptables -L -n | head -20另外如果 Agent 对外提供服务时只监听了 IPv4 地址而请求走了 IPv6也会出现端口“看似不通”的现象。排查时可以用 ss 命令确认进程的监听地址ss -lntp | grep 8080输出显示监听地址是 127.0.0.1:8080 还是 0.0.0.0:8080一下就能定位问题。我的 Agent 服务在测试阶段曾因为只监听了 127.0.0.1导致外部通过公网 IP 访问时始终失败查了半个小时才意识到。5.4 一次完整的日志分析实战再分享一个很有代表性的实战案例某个半夜 Agent 突然不响应了。我登录云主机发现进程还在但从日志看模型调用链路全部超时。先通过 journalctl 拉日志发现超时发生在调用模型 API 阶段。我用 curl 手动测试模型 API果然延迟高达十几秒。于是判断不是 Agent 代码问题而是模型服务端波动。我把 Agent 切到备用模型 endpoint服务立刻恢复。整个过程几分钟搞定。事后我给 Agent 加了一个“健康检查 Skill”定时探测各依赖 API 的延迟和可用性异常就通过 Webhook 推送到企业微信。这样即使凌晨出问题也能第一时间收到警报而不是早上起来才发现服务已经挂了一整夜。这个经验对所有跑在云上的 Agent 都适用服务本身不重要可观测性才是让服务省心的基石。6. 全流程踩坑心得与还能继续扩展的方向整套项目跑了大半年有几个值得分享的体会。Skill 的设计量要“小步快跑”先做单个指令跑通了再慢慢丰富。一次做一个大而全的 Skill效果往往很差因为边界越模糊模型越难正确调用。小而清晰的技能组合往往更能提升 Agent 的整体效率。我早期把很多逻辑写进单个 SKILL.md 里让它支持十几种变化结果模型经常挑错执行路径。拆成三五个技能后反而稳定模型始终选中最贴近请求的那一个。这一点值得和所有打算“一口吃成个胖子”的朋友共勉。还有一个技巧写 SKILL.md 时把自己想象成是在为另一个工程师写交接文档而这位“工程师”恰好不会问问题只能按文档干。所以每个默认值、每个边界条件、每个失败兜底都要写清楚。文档越明确模型执行得越准确。腾讯云这套环境其实是 Agent 练手的绝佳场所因为它的 API 覆盖全面从云主机到域名、对象存储到数据库都能用同一套凭证调用。顺着这个思路继续扩展可以做周期巡检 Agent、自动处理工单的助理 Agent甚至做成一个可对外提供的“云资源问答机器人”。下一步我准备把所有 Skill 都加上腾讯云子账号级别的细粒度权限控制在安全上再收一道口子。