腾讯云AI Agent实战：AI Skills设计、Docker部署与问题排查

从今年开始我明显感觉到身边问AI Agent的人变多了。大家不再满足于让大模型聊天而是希望它真的能干活查库存、发通知、生成周报、调内部系统。我最近在腾讯云上把一个原本只会回答问题的机器人升级成一个能自动拆任务、调工具、跨系统完成工作的全能Agent这套实践最核心的部分就是用好了腾讯云上的AI Skills。这篇文章把我从概念梳理、架构设计到部署上线的完整过程都抖出来包括踩过的坑和改过的配置给想自己动手搞Agent开发的朋友一份能直接抄的作业。如果只为了跑通Demo随便一台电脑都能做但要做到“全能”并且长期稳定运行就会碰到一堆没人提前告诉你的问题Skill到底该怎么设计Agent进程挂掉怎么恢复Redis改个密码重启为什么会失败腾讯云控制台偶尔提示网络异常又该怎么处理这些问题我在项目里都遇到过下面一项项讲。1. 项目概述与整体设计思路1.1 Skill和Agent到底是什么关系很多刚接触Agent开发的朋友第一个问题就是“skill和agent区别”。我一开始也混把Skill当成一个插件目录后来发现没那么简单。Agent本身是一个具备决策和执行的完整系统。它可以理解用户意图拆解任务规划执行顺序并且在执行过程中根据环境反馈调整策略。Skill则是Agent可以调用的“能力单元”本质是一份描述“我能做什么、怎么用我”的协议。比如一个“查库存”的Skill它不只包含查数据库的代码还要告诉Agent什么时候该用它、需要传入哪些参数、返回什么格式。我习惯用这个类比Agent是公司里的项目经理Skill是不同部门的执行团队。项目经理不关心团队内部怎么实现只关心在什么情况下给哪个团队派什么活以及拿回来的结果长什么样。所以你定义Skill时最重要的不是代码写得多漂亮而是“把接口描述清楚”让Agent能看懂、能用对。每条Skill最好只有一个清晰职责不要一个技能里既查库存又写日报。Skill多了以后描述字段尤其重要因为Agent选择工具基本靠描述匹配。描述写得模糊Agent就会在多个Skill之间犯选择困难症甚至拿错工具。1.2 全能Agent的养成目标我这个项目的目标很明确做一个能处理日常运营琐事的Agent。具体来说它要做四件事查订单库存、生成每日销售日报、调用外部API同步数据、在异常时主动推送告警。这四件事看起来简单真正做起来涉及模型调度、工具调用、会话记忆、异常处理四条链路。命令Agent“帮我查一下SKU 10086的库存”Agent需要先解析出意图“查库存”找到匹配的Skill构造好参数再请求Skill的endpoint。如果库存低于阈值它还要继续触发告警Skill整个过程是一个多轮决策闭环。所以我在设计阶段先画了能力边界不碰支付、不做审批、不直接写生产数据库。这些高风险操作只做成“建议确认”模式Agent负责分析出结果最后是否需要执行由人在群里确认。这个设计极大降低了上线时的不安全感也是我觉得做Agent最重要的一条原则先限制能力再扩展能力。1.3 为什么最后选了腾讯云Agent可以跑在本地也可以跑在云上。本地部署的问题是第一模型调用和API访问容易受本地网络波动影响第二机器不能7x24小时开机第三外部系统回调Agent时本地没有公网入口。我选择腾讯云主要是看中三样东西一是国内访问延迟低二是从服务器、域名、Redis到容器镜像服务基本一站式搞定三是控制台生态完整后面扩容量、加监控不用来回切换平台。实际开发中我用了轻量应用服务器跑Docker容器用容器镜像服务存Agent镜像用云数据库Redis存会话状态域名解析也在同一套体系里。好处很明显少对接几个平台就少踩几个集成坑。这里提醒一句选云服务商别光看价格要看“你要用的服务是不是都是成熟产品”。如果A家的域名解析很好但容器服务很弱B家的RDS很稳但服务器要排队申请那整个项目的时间成本会翻倍。我自己在项目里最常用的实际是腾讯云的容器镜像服务、Redis和轻量服务器这三者组合起来非常顺手。2. AI Skills的核心设计与关键细节2.1 一份能被Agent读懂的Skill定义格式AI Skills的形式很多有人用OpenAPI规范有人直接用代码函数加装饰器也有人用YAML描述。我用的是最直白的方式每个Skill一个YAML文件里面写清楚名称、描述、请求方式和参数规范。下面是我项目中“查询库存”Skill的定义去掉敏感信息后大概是这个结构name: stock_query description: 根据SKU编码查询商品实时库存当用户询问库存、余量、是否有货时调用 endpoint: https://skills.example.com/stock method: POST headers: Content-Type: application/json parameters: - name: sku_id type: string required: true description: 商品SKU编码例如SKU10086 response_schema: sku_id: string stock: integer updated_at: string字段不多但每个都很关键。name是Agent内部调用的唯一标识我用蛇形命名法方便代码引用。description不能写得太抽象要明确出发条件模型就是靠这段描述来决定“该不该用这个Skill”。parameters要逐个说明类型、是否必填和含义参数说明写得不清楚Agent会经常传错值。response_schema同样重要。很多初学者忽略它结果Agent拿到接口返回后不知道字段含义。我一开始也吃过亏后来每个Skill都补上返回结构说明Agent解析结果的准确率明显提高。2.2 参数的“模型友好化”设计原则Skill参数设计不是给后端工程师看的而是给模型看的。后端接口可能用的是业务字段名但直接暴露给Agent会出问题。比如接口接收一个warehouse_id如果Skill定义里只写“仓库ID”Agent并不知道该传什么值。我的原则是参数名用易懂的英文description里必须给例子。例如warehouse_id的描述改成“仓库唯一标识默认为WH001可传WH002等”就要好得多。还有一类参数是枚举型我会直接把可选值列在description里减少模型自由发挥的空间。另外请求体和返回体尽量都用JSON。从实践看JSON对模型来说是最不需要额外解释的数据格式。尽量不要让Agent去解析XML或者CSV处理这些格式时会多消耗token也容易出解析错误。2.3 Skill之间如何隔离和协作一个Agent挂多个Skill不代表Skill可以互相调用。我在架构上让每个Skill都是独立服务通过统一网关暴露给AgentSkill之间不直接通信。为什么这么设计因为一旦两个Skill产生直接依赖后面任何一个Skill升级都可能影响另一个。独立部署后我可以单独更新某一个Skill而不影响Agent主进程。如果Skill之间确实需要协作比如“查库存”后自动“发告警”我会把这种调度逻辑交给Agent让Agent按顺序调用两个Skill而不是在Skill代码里硬编码调用关系。当然完全隔离会增加请求延迟。每个Skill都是一次HTTP调用多一跳就多几十毫秒。对于常规运营场景完全可以接受。如果对性能要求极高也可以用进程内函数方式加载Skill但那就牺牲了独立更新能力。我的取舍是前期用独立HTTP服务把逻辑理清楚等稳定后再优化延迟。2.4 运行载体选型云函数、容器还是裸机Skill服务可以放在云函数里也可以放在容器里还可以直接扔在裸机上跑。三种方案我都试过最后选了容器。云函数的优点是真省事写好代码传上去就能跑按调用量计费适合单一轻量技能。问题在于依赖管理麻烦有些Python库体积大、冷启动时间明显Agent实时调用时等不起。裸机最灵活但所有东西都自己运维升级回滚都得手动处理。容器是中间态镜像把环境和代码一起打包推到腾讯云容器镜像服务在任何一台服务器上都能拉起同一个环境排查问题也更方便。我的部署结构是Agent主程序放在轻量服务器上跑Docker容器每个Skill拆成独立的容器通过内网地址互相访问。镜像统一推到腾讯云容器镜像服务服务器上用docker compose一键拉起。这套方案维护成本低也方便以后扩机器。3. 从0到1的实操过程3.1 环境准备账号、服务器和二级域名动手之前先把基础资源备齐。我用的是一台轻量应用服务器2核4G装好Docker和docker compose。镜像仓库在腾讯云容器镜像服务里创建一个命名空间后面推送镜像要用。域名我提前在腾讯云完成解析创建了一个skills二级域名专门用来暴露Skill接口。“腾讯云怎么申请二级域名”这个问题经常看到。严格说二级域名不是“申请”来的而是你拥有一个主域名之后在DNS解析控制台添加一条记录。比如主域名是example.com想给Skills模块用就添加一条主机记录为skills、类型为A的记录值填服务器公网IP。等解析生效后skills.example.com就是你自己的二级域名。如果只是本地测试用IP加端口也能访问但后面Agent要访问Skill接口使用域名比IP稳定还方便以后换IP不用改配置。所以我建议一开始就把域名解析搞定。服务器安全组里要放行80/443端口如果Skill接口用自定义端口也要记得在安全组和系统防火墙里同步打开。3.2 用Docker把Agent镜像推送到腾讯云容器镜像服务先说明一下整体步骤本地构建镜像打标签登录腾讯云容器镜像服务推送服务器上拉取运行。构建镜像前我写了一个简单的Dockerfile大致长这样FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . CMD [python, main.py]构建好本地镜像后执行以下命令推送docker login ccr.ccs.tencentyun.com --username腾讯云账号ID --password访问令牌 docker tag myagent:v1 ccr.ccs.tencentyun.com/命名空间/myagent:v1 docker push ccr.ccs.tencentyun.com/命名空间/myagent:v1这里的腾讯云账号ID不是登录密码是在访问凭证里生成的长期密钥。第一次推镜像时我就在这里卡了半天一直用登录密码输入结果一直报denied。访问凭证在容器镜像服务的控制台里可以生成建议单独建一个仅用于镜像仓库的凭证别把主账号密钥到处用。推送成功后我在服务器上执行docker pull ccr.ccs.tencentyun.com/命名空间/myagent:v1 docker run -d --name agent \ -p 8080:8080 \ -e SKILLS_DIR/app/skills \ -e REDIS_URLredis://:密码内网IP:6379/0 \ ccr.ccs.tencentyun.com/命名空间/myagent:v1SKILLS_DIR告诉Agent去哪里加载Skill定义REDIS_URL用于会话存储。之所以用环境变量而不是写死在代码里是因为后面更新Skill配置不用重新打镜像。3.3 在Agent里挂载Skill定义Skill定义文件不只是给研发看的也是运行时给Agent加载的。以我用的Python Agent框架为例启动时读取SKILLS_DIR目录下的所有YAML文件注册成可调用工具然后通过function calling机制暴露给大模型。整个调用链路是这样的用户输入一句话。Agent把用户消息和所有Skill的name、description、parameters一起发给大模型。大模型决定是否需要调用某个Skill如果要调用会返回一个结构化的工具调用请求。Agent根据请求参数去请求对应的Skill endpoint。拿到结果后再连同原始用户消息一起交给大模型生成最终回复。所以Skill定义里那几行description本质上就是大模型的“菜单”。菜单写得越清楚模型点菜就越准。我每次调整Skill描述后都会跑一遍“实测对话”来验证故意用各种说法问库存看Agent能不能正确命中stock_query这个Skill。3.4 用Redis保存会话状态和技能缓存Agent的多轮对话依赖会话记忆。如果每轮对话都重新把所有历史发给大模型token消耗会非常大网络延迟也会增加。我用腾讯云数据库Redis保存最近几轮关键信息比如用户ID、当前任务上下文、上一次工具调用结果。实现不复杂。每次用户进入会话先从Redis读取最近的history摘要拼接到系统提示词中每轮结束后把新的交互写入Redis并设置过期时间。Redis的EXPIRE策略很实用我一般设置会话1小时过期既能保证连续操作又不至于把无效上下文一直存着。除了会话状态我还用Redis做了简单的技能结果缓存。比如同一个SKU在5分钟内被反复查询就不再请求真实系统直接返回缓存结果减轻业务系统压力。这个缓存的过期时间要控制好库存这种强实时数据缓存时间不超过1分钟。这里要特别提醒密码问题。我在腾讯云数据库Redis控制台重置了密码之后服务端一直连接失败排查好一会儿才发现原因是连接串里的密码没有同步更新。后面对接Redis一定要把REDIS_URL里的密码改成最新值并且重启所有依赖Redis的容器。4. 常见问题与排查技巧实录4.1 Redis改了密码之后重启服务一直失败这个问题在热搜词里也出现过我身边也有人遇到过。现象是修改Redis密码后重启Redis进程起不来或者起来了但客户端一直报NOAUTH Authentication required。很多人的第一反应是改配置文件里的requirepass。但改完之后必须确认系统服务使用的配置文件是哪一个。我踩过的坑是机器上有多个redis.confsystemd的unit文件里指定的是旧的配置路径我改了另一个文件当然不生效。建议三步排查先确认Redis启动方式systemctl status redis看unit文件路径或者ps -ef | grep redis看启动参数。在确认的配置文件里找到requirepass改成新密码。重启后用redis-cli -a 新密码 ping验证。容器方式部署的Redis也一样改密码后要把容器的启动参数--requirepass更新掉再重新创建容器。只改容器内部配置文件然后docker restart如果启动命令里带了旧参数容器一重启就会被覆盖回去。4.2 Agent中途报错提示execution terminated due to errorAgent跑着跑着突然中断是开发中最容易心态崩的问题之一。仅提示一句“execution terminated due to error”没有具体原因非常让人头疼。从我实际遇到的情况看主要原因有三类某个Skill的endpoint超时或返回非200状态Agent在等待结果时达到上限被终止。模型上下文超过限制尤其是历史会话太多请求大模型时报错。Agent进入死循环比如一个Skill返回结果不满足条件Agent反复尝试最后触发了步数上限。排查时不要只看Agent主进程日志要找到真正报错的那一行。比如日志里出现[Skill:stock_query] request failed: HTTP 504, retry 3 times这就说明问题出在Skill接口本身而不是Agent框架。用Postman直接请求Skill endpoint看是不是真的超时如果是就得去优化Skill的响应时间比如加缓存、改异步任务。如果日志里是context length exceeded那就得清理会话历史或者换成更大上下文的模型。如果是频繁循环执行同一Skill多半是parameters描述不够清楚模型拿到了不合理的参数Skill返回了“假失败”。建议从一开始就给Agent设定最大执行步数比如10步。超过步数直接结束返回“任务过长需要人工介入”。这能避免很多无意义的资源消耗。4.3 腾讯云控制台提示“您所处的网络环境异常无法进行注册/登录”这个提示我遇到过尤其在公司网络或校园网里。原因通常是当前出口IP被风控标记经常出现在共享IP段或者该IP段有大量异常请求的情况下。处理办法很简单先不要反复试越试越容易触发更严格的风控。先清理浏览器缓存和Cookie检查系统时间是否正确再换个网络环境试试。我实际用的方法是手机热点连一下再回到原网络就能正常访问。如果还不行等半小时再试风控一般会自动解除。这里多提一句如果你是在云服务器上操作腾讯云控制台也可以用API方式管理资源避免浏览器交互被网络环境干扰。API的密钥在控制台可单独创建按最小权限原则分配这样服务器运维和人工登录层面互不干扰。4.4 镜像推送到腾讯云容器镜像服务总报denied推送镜像失败最常见的报错是denied: requested access to the resource is denied原因基本是四选一没有登录或者登录时用了邮箱/手机号而不是账号ID没有在容器镜像服务里创建命名空间镜像标签里的命名空间和实际创建的不一致访问令牌权限不足。对照检查一下就能解决。还有一个容易忽略的点如果之前登录过其他镜像仓库Docker会把凭证缓存在本地导致登录腾讯云时被旧凭证干扰。可以先执行docker logout清理再重新登录。镜像推到仓库后先别急着在服务器上拉取。本地先docker run试一遍确认镜像没问题再上服务器。这样能区分是镜像本身的问题还是服务器环境的问题。4.5 二级域名解析生效慢或解析到旧IP添加完二级域名解析记录后有时发现访问的还是旧IP。这和DNS缓存有关除了等TTL过期也可以先在一些公共DNS查询比如nslookup skills.example.com 1.1.1.1看解析结果是否已经更新。如果公共DNS已经是新IP本地还是旧IP换一下本机DNS或者重启网络设备即可。更要注意的是如果以后服务器换了IP必须同步去改DNS记录不要以为旧解析会自动失效。我吃过一次亏服务器迁移后忘了改解析Agent能启动但Skill接口一直404排查半天才发现流量都打到旧机器上了。5. 一些至今受用的实操经验本来写到问题排查就差不多了但还有几条经验我觉得值得单独拿出来说。第一Skill定义文件一定要纳入版本管理。我用的Git仓库里有一个skills/目录每个YAML文件都有提交记录。是哪一轮改动导致Agent行为变化翻下Git历史就能定位。这个习惯帮我省了无数次“我记得之前能用的啊”的尴尬。第二Agent的日志要结构化输出。在关键节点打印出Skill名称、参数、耗时、结果摘要排障效率会快很多。日志格式建议统一成JSON后面接日志服务也好自己写脚本统计也罢都能少折腾。第三动手写第一个Agent的时候不要一上来就追求“全知全能”。先把一个最常用的Skill做到极致比如查库存让Agent对“还有货吗”“余量多少”“哪些缺货”这几类问题都能准确命中再继续加下一个能力。能力是一步步养出来的不是一次性堆出来的。我自己在持续迭代这个项目时最大的感受是AI Agent目前的瓶颈其实不在模型有多强而在于周边工程够不够扎实。AI Skills正好是解决这个问题的一把钥匙它把“这个Agent会做什么”变成了可配置、可版本化、可测试的资产。如果哪一天Skill接口崩了Agent很快就会在日志里暴露出问题如果Skill设计得足够清晰Agent的判断力和执行力会超出你的预期。最后分享一个小技巧每次给Agent新增Skill后不要只测标准问法还要测“模糊问法”和“错误问法”。模糊问法看它能不能在多个Skill中选对错误问法看它会不会瞎调用。这样反复打磨一轮Agent才更像一个真正的“全能选手”。