前阵子把一套基于腾讯云的 AI Agent 从零搭到了能稳定跑业务中间经历了架构选型、Skill 设计、容器化部署、线上排障一整轮折腾。说实话网上的 Agent 教程很多但大多数停在调一个 API、写一段 ReAct 循环的玩具阶段真正到生产环境时会发现工具调用、记忆、权限、服务编排全是坑。这篇东西不准备做概念科普就围绕在腾讯云上把 Agent 做得真正可用这件事把 AI Skills 的设计思路、底座搭建和部署经验完整串一遍也把我在实际项目里踩过的坑一并交代清楚。文章适合两类人看一是准备从零开发 Agent 但还没跑通全链路的开发者二是已经在做 Agent 产品、想优化工具调用和任务编排质量的工程师。我会尽量少说空话所有结论都来自实际可复现的操作。1. 先想清楚Agent 和普通 ChatBot 的差别在哪里很多人一上来就问用什么框架、上什么模型但我建议先想清楚一件事你做的到底是一个会聊天的机器人还是一个能干活的任务执行体。ChatBot 的核心是生成回答Agent 的核心是完成目标。看起来只差几个字但整个技术架构的复杂度完全不是一个量级。1.1 Agent 真正跑起来的三个前置条件一个能在生产环境里干活的 Agent在我看来至少要满足三个前置条件缺一个后面都会补课补到哭。第一个是工具调用能力。Agent 不能只靠模型自身的知识回答问题它必须能读取外部数据、调用第三方服务、操作数据库。比如用户让 Agent 查一下某个订单的物流状态它就得知道该调哪个接口、接口参数是什么、返回值怎么解析。模型本身只负责决定调哪个工具、传什么参数真正执行动作的是你写好的那层代码。第二个是任务编排能力。单个工具解决不了复杂问题Agent 必须能把一个大目标拆成多个子步骤并且能根据中间结果动态调整后续计划。这一步比大多数人想象的难得多模型对任务拆解的稳定性、中途出错后的恢复机制、多步骤间上下文保持都是要花大量精力打磨的东西。第三个是记忆能力。这个记忆分成两层一层是短期记忆也就是当前对话上下文里已经发生过的事另一层是长期记忆指的是跨会话、跨用户需要持久化的信息。很多 Agent 项目跑着跑着就失忆了上一轮说好的偏好这轮就忘本质上是记忆层设计得不对。1.2 AI Skills 在整个体系里扮演什么角色说完三个前置条件你可能已经感觉到了Agent 不是一个大模型就能装下的东西它是一个由多个模块拼装出来的系统。而 AI Skills 就是这套系统里让模型具备特定领域能力的关键封装方式。打个比方如果把 Agent 比作一个全能员工大模型是他的大脑那 Skills 就是他被训练好的标准操作流程。每个 Skill 都包含三个要素这个能力是什么、在什么条件下触发、具体怎么执行。比如你给客服 Agent 配置一个查订单的 Skill它内部定义了订单查询接口的调用方式、参数校验规则、超时处理、结果格式化输出。模型看到用户的意图后会从 Skills 列表里选中这个能力并执行。这样设计的好处非常明显能力可复用一个写好的 Skill 可以被多个 Agent 共享不用每个 Agent 重写一遍逻辑。行为可控制Skill 内部是确定性的代码逻辑不会像模型自由发挥那样出现不可控输出。排查更简单当 Agent 表现异常时可以快速定位是模型决策错了还是 Skill 执行出错了。我在实际项目中把 Skills 机制放到了整个 Agent 架构的核心位置效果比让模型自由调用函数稳定得多。2. 腾讯云上的底座准备服务器、Redis 与镜像仓库Agent 的代码逻辑再漂亮也得有地方跑。这一节是纯实操向的我会依次讲清楚服务器怎么选、Redis 怎么配、镜像仓库怎么用。腾讯云是我这次项目的基础运行环境下面的配置都是实际验证过的方案。2.1 服务器配置怎么选才不浪费钱Agent 服务本身的 CPU 和内存消耗取决于你承载的并发量和用不用大模型做实时推理。我在项目里用的是云端 API 调用大模型服务器只负责业务逻辑、工具调用编排和状态管理这种情况下 2核4G 的入门配置其实就够跑了。但有一点容易被忽略Agent 服务是 IO 密集型而不是计算密集型的。它大量时间在等待模型 API 返回、等待数据库响应、等待外部接口回包CPU 大部分时候是空闲的。所以选服务器时优先关注带宽和磁盘 IO而不是盲目堆 CPU。我的配置是 2核4G 5M 带宽 50G SSD跑一个生产环境的 Agent 服务加一个 Redis 实例完全够用。另外一个建议用腾讯云的轻量应用服务器还是云服务器 CVM如果只是个人项目或者小型业务轻量服务器的性价比更高如果要上生产、需要更灵活的网络配置和快照能力直接上 CVM。2.2 Redis 连接的坑与安全组配置Agent 的长期记忆、任务队列、会话状态我都存在 Redis 里。原因很简单Redis 的读写性能高、数据结构丰富而且天然支持过期时间设置非常适合存有时效性的上下文数据。我遇到的第一个坑就是修改 Redis 密码后重启服务失败。这个问题在腾讯云服务器上装 Redis 时特别常见原因通常是你改了配置文件里的requirepass但是忘记处理 Redis 的系统守护进程和服务管理配置导致重启时它读的还是旧的配置或者根本没有正确加载新密码。排查链路大概是这样的先确认配置文件改对了位置/etc/redis/redis.conf里的requirepass字段。查看 Redis 进程状态systemctl status redis或者直接 ps 查进程。如果报NOAUTH Authentication required说明服务起来了但你用的客户端没带密码不是服务启动失败。如果服务真的启动不了用redis-server /etc/redis/redis.conf前台启动看报错日志。还有一个隐藏坑是安全组规则。腾讯云的服务器有两层网络隔离安全组和操作系统防火墙。如果你在安全组里放通了 6379 端口但是 Redis 只绑定了127.0.0.1那远程访问还是会被拒绝。反之如果你把 Redis 绑定到了0.0.0.0方便远程访问但忘了设置强密码和防火墙规则那基本等于把数据裸奔在公网上。我的做法是内网部署就用内网 IP 访问安全组只对指定 IP 开放 6379 端口密码设置的复杂度要达到一般生产标准。2.3 用 Docker 推送镜像到腾讯云容器镜像服务Agent 服务跑在服务器上最省心的部署方式是打包成 Docker 镜像推到腾讯云的容器镜像服务TCR然后在服务器上拉取运行。这个流程看起来简单但有几个细节会影响体验。首先是按地域选择就近的镜像仓库。腾讯云 TCR 的企业版和个人版都有可用区的概念镜像仓库必须和你的服务器在同一地域否则内网拉取速度会很慢。我一开始没注意把镜像推到另一个地域的仓库每次拉镜像都要走公网几百 MB 的镜像等得人心态崩。其次是登录和推送命令。腾讯云 TCR 使用 Docker 登录时用户名是访问凭证里分配的密码是访问凭证的密钥串不是你腾讯云账号的密码。这个细节很多人第一次都会搞错。登录命令长这样docker login ccr.ccs.tencentyun.com --username 你的用户名 --password 你的访问凭证密钥登录成功后给本地镜像打标签并推送docker tag agent-service:latest ccr.ccs.tencentyun.com/your_namespace/agent-service:latest docker push ccr.ccs.tencentyun.com/your_namespace/agent-service:latest最后是镜像版本管理。不要每次都用 latest 标签生产环境必须用带版本号的标签方便回滚。我习惯用v1.2.3这样的语义化版本号推送成功后把版本号记录到发布文档里。3. 设计高质量 AI Skills从工具描述到任务闭环写一个能跑的 Skill 容易写一个关键时刻不掉链子的 Skill 难。这一节是整个 Agent 项目的核心我尽量把 Skill 设计的方法论和实际案例都交代清楚。3.1 Skill 的本质是把模型能力装进确定性流程先讲一个我在项目里反复体会到的道理模型擅长的是语义理解和决策判断不擅长的是精确执行。如果你让 Agent 自己通过自然语言去调接口、解析返回、处理异常结果一定不稳定。AI Skills 的核心价值就是把这些要求精确的部分用代码固化成流程模型只负责选择走哪条流程、传入哪些参数。举个例子。我要让客服 Agent 支持查订单最差的做法是让模型自己去拼 HTTP 请求因为模型会漏参数、会编造不存在的字段、会把返回结构理解错。好的做法是写一个queryOrder的工具函数用代码严格实现参数校验、HTTP 调用、异常处理、结果格式化然后把工具的功能、参数、返回值的描述告诉模型。模型只需要做两件事判断用户意图是否匹配查订单从对话中提取订单号。这就是 Skill 设计最关键的思想转换——从让模型做人变成让模型管理人让代码做事。3.2 一份可执行的 Skill 定义长什么样我在腾讯云这个项目里Skill 定义用的是 JSON Schema 风格的描述配合 Python 抽象基类实现。一份完整的 Skill 定义包含这几个部分name技能的唯一标识模型根据这个名字来选择调用。description一段清晰的自然语言描述说明这个技能做什么、什么时候该用、什么时候不该用。parameters参数的 JSON Schema包括每个参数的类型、含义、是否必填。execute实际执行逻辑接收参数后返回结构化的结果。下面是一个简化版的订单查询 Skill 描述结构使用的是 function calling 的标准格式{ type: function, function: { name: query_order, description: 根据订单号查询订单状态。当用户询问订单进展、物流信息、发货状态时使用。, parameters: { type: object, properties: { order_id: { type: string, description: 用户的订单号一般由字母和数字组成 } }, required: [order_id] } } }这里有个容易被忽视的重点description 要写清楚什么时候不该用。因为模型选工具的准确度直接取决于描述信息的质量写清楚边界反而能提升模型决策准确率。比如这个例子你可以加一句仅用于用户本人发起的订单查询如果用户询问其他人的订单请拒绝。3.3 我总结的 Skill 设计四步法经过几个项目的反复迭代我归纳出了一套 Skill 设计流程每一步都有明确产出物和验证方式。第一步是定义边界。确定你要解决的具体问题把一个复杂能力拆成若干单一职责的 Skill。比如订单服务不要做一个大而全的 Skill而是拆成查订单取消订单修改收货地址三个独立 Skill。拆细的好处是模型更容易判断该选哪个且每个 Skill 的入参校验更简单。第二步是写清楚描述。这一步直接决定模型的工具选择准确率。描述里要写清楚能力是什么、触发条件、常见表达方式、边界条件。我在项目里统计过描述包含负面条件的 Skill工具选择准确率能提升近 10 个百分点。第三步是设计健壮的执行逻辑。Skill 的执行代码里参数校验必须可失败外部接口的异常必须捕获超时必须有兜底。永远假设输入是不干净的、下游是不可靠的。你写的每个 Skill 都可能是运行 1000 次遇到一次极端情况的地方好的执行代码要把这次极端情况兜住。第四步是用测试用例固化行为。每个 Skill 至少要包含 5 到 10 个回归测试用例覆盖正常路径、边界参数、异常输入和超时情况。不要等全部 Skill 写完再测试每写一个 Skill 就补齐测试后面集成时能省掉大量联调时间。4. 框架选择与编排把 Skills 串成完整工作流单个 Skill 解决的是原子能力要把多个 Skill 组合起来完成复杂任务就需要框架和编排层。这一节讲我的选型思路和一个容易出问题的环节——模型接入层的统一管理。4.1 主流 Agent 框架的取舍目前市面上的 Agent 框架不算少挑的时候容易挑花眼。我自己以轻量、可控、易调试为原则筛选最终选择的是自研编排逻辑加上合适的开源组件而不是整套照搬某个重量级框架。做这个选择的原因有两条。第一条Agent 业务的个性化程度非常高你总有框架没覆盖到的业务逻辑。框架封装得越深自定义越痛苦而且框架升级时的兼容问题会消耗大量维护精力。第二条Agent 的核心逻辑其实不复杂主要就是循环决策-执行-观察结果自己用一两百行代码就能写清楚还不如把控制权握在自己手里。当然如果你刚起步、团队没有太多 Agent 开发经验选择成熟的框架作为起点是合理的。关键是搞清楚框架帮你解决了什么、它约束了什么别糊里糊涂被框架牵着走。我自己的编排核心简化后大概长这样def agent_loop(user_input, available_skills): messages build_messages(user_input) while True: response llm.chat(messages, toolsavailable_skills) if response.tool_calls: for call in response.tool_calls: result execute_skill(call.name, call.arguments) messages.append(tool_result_message(call, result)) else: return response.content模型每次返回tool_calls说明它决定调用工具执行完工具结果后把结果放回对话里再让模型继续判断。这个循环会一直持续到模型给出最终答案。看起来很简单但真正的复杂度在循环之外如何防止死循环、如何控制单次任务最大步数、工具执行结果超长怎么截断。4.2 用 litellm 做模型接入层的统一管理项目里踩过的一个大坑是模型接入层混乱。Agent 在开发阶段要用不同厂商的模型做对比测试不可能让业务代码直接绑定某一个厂商的 SDK。我的解决方案是接入 litellm 作为统一网关它在不改变外部接口的前提下把多个模型提供方的 API 格式统一成了同一种风格切换模型时只需在配置里改一个字段。实际用下来litellm 帮我解决了三个问题一是开发环境用便宜的小模型生产环境切大模型代码不用改二是部分模型厂商接口不稳定时可以用配置里的 fallback 机制自动切换备选模型三是统一的请求日志和 token 统计方便做成本追踪。启动一个 litellm 代理服务的配置示例model_list: - model_name: gpt-4o litellm_params: model: openai/gpt-4o api_key: your_api_key - model_name: deepseek-chat litellm_params: model: deepseek/deepseek-chat api_key: your_deepseek_key业务代码里直接连 litellm 的 OpenAI 兼容接口把base_url指到 litellm 服务model填你配置的model_name其他逻辑全部复用 OpenAI SDK。这个方案极大降低了成本评估和多模型对比的复杂度。4.3 记忆机制让 Agent 记住上一步干过什么如果说 Skills 是 Agent 的手脚那记忆就是 Agent 的短期工作台。我在项目里把记忆分成了三层每一层用不同的存储会话上下文存 Redis设置 30 分钟过期。存放当前会话最近的十几轮对话、模型决策过程、工具执行结果摘要。用户画像存 Redis 的 hash 结构存放用户的长期偏好、历史订单习惯等信息。这部分在用户明确授权的前提下写入Agent 回答时优先参考。任务日志存数据库或者对象存储记录每次任务的完整执行链路用于排查问题和优化迭代。记忆层设计最关键的一点是控制在上下文窗口内。模型能接收的 tokens 有限你不可能把所有历史对话都塞进去。我的做法是把工具执行结果做摘要后再放回上下文而不是直接丢原始返回值。例如查订单返回了 20 个字段但模型决策时只需要订单状态和预计送达时间那就截断成 3 个字段再放回上下文既省 tokens 又减少了干扰信息。5. 部署实战从本地测试到云端上线写完代码只是第一步真正让 Agent 稳定运行还需要把部署流水线和运行环境弄扎实。这一节我将按打包到上线的实际顺序展开。5.1 Docker 化打包的注意事项Agent 服务容器化的第一原则是镜像要小、启动要快。我用的基础镜像是python:3.11-slim最终镜像体积控制在 500 MB 以内。如果直接把开发环境里的依赖全部装进镜像体积会膨胀到 1G 以上拉取和启动都慢。有一个特别容易被忽略的坑时区设置。镜像默认是 UTC 时区如果你的 Agent 生成的日志、任务计划里用了本地时间就会出现时间偏差。我的 Dockerfile 里加了这几行ENV TZAsia/Shanghai RUN ln -snf /usr/share/zoneinfo/$TZ /etc/localtime echo $TZ /etc/timezone另外不要在镜像里写入任何敏感信息。API 密钥、数据库密码、Redis 密码必须通过环境变量或密钥管理服务注入。镜像一旦被推送到镜像仓库里面写死的密钥就等于泄露了。5.2 启动参数、环境变量与进程守护容器启动命令和环境变量的设计我踩过一次印象很深的坑。当时把REDIS_HOST、REDIS_PORT、数据库连接串等十几个变量都塞到启动命令里结果有一次服务器重启后命令被截断了排查了半天才发现是变量太多太长导致的问题。后来我把所有配置项移到启动脚本里用.env文件维护默认值容器启动时逐一加载。进程守护方面我用的是 Docker 自带的--restart策略。核心服务设置restartalways这样容器崩溃或服务器重启后能自动拉起不需要额外写脚本。如果同一个服务器上跑多个服务建议用docker-compose管理Redis、Agent 服务、litellm 网关一次启动。5.3 上线后的第一轮压测结果服务上线后我做了三轮基础压测。第一轮是并发测试模拟 20 个用户同时发起对话请求观察 Agent 服务的响应时间和错误率。第一轮结果不太理想p95延迟接近 8 秒原因是部分工具调用串行等待且有外部接口响应超时。后来把工具调用改成可配置的超时时间并让能并行的调用走并发逻辑p95降到了 3.2 秒。第二轮测的是长会话稳定性。连续进行 15 轮以上的多轮对话后观察 Agent 是否出现上下文丢失、回答漂移、重复调用工具的问题。发现两个 bug一个是当上下文 token 数接近窗口上限时历史信息被截断导致模型忘记用户前面提到的关键约束另一个是某些情况下模型会反复调用同一个失败的 Skill形成死循环。修复方式分别是加上下文压缩逻辑和设置单次任务最大步数限制。第三轮是异常恢复测试。手动杀掉 Agent 服务进程、停掉 Redis观察恢复情况和数据一致性。测试结果是 Docker 自动拉起服务约 10 秒机制正常但发现任务进度信息存在丢数据的风险原因是部分状态只存在内存里没有及时落 Redis。后来设计了状态快照机制任务执行过程中每完成一个步骤就更新状态缓存。6. 我在这个项目里踩过的坑和最终心得下面收敛一下把这次腾讯云 Agent 项目里踩过的几个典型问题集中讲一遍再给准备入坑的朋友几条实在建议。6.1 五个真实踩坑记录第一个坑是最常见的模型乱调工具。我给 Agent 配了 8 个 Skill它在测试阶段偶尔会选错。查了日志后发现问题往往出在 Skill 描述上。有的描述写得太抽象模型理解不了触发条件有的描述里有两个 Skill 功能重叠模型不知道该选哪个。修复方式就是重新拆 Skill、细化描述、明确边界。这个工具选择准确率要通过日志持续监控而不是上线时看一次就完。第二个坑是Agent 被外部接口带偏。工具执行返回的结果里如果包含恶意或者异常内容模型可能会被诱导执行不该做的事。我一开始没做工具输出过滤有次测试时模型读取了一个网页内容被网页里的提示词注入影响差点按照恶意指令走了错误分支。后来在处理每个工具的输出时都加了敏感指令过滤并且严格限制工具输出注入上下文的数据长度。第三个坑是Redis 缓存和会话不同步。用户在一个会话里修改了偏好设置另一个会话没感知出现人格分裂的情况。原因是用户画像只存了一份但会话上下文里没有强制刷新。这里建议在做 Agent 状态的时候要清楚哪个信息是会话级的哪个是用户级的每一轮对话开始前从 Redis 拉一次最新画像。第四个坑是模型服务商限流导致 Agent 卡死。Agent 一个任务可能要调用多次模型 API如果并发一上来API 报限流错误编排循环就一直在重试任务进度卡住。后来我在模型接入层加了重试退避机制并且对每个任务做了模型调用次数的配额限制超出后主动结束任务并提示用户稍后再试。第五个坑是日志和追踪缺失导致问题难排查。Agent 的决策链路复杂任何一个环节出了问题如果只看最终回答根本定位不了。后来我把每一步模型决策、工具调用、返回结果都记录成结构化的 trace 日志配合统一的 request_id排查问题从猜变成了看日志链路。6.2 给准备入坑 Agent 开发的人几条建议如果你准备在腾讯云上开始自己的 Agent 项目根据我这次的实践给你这几条建议第一不要把第一个版本做太复杂。先用最少的 Skill 跑通全链路模型接入、工具调用、记忆、部署、日志。跑通之后再加复杂能力不然问题混在一起根本定位不到根因。第二日志和可观测性要提前设计。Agent 项目的调试难度是普通 Web 服务的很多倍没有完整的 trace 链路排查问题效率极低。我建议从第一天就把请求日志、工具调用日志、成本统计这三大块接入好。第三预留模型切换的抽象层。不要只绑定一家模型服务商用 litellm 这类统一网关或者自己在代码里封装一层接 口。模型能力迭代快今天最优的模型可能三个月后就不是了切换成本太高会拖慢迭代速度。第四安全底线不能放松。Agent 拥有执行工具的权力就等于给某个入口开放了调用外部服务的能力。所有 Skill 执行前都要做权限校验工具输出要做过滤敏感操作要做二次确认同时做好操作审计。这些不是上线前临时补的而是架构设计阶段就要纳入的。整个项目做下来我的体会是Agent 开发最大的挑战不是模型能力不够而是如何用系统工程的方法把模型的不确定性约束在可控范围。Skill 设计、编排逻辑、记忆管理、部署运维每一个环节都在做同一件事——把不可控的模型行为逐步收敛成稳定可靠的产品能力。这条路没有捷径靠的是一个个决策的积累和一次次线上问题的打磨。