最近一段时间我一直在腾讯云上折腾自己的 Agent 项目从最开始的“会聊天的机器人”慢慢做成了一套带 Skills 的自动化工作流。老实说真正让 Agent “能干实事”的不是模型本身的聪明程度而是你愿不愿意给它配一套好用的 Skills再围绕 Skills 把部署、编排、网关、容灾这些基础设施理顺。这篇文章就复盘一遍我踩过的坑和最终形成的最佳实践从 AI Skills 的架构思路到 LiteLLM Proxy 网关接入再到 Docker 镜像推送腾讯云容器镜像服务最后落到云服务器上真实跑起来。内容偏实战适合已经写过几个 Agent Demo、正准备往生产环境推的开发者。1. 一个 Agent 项目先想清楚这三层结构1.1 我理解的 Agent 到底是什么很多刚入门的朋友会把 Agent 理解成“一个能对话的模型”这其实不太准确。Agent 是一个以模型为决策核心、以外部工具为能力延伸的自主执行系统。它接收任务、拆解步骤、调用工具、检查结果整个循环由模型驱动而不是靠固定脚本。我用一个生活化的例子解释模型是大脑负责想“下一步该干嘛”Skills 是双手负责“真正把事情做出来”。没有双手的大脑只能聊天有了双手才能写文件、查数据库、调用 API、操作浏览器。所以我在设计项目时第一个问题永远是——这个 Agent 需要哪些 Skills而不是用哪个模型。模型选错了可以换Skills 设计错了整个系统就瘫痪了。1.2 Skills 才是 Agent 的“手脚”和“工具箱”所谓 AI Skills可以理解为一组可以被模型动态调用能力单元。每个 Skill 通常包含一个名字、一段描述、入参出参定义以及背后的执行逻辑。模型在接到任务后会根据任务内容判断“该调哪个 Skill”然后填充参数、发起调用再把返回值拿回来继续推理。我习惯把 Skills 分为三类基础工具型读写文件、执行 shell、操作 Redis 或数据库这类 Skills 把本机能力暴露给模型。业务能力型比如查天气、发邮件、生成工单直接对接具体业务场景。复合流程型内部串起多个 API比如“拉取订单-计算折扣-生成对账单”对模型只暴露一个入口。一开始我犯过一个错把每个 API 都拆成一个 Skill结果模型在复杂的推理链路里频繁切换、参数拼错。后来我调整思路粒度过细的 Skill 让模型容易走错路粒度过粗的 Skill 又让模型无法灵活组合。最终的经验是把原子操作保留在小工具里把稳定的业务链路固化成复合 Skill让模型尽量面对“有明确输出”的模块。1.3 为什么我选择腾讯云这套组合拳在动手之前我也对比过几套部署方案本地跑、轻量服务器、K8s 集群、Serverless。最后选腾讯云主要原因是整个链路的完整度一套账号就能把容器镜像仓库、云服务器、对象存储、DNS 解析全部串起来省掉了很多跨平台对接的麻烦。我最终的架构是这样模型调用层用 LiteLLM Proxy 做统一网关兼容多家模型 APIAgent 编排层跑在 Docker 容器里通过 HTTP 调用 SkillsSkills 执行层拆成独立的服务和编排层通过 REST 或内部消息通信。整个系统全部部署在一台 2C4G 的云服务器上再用二级域名把 Skill 服务暴露出去。这套组合的好处是层级清晰、按需扩展单台机器就能跑出接近生产环境的完整效果。2. Agent 与 Skill先把概念边界划清楚2.1 Skill 和 Agent 的区别一句话和一张表“Skill 和 Agent 的区别”是我在社区里看到提问频率最高的问题。一句话版本Agent 是执行者Skill 是执行者的能力模块你可以让一个 Agent 同时拥有多个 Skills也可以让多个 Agent 共享同一个 Skill。我用一张表说明更直观维度AgentSkill定位自主执行的主体可复用的能力单元核心决策、规划和循环输入、处理、输出生命周期随任务创建和结束长期存活、按需调用依赖关系依赖多个 Skills依赖具体工具或 API调试方式看链路日志和推理过程看单个接口的入参出参示例自动化测试 Agent“执行一条 SQL 查询”在工程实现上我会把 Agent 写成“调度器 状态机 记忆容器”的组合体而把 Skill 写成一个标准接口的独立服务。这样调试时能单独测 Skill跑通之后再挂到 Agent 上心智负担会小很多。2.2 Skill 的底层机制上下文注入与工具注册Skill 能被模型“理解并选择”靠的不是魔法而是上下文注入。每次 Agent 发起推理时系统会把所有可用 Skill 的元信息名字、描述、参数 Schema拼装进系统提示词或工具定义列表里。模型看到这些描述后才能在生成回复或者规划步骤时从“工具箱”里选出正确的那个。这里有一个非常关键的细节Skill 描述写得好不好直接影响模型的选择准确率。我第一次设计 Skill 时描述写得很模糊比如“获取用户信息”模型经常在用户问“查询积分”时调错成“查询订单”。后来我改为“当用户需要查看积分余额时调用返回剩余积分和最近三条变动记录”准确率立刻上来一大截。写描述时要把触发场景、输入要求、返回内容都写清楚就像给同事写交代文档一样。除此之外还有一个容易被忽略的点Skill 的输入参数定义要严格。如果参数是对象类型最好用 JSON Schema 描述清楚嵌套结构避免模型自由发挥。我踩过的典型异常是参数类型传错比如把字符串传给了整数结果 API 报 500Agent 还一脸无辜地把错误原样丢给用户。后来我统一在接口入口强制校验参数类型不合格就直接返回带提示的错误码出错的概率降了很多。2.3 Agent 的编排层框架选型的几点考量在选 Agent 编排框架时很多人直接冲上去写状态机、写记忆管理其实大可不必。目前成熟的框架已经帮你处理了“模型循环、上下文拼接、工具调用解析、错误重试”这一套固定的脏活你只需要把精力花在业务逻辑上。我自己的选择倾向如果项目简单直接用原生模型 API 加上手写的工具调用循环如果项目复杂就上成熟的 Agent 框架。腾讯云开发者社区里很多同行的做法也类似先把框架跑通再逐步定制。这样既能保证开发效率又能在后期有足够的改造空间。我当时对比了几个框架之后决定先用一个轻量框架把链路跑通核心原因有两个第一我不想把时间花在重复实现模型调用解析上第二框架自带的日志和追踪功能对我排查问题太有用了。跑通之后我再把自定义的 Skills 接入进去整个开发周期比从零手写缩短了一半以上。3. 从零搭建 Agent模型网关、Skill 开发与 API 接入3.1 接入 LiteLLM Proxy 作为模型网关做 Agent 项目避不开一个问题模型服务从哪里来。如果每个 Skill 都直接用各家模型 SDK代码很快就会被厂商绑定搞乱。我的做法是上一套 LLM 网关把模型调用统一到一个服务上。LiteLLM Proxy 是我一直在用的方案它支持把多个模型供应商的 API 转成统一的 OpenAI 兼容接口还能做 Key 管理、限流和审计。部署 LiteLLM Proxy 很简单核心就是一个配置文件指定可以使用的模型和对应的 API Keymodel_list: - model_name: primary-chat litellm_params: model: openai/gpt-4o-mini api_key: sk-xxxx - model_name: local-chat litellm_params: model: ollama/qwen2.5:7b api_base: http://127.0.0.1:11434配置好之后我就把所有调用方都指向 LiteLLM Proxy 的地址比如http://服务器IP:4000/v1/chat/completions。这样底层模型无论换成哪家上层的 Agent 编排层都完全无感。我实际体验中这套网关非常稳尤其是把多个开源模型和商业化模型统一管理之后切换模型只需要改配置不再需要改代码。3.2 用 Python 写第一个 Skill 并暴露为 HTTP 接口我第一个真正落地的 Skill 是一个“订单信息查询”服务。它做的事情很简单接收用户编号从数据库查出订单列表再把数据整理成大模型容易理解的文本返回。这个 Skill 我封装成了一个独立的 FastAPI 服务核心代码如下from fastapi import FastAPI, HTTPException from pydantic import BaseModel, Field app FastAPI() class OrderQuery(BaseModel): user_id: str Field(description用户编号必填) limit: int Field(10, description返回订单数量上限, ge1, le50) app.post(/skill/order-query) def query_order(req: OrderQuery): # 实际场景中这里会查询数据库这里简化为模拟数据 if req.user_id U10001: return { code: 0, data: [ {order_id: A1001, amount: 99.0, status: 已发货}, {order_id: A1002, amount: 199.0, status: 待付款} ] } raise HTTPException(status_code404, detailuser not found)写这个接口时有几个细节我想强调一下。第一入参一定要用 Pydantic 做类型校验Field 描述最好写清楚这样后续把 OpenAPI Schema 喂给模型时参数说明会非常准确。第二返回结构要固定最好统一用{code: 0, data: ...}这种信封结构错误时用非 0 的 code 区分业务错误而不是依赖 HTTP 状态码判断。因为模型处理 HTTP 500 的能力很差但处理业务错误码的能力相对好很多。启动这个 Skill 服务后我用curl快速验证了一次curl -X POST http://127.0.0.1:8000/skill/order-query \ -H Content-Type: application/json \ -d {user_id: U10001, limit: 5}返回结果符合预期这一步的验证很重要它保证了在接入 Agent 之前Skill 本身是“健康”的。3.3 把 Skill 挂到 Agent 编排层一次真实的调用链路Skill 服务跑通之后下一步就是把它挂到 Agent 编排层。这个环节最重要的文件是“Skill 注册表”它告诉编排层系统里有哪些 Skill、各自是干嘛的、怎么调用。我简化后的注册表如下{ skills: [ { name: order_query, description: 当用户需要查询订单信息时调用支持按用户编号查询订单列表, endpoint: http://127.0.0.1:8000/skill/order-query, parameters: { type: object, properties: { user_id: {type: string, description: 用户编号}, limit: {type: integer, description: 返回数量上限, default: 10} }, required: [user_id] } } ] }这里要注意description字段是整个注册表里最重要的部分它决定了模型什么情况下会调这个 Skill所以我尽量写得口语化少用术语让模型一眼就能“看懂”。这一步走通后我试着让 Agent 处理一句非常口语化的请求“帮我查一下 U10001 最近的订单”。从日志里可以看到Agent 完整地走了一遍识别意图 - 选中 order_query Skill - 填充 user_id - 发起 HTTP 请求 - 拿到结果 - 组织语言回复用户。我第一次跑通这条链路时非常兴奋但同时也发现一个问题模型在生成参数时偶尔会发挥“想象力”比如把user_id写成不存在的名字。后来我在编排层加了一层参数清洗逻辑把模型生成的参数和注册表的 Schema 做一次强校验不合法的参数直接走“澄清式回复”让用户补充信息而不是把错误请求打到后端。4. 上线部署Docker 镜像构建与腾讯云容器实践4.1 多阶段构建镜像瘦身是第一课本地跑得好不代表上线能跑部署环节的坑一点也不比开发少。我先说一个最直观的问题——镜像体积。刚开始我图省事直接把 Python 环境、构建工具、源代码全塞进一个镜像结果镜像体积接近 2GB上传慢不说启动也慢。后来我改成多阶段构建# 第一阶段构建依赖 FROM python:3.11-slim AS builder WORKDIR /app COPY requirements.txt . RUN pip install --prefix/install -r requirements.txt # 第二阶段运行镜像 FROM python:3.11-slim WORKDIR /app COPY --frombuilder /install /usr/local COPY . . EXPOSE 8000 CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8000]这样最终镜像里只保留运行所需的依赖和代码体积能压缩到 300MB 左右。对于云服务器部署来说镜像越小拉取越快磁盘占用越少后续的镜像版本管理也更轻松。4.2 推送到腾讯云容器镜像服务镜像构建好之后下一步就是推到腾讯云容器镜像服务TCR。这个步骤流程上很简单但有几个细节容易踩坑。首先你需要在腾讯云控制台开通容器镜像服务并创建一个命名空间和镜像仓库。然后在本地登录仓库sudo docker login ccr.ccs.tencentcloud.com --username 你的腾讯云账号ID这里会提示输入密码密码不是腾讯云登录密码而是访问凭证里的专用密码这个在控制台的 API 密钥或访问凭证页面可以找到。我第一次操作时在这卡住了几分钟因为一直下意识输入登录密码后来才反应过来。接下来给镜像打上仓库的完整标签并推送sudo docker tag agent-skills-server:latest ccr.ccs.tencentcloud.com/your-namespace/agent-skills-server:latest sudo docker push ccr.ccs.tencentcloud.com/your-namespace/agent-skills-server:latest推送完成后我在云服务器上用同一个 docker login 登录然后直接 pull 这个镜像运行起来。整个过程非常顺这也让我意识到容器化部署的一个大优势本地和服务器环境完全一致不会再出现“在我电脑上是好的”这种尴尬。4.3 云服务器上的运行配置与二级域名接入Agent 服务的容器跑起来之后面临的下一件事就是怎么让别人访问。我直接在腾讯云服务器上配置了一个二级域名专门用来暴露 Skill 服务。步骤大概是在域名服务商处加一条 A 记录把skill.yourdomain.com解析到服务器公网 IP然后在云服务器的防火墙或安全组里放行对应端口最后在 Nginx 里配置反向代理把域名请求转发到本机的 8000 端口。这里有一个坑一定要提醒腾讯云在轻量应用服务器和云服务器两种产品上安全组的配置入口不一样我一开始在轻量服务器上找不到放行端口的入口后来才发现控制台路径不同。如果你手头是轻量服务器要到“防火墙”页面设置如果是标准 CVM则要到“安全组”页面设置。放行时只开需要的端口别把什么 22、80、443、8000 全裸奔到公网用 Nginx 统一入口管理会更安全。跑通后我试着用二级域名访问 Skill 接口然后在 Agent 编排层把 Skill 地址换成了这个公网域名。这样设计的额外好处是后续 Skill 服务迁移到别的服务器只要域名解析不变Agent 编排层就不用动。5. 常见问题排查与避坑实录5.1 Redis 改密码后重启失败的排查我在部署过程中遇到的第一个比较恼火的问题是 Redis。有一次我改了 Redis 的密码重启之后发现 Agent 的内存服务一直连不上日志提示权限认证失败。最开始我还以为是防火墙问题排查了一圈才发现是 Redis 启动脚本里没有带上requirepass配置导致服务起来了但密码没生效。这个问题的根源在于修改密码不能只改redis.conf还要看启动方式是否读取了这份配置。如果通过systemctl启动配置文件路径可能被覆盖如果手动启动一定要显式加上--config参数redis-server /path/to/your/redis.conf另外改了 Redis 密码之后所有客户端配置也要同步更新。我当时在环境变量里写了旧密码导致服务一直用旧密码去连接自然被拒。现在我把这类敏感配置统一放在 env 文件里每个环境一份排查问题时会快得多。5.2 “agent execution terminated due to error”的两种常见成因在使用 Agent 框架时我最头大的报错就是agent execution terminated due to error。这个报错本身非常笼统几乎不包含任何有用的堆栈信息。踩了几次坑之后我发现这个错误最常见的原因有两个。第一个原因是Skill 接口返回了模型无法解析的内容。比如接口返回了 JSON 之外的纯文本或者返回结构里嵌套了不可见字符模型在解析工具输出时直接崩溃。解决办法是在 Skill 接口层把所有返回都严格序列化成 JSON并且在 Agent 编排层做好异常捕获超时或解析失败时返回明确的错误代码。第二个原因是上下文长度超限。当 Agent 需要查询大量数据且 Skill 把全部明细都塞进上下文时很容易突破模型的 token 上限导致整个执行被中止。我的解决方案是在 Skill 返回前做一次摘要只返回关键字段和汇总统计而不是把几百行数据库记录全部丢给模型。如果你确实需要完整数据那就把“读取完整数据”拆成另一个 Skill让 Agent 按需调用。这类错误排查时我强烈建议打开 Agent 框架的执行日志和时间线追踪。很多框架自带每一步的模型输入输出记录你只需要定位到“最后一次成功”和“第一次失败”之间发生了什么基本就能找到根源。不要对着一个错误的堆栈反复猜。5.3 注册与网络环境异常提示的处理还有一个很常见的问题在购买或操作云资源时偶尔会碰到“网络环境异常无法注册/无法执行”之类的提示。遇到这种情况不要慌大部分时候不是账号出了问题而是操作环境的网络特征触发了风控策略。我的建议是先切换网络看看或者尝试在干净的浏览器无痕窗口里重试如果服务器日常登录受影响直接换用控制台自带的网页终端避免第三方终端软件和网络因素叠加干扰。这里我也想说一句遇到任何“环境异常”的提示优先排查自己的网络和浏览器扩展别急着找客服。很多 Chrome 插件会修改请求头导致云服务控制台认为请求不合法。把插件关掉、刷新重试多半就能解决。最后再分享一个提升调试幸福感的小技巧整个项目跑顺之后我最后装上了一个“必杀器”把 Agent 的每一步决策日志都落到本地文件并附带时间戳和 token 消耗统计。这样每次任务跑完我都能复盘——模型在哪一步浪费了 token、在哪一步选错了 Skill、哪次调用超时了。这个习惯帮我优化掉了很多隐藏问题也让整个系统的行为变得可解释、可预测。如果你正在规划自己的 Agent 项目我的建议是先把最小闭环跑通一个模型网关、一个 Skill、一个编排层部署到云服务器上用真实任务测试。这套从零搭建的流程走完后你会发现 Agent 从“玩具”到“生产力工具”之间的距离并没有想象中那么大。
