从标题里的“全能 Agent 养成记”这几个字其实就能嗅到一类很典型的项目味道不满足于让 AI 只做聊天框而是要它真正去执行、去调用、去交付结果。过去一年多我把不少时间砸在腾讯云上做这类 Agent 项目最大的感触是市面上讲 Agent 的教程很多但真正把 AI Skills 当核心工程做的人太少。Agent 不是“某个更强的大模型”Agent 是模型、工具、记忆、编排共同作用下长出来的执行体。这篇文章我就把这套从零到一、从能跑到敢上的实践链路完整复盘一遍。适合正在规划 Agent 开发学习路线、正在设计 agent skill、或者被“技能怎么拆才合理”卡住的人。先说结论如果只想做一个偶尔能被调用的玩具 Agent不需要读这篇。但如果你想做的是一个能处理多种任务、可以被稳定部署在云服务器、还要面对真实用户的安全与超时问题的全能型 Agent那下面这些从教训里长出来的最佳实践应该能帮你少走不少弯路。1. 先拆概念Agent、AI Skill、Tool别把它们揉成一团刚开始学 Agent 开发的人十有八九会被“这个跟那个有什么区别”搞糊涂。打开各种论坛一边是 agent framework一边是 agent skills底部还压着一个 tool。你要是用搜索引擎查“skill 和 agent 的区别”“tool 和 agent 的区别”会发现答案五花八门。我在项目里摸索了很久最终把概念收敛成一套自己的定义后面所有设计都基于这套定义展开。1.1 为什么连“Skill 和 Agent 的区别”都能吵起来因为很多教程把概念描述在了同一个维度上这本身就是误导。我的理解是Tool 是一个最小可执行动作比如“发送 HTTP 请求”“执行一段 SQL”“读一个文件”Skill 是一个语义完整、可以被模型理解并自动调度的能力模块一个 Skill 内部通常会组合多个 Tool并且带有自己的约束条件、执行步骤和输出规范Agent 则是“会判断什么时候调用哪个 Skill、如何拆解任务、如何在失败后补救”的运行主体。Tool 是手Skill 是一套熟练的动作组合Agent 是站在旁边知道你该先洗手还是先切菜的师傅。很多人做 Agent 翻车不是因为模型差而是把这三层全揉成了一团。代码里写了几十个 function然后告诉模型“你可以用这些 function 完成任务”。结果是模型每次都在几百个函数里做选择每次调用参数都可能出错。后来我们改成了“只把 Skill 层暴露给模型”Tool 层藏在 Skill 内部调用准确率立刻高了一个档次。这也是 Agent 架构设计里面最值得先想清楚的一件事到底让模型看到多大的决策面。1.2 给技能定“边界”比函数大一点比 Agent 小一点Skill 粒度怎么定是一个全能 Agent 是否好用的分水岭。太细模型要在“先查用户、再查订单、再算折扣、再下订单”四个技能之间反复横跳每一步都有失败概率整体成功率会指数下降太粗一个技能体内塞下整条业务链路一旦某个环节发生变化你就要改动一大坨代码复用性也基本归零。我自己的判断标准有四个可测试技能有明确的输入输出可以单独跑通一个单元测试可复用不止一个场景需要它而不是某个一次性脚本换了个名字有语义边界技能名称和描述能让模型一眼看出“这个技能管什么、不管什么”内部步骤可失败、可回滚如果技能内部第 3 步挂了至少能返回一个明确定位到步骤的错误码。举一个比较贴近项目的例子做日报机器人时很多人会拆出“采集业务数据”“调用模型生成分析文本”“推送到群里”三个独立技能然后期望模型自主编排。听起来很灵活实际上模型经常在第 2 步生成摘要后忘掉第 3 步的发送动作或者把采集参数的格式搞错。最后我们直接把“发布一次日报”封装成一个 Skill内部再由代码依次完成数据采集、生成、推送三个环节。模型只需要理解“用户要发日报就调 publish_daily_report”剩下的编排由代码稳住。这就是比函数大一点、比 Agent 小一点的典型例子。1.3 技能盘点模板先画地图再动工开始写第一个 Skill 之前我强烈建议先做一张能力盘点表不要想到哪写到哪。这张表的作用不是给机器看而是逼你把自己的系统边界梳理清楚。通常我会列这些列技能名称、一句话职责、会调用的内部系统、入参摘要、出参摘要、失败场景、运行成本等级。技能名称职责边界依赖服务入参摘要出参摘要失败场景成本等级fetch_web_content抓取指定网页正文网页抓取服务、内容清洗模块url、最大字符数清洗后的正文、标题、抓取状态目标站点超时、反爬拦截低search_knowledge_base在内部知识库中检索片段向量库、Embedding 接口查询文本、TopK命中片段列表及相似度向量库不可用中generate_video_depth对视频做深度估计并产出可视化结果GPU 推理服务、对象存储视频 URL、抽帧频率深度图序列的存储地址GPU 资源不足、视频无法解码高盘点完之后你会发现一个反直觉的现象同一个 Agent 里不能只放低成本技能。如果所有 Skill 都是外部网页抓取这类轻操作那这个 Agent 根本没有处理复杂任务的后劲但如果一上来就挂一堆 GPU 重推理技能每次意图误判都会烧钱。所以盘点表的最后一列“成本等级”非常关键后面做安全限流和预算控制的时候全靠它来设计策略。2. 云端家底怎么搭一台机器、一组端口、一个域名背后的坑概念盘完开始进入腾讯云环境搭建环节。这一步被我严重低估过。以前总以为写 Agent 最重要的是模型和 Prompt等真正要把 Agent 暴露给外部访问的时候才发现云资源编排、端口安全、域名解析这些“底层杂事”会占掉项目前期三分之一的时间。尤其是 AI Skills 这种东西一旦引入异步回调光是把回调链路打通就够折腾一阵子。2.1 算力选型的现实考量不是越贵越好先谈服务器。很多第一次做 Agent 项目的朋友上来就挑 GPU 实例觉得要跑模型就得上显卡。实测下来如果你的 Agent 主流程是调用云端模型 API同时只做编排、记忆存储、工具调用那么一台 8 核 16G 内存的中等 CPU 云服务器已经够用。模型推理的算力都在模型服务方那边你自己这台机器主要扛的是并发请求和技能逻辑。真正需要 GPU 的场景是你打算在本地部署 Embedding 模型、Rerank 模型或者跑视觉类的 AI Skill。这里也解释了为什么后来我会单独做“视频深度估计”这类技能它需要抽帧、推理、再编码输出光靠 CPU 根本没办法做实时响应。这种任务你至少需要一张 16G 以上显存的推理卡而且要先确认显存能不能容纳模型和中间张量层。云厂商的 GPU 实例有各种规格别一上来就买最贵的先看几个关键指标显存、GPU 架构、显存带宽、实例是否支持按量计费。早期验证阶段按量计费比包年包月理智很多跑通一个深度估计技能的完整流程后再转包月也不迟。不过更常见的情况是 CPU 和 GPU 混合拓扑Agent 主服务放在 CPU 实例上GPU 实例通过内网或对象存储来接收重任务。这样避免了一个视频深度估计任务把整个 Agent 的响应卡死。后面我会专门讲到这种异步任务设计。2.2 安全组放行与“开放所有端口”的诱惑很多新手照着帖子配服务器第一件事就是去云控制台把安全组全放通美其名曰“免得后面还要加端口麻烦”。这是一个非常大的坑。先说明一下云服务器上的防火墙最外层叫安全组它是个白名单机制默认拒绝所有入站流量。你只开通 80 和 443那么其他端口在公网就是不可达的。这种不可达反而是一种保护因为 Agent 服务如果监听在一个调试端口上且没有加鉴权被公网扫到后很容易变成别人调用你模型 API 的肉鸡。我实际使用的端口放行策略很简单一共不超过五个入站规则端口用途建议来源22SSH 远程运维只允许公司出口 IP 或跳板机 IP80HTTP 访问做 Lets Encrypt 验证或重定向到 HTTPS全网 0.0.0.0/0443HTTPS 正式入口全网 0.0.0.0/09000内网应用服务端口仅通过 Nginx 反向代理访问建议不对公网开放只绑定内网或通过安全组限制如果确实需要临时调试一个 Agent 服务端口也不要直接在安全组里放行 0.0.0.0/0更不要用“开放所有端口”那种按钮。正确做法是临时加一条来源为“当前你本机公网 IP”的规则调试完立刻删掉。这个习惯看起来啰嗦但它能拦截掉 99% 的扫描器攻击。安全组不是配置一次就完事的东西它应该跟着版本走每次上线前都检查一遍。另外很多人在云安全组之外还会装 UFW 或 firewalld。两层防火墙之间如果没有规划好经常出现“安全组放行了但服务还是连不上”这种排查噩梦。我的习惯是只信任一层如果腾讯云安全组已经做了白名单实例内部 UFW 就不必再来一套复杂策略否则出问题时会怀疑人生。2.3 二级域名、回调地址与 API 网关之间的配合Agent 服务和普通 Web API 不同的一点是它经常需要让外部系统把结果“送回来”。比如某个 AI Skill 启动了一个异步任务任务处理完要通过 Webhook 回调你的 Agent 服务又比如企业微信、钉钉这类应用要发消息给 Agent也要求你的服务地址是一个公网可访问的 HTTPS 域名。这就绕不开域名配置。“腾讯云怎么申请二级域名”这个问题本质是云解析的操作。如果你已经有一个域名并不需要额外申请什么只需要添加一条解析记录。我通常会在域名解析控制台新建一个 A 记录主机记录填agent记录值填云服务器公网 IP这样agent.你的域名.com就指向了服务器。之后用 Nginx 在这个二级域名上配置 SSL 证书再把请求反向代理到本机的 Agent 服务端口整套链路就通了。需要注意的细节是回调地址一定要用 HTTPS不能用裸 IP。很多大平台 Webhook 强制要求 HTTPS裸 IP 证书也不是不能签但维护起来麻烦。我用的是免费证书方案三个月续期一次配合定时任务自动续期基本不用手工管。还有一个经验是不要把 Agent 的入口地址做成动态解析的 DDNS虽然家里的宽带也能跑但云服务器的固定公网 IP 加二级域名才是稳定可靠的做法否则用户侧的 Webhook 配置会因为 IP 变动而全部失效。这套家底搭好后你的 Agent 才算是有了立足之地。3. 把一个“神”技能拆成能交给 Agent 执行的规格有了机器后面的问题就是 AI Skills 本身怎么设计。我用一个词来概括写过很多个烂技能后的体会规格。技能不是给程序员写的一个普通函数它是给“一个看不见摸不着的模型”看的接口。模型没有读过你的代码它只看到技能名、描述、参数列表。所以一切让它困惑的描述最后都会变成错误的参数输入、错误的技能选择。全流程里把 Skill 描述写准确带来的效果提升可能比换一个参数更大的模型还明显。3.1 Skill 描述写不好再强的模型也救不了你在功能调用场景里模型的行为逻辑本质是“读描述做匹配”。如果技能描述写得模棱两可模型就会在多个相似技能之间摇摆最后选错。常见的坏描述长这样“查数据”“处理用户问题”“工具函数”。好描述应该包含触发时机、服务目标、关键限制。我写描述的时候会刻意遵循一个公式当用户想达成 X 场景下的 Y 目标可调用该技能如果输入不符合条件 Z请直接返回错误不要编造结果。举个例子一个抓网页的技能描述可以写成fetch_web_content 技能用于抓取指定 URL 对应的正文内容。当用户提到“看看这个链接讲了什么”“把某篇文章总结一下”“需要获取某个网页的文本信息”时调用该技能。如果 URL 不是 http/https 协议或者目标站点在 10 秒内无响应返回可读错误不得伪造网页内容。这段描述里有触发场景、有参数约束、有失败的处理要求。模型读到后会更容易在第一次就做对。同样的代码逻辑描述从一句话变成三段话之后我们的功能调用成功率大约从 60% 提升到了 85%。这里有个容易被忽略的隐藏坑技能的 description 会占用模型上下文。技能一多每次都把所有 Skill 描述发送给模型Tokens 成本会直线上升。因此描述里不要写废话比如“这是一个非常重要且强大的功能”这类修饰词应当直接被砍掉。要让每个字都服务于“让模型做出正确选择”这一目标。3.2 技能入参与出参生产级 Agent 的“结算单”参数定义是另一大坑。很多平台支持 JSON Schema 定义参数很多人就草草写个 type 和 required。但实际生产过程中模型会按照 Schema 的 description 来生成参数所以参数的 description 同样要写清楚最好带上取值范围和示例值。{ type: object, properties: { url: { type: string, description: 需要抓取的完整网页链接必须包含协议头例如 https://example.com/news/123, examples: [https://example.com/news/123] }, max_chars: { type: integer, description: 最多返回多少字符默认 8000最大不要超过 20000, default: 8000 } }, required: [url] }出参设计同样要有统一格式。这里的核心思路是模型通过工具调用拿到的结果不能是一堆原始文本就完事。原始文本会导致两个问题一是模型需要花大量 Tokens 去理解“这次调用到底成功没有”二是出错时模型看不到可读错误码就会自己脑补一个成功结果。所以我把 Skill 的返回统一设计为 JSON永远包含四个部分{ status: success, data: { title: 页面标题, content: 清洗后的正文, url: 原始链接 }, error: null, meta: { duration_ms: 235, from_cache: false } }如果状态是 errorerror 字段里要有 code 和 message比如{code: FETCH_TIMEOUT, message: 目标站点 10 秒内未响应}。别小看这个“结算单”设计它是模型能否正确决策下一步的关键一个清晰的 error message会让模型知道“这个技能没有成功我不能基于它编结论”它能直接避免大量胡说八道的回复。3.3 两类最容易写烂的 Skill巨型脚本和连环调用第一类烂 Skill是把一套完整业务流程硬塞进一个技能里参数多达二十个内部有各种 if 分支代码上千行。这种技能每次改动都要做全量回归而且很难测任何一步失败都只能给一个笼统的错误。它违背了前面说的“可测试”原则。第二类烂 Skill是 Skill 与 Skill 之间的调用链编写得没有纪律。Skill A 内部去调用 Skill BB 再去调用 C。这种写法在 Agent 运行时会带来一个严重问题一旦某个 Skill 失败错误信息要跨好几层传播最后模型根本不知道是哪个环节出了问题。我后来给团队定了一条规矩Skill 只能调用 Tool不允许 Skill 之间互相直接调用。Skill 之间的协作应该交给上层的 Agent 编排逻辑由模型判断是否需要先调用 A 再调用 B。这两条规定让我少踩了很多坑也降低了后面上线排障的难度。4. Load/Unload技能仓库和动态注册机制技能写得再多如果全部一股脑塞给模型照样会把人“撑死”。一个全能 Agent 要面对的场景可能很多但单次对话通常只需要其中几个技能。如何让 Agent“在需要时想起对应的技能”而不是“平时背下所有技能”是技能仓库机制要解决的核心问题。4.1 用代码实现一个轻量 Skill Registry我推荐一开始就为技能做一个注册中心哪怕你只有两三个技能。这能避免日后把所有技能堆在一张大 switch-case 表里的尴尬。代码实现很轻量核心定义如下class BaseSkill: name: str description: str parameters: dict {} async def execute(self, params: dict) - dict: raise NotImplementedError class SkillRegistry: def __init__(self): self._skills {} def register(self, skill: BaseSkill) - None: self._skills[skill.name] skill def get(self, name: str) - BaseSkill: return self._skills.get(name) def list_tool_schemas(self) - list[dict]: schemas [] for skill in self._skills.values(): schemas.append({ type: function, function: { name: skill.name, description: skill.description, parameters: skill.parameters, }, }) return schemas这个注册中心做的事很少登记、按名字取出、转成模型能理解的功能 Schema。它的好处是当你引入新技能时只需要新增一个类并注册Agent 侧不需要改动。而且你可以做成动态加载把技能的定义存储在一个外部文件或配置表里服务启动时扫描并注册。这样每一类技能本质上就是一个插件做到“即插即用”。4.2 让模型“点菜”路由选择技能的 Prompt 设计有了注册中心下一步是设计路由。在纯 Function Calling 模式下模型会自己根据用户输入去匹配工具所以路由策略的核心隐藏在系统提示词里。我之前用过一个简单有效的提示词模板你是一个任务执行型 Agent。下面是你可以调用的技能列表。请根据用户意图选择合适的技能。如果用户请求明显不在任何技能职责范围内不要编造技能名直接回复“我当前没有合适的能力处理这个请求”。这段提示词给模型划了一条红线不要乱编技能名。实测发现模型有一定概率自行发明工具名比如明明没有“delete_user”这个技能它却按语义猜测生成了一个调用。注册中心收到未知技能名时不能静默忽略也不应该直接报错而是要把它当成一次路由异常记录到日志里方便你定位是描述冲突还是幻觉问题。还有一点是技能路由不要只靠一次模型调用。如果技能内部逻辑复杂你可以让模型先做意图识别输出一个 JSON 格式的计划再按计划执行。这种方式多一次往返但能看到 Agent 的决策链路排查问题时非常方便。比如下面这个结构{ thought: 用户想分析一个网页并且需要保存结果所以应该先抓取网页再调用摘要生成最后保存, steps: [ {skill: fetch_web_content, params: {url: https://example.com}}, {skill: summarize_text, params: {max_length: 500}} ] }我建议在小流量阶段就把这种中间计划输出出来放在日志里观察。只有当你确认模型每次的计划都符合预期再切换成纯 Function Calling 的快速路径否则在调用链出错时你将面对一个行为黑盒。4.3 多模态技能接入示例视频深度估计是如何变成 AI Skills 的很多人在想“Agent 不就是处理文字吗多模态技能到底怎么加”。这里用一个真实案例来说明让 Agent 具备视频空间感知能力比如判断一段视频里哪些物体更靠近摄像头。这个任务在计算机视觉里叫视频深度估计。第一步这个 Agent 需要接收一个视频 URL然后抽帧。抽帧不能把每秒所有帧全抽出来成本和延迟都扛不住通常按场景切换或按固定间隔抽关键帧具体频率取决于视频内容变化速度。第二步把帧图送给单目深度估计模型产出深度图。这个模型需要 GPU 推理。我之前第一次做的时候天真地让 Agent 主服务同步调用 GPU 推理接口结果一次任务耗时 40 秒网关早超时了。后来改成异步架构Agent 接到任务后立刻返回“任务已受理”和任务 ID后台队列消费视频抽帧后批量推理最终把深度图打包上传对象存储再用 Webhook 通知用户结果。这就是多模态 AI Skill 在工程落地上最核心的经验不要把 GPU 任务放进 Web 请求的同步链路。重任务必须异步化配合消息队列和回调机制完成。技能接口被模型调用后立刻获得一个 task_id模型可以告诉用户“任务正在处理中”而不是傻傻等一个不可预测的响应。这也是“全能 Agent”能同时处理多个重任务而不被拖垮的关键设计。5. 记忆与上下文让同一个 Agent 像老同事而不是金鱼让 Agent“全能”的另一半是让它“长记性”。一个没有任何记忆的 Agent无论技能多丰富每次对话都像和一个刚入职的实习生说话他明明昨天刚整理过一份资料今天又会从头问起。做过几轮之后我越来越觉得记忆模块的设计水平决定了 Agent 长期可用还是只能活在 demo 里。5.1 为什么上下文窗口再大也替代不了记忆有人会质疑“现在模型上下文窗口已经很大了把所有历史聊天记录都塞进去不就行了吗”表面上看有道理实际操作后你就会发现两个问题。第一是成本上万 Tokens 的历史记录每次都要重新发送给大模型按一天几千次请求来算这部分开销会高得吓人。第二是注意力稀释大模型面对海量上下文时对关键信号的捕捉能力会下降无关历史反而盖住了当前真正重要的信息。这就像一张桌子桌面再大也是工作台不是仓库。你不能把过去半年的所有文件都堆在桌面上正确做法是定期归档、建立索引工作时只把当前任务相关的几份文件抽到桌面上。上下文窗口就是桌面记忆系统就是档案柜。5.2 短时记忆、长时记忆与向量库的三角关系我实际搭的记忆系统分三层第一层是运行时上下文只保存当前对话最近几轮消息并且每轮结束时做一次摘要压缩把早期对话变成几句话的 summary。第二层是长期记忆库保存真正重要的用户偏好、项目状态、关键事实配合去重和过期策略。第三层是向量索引长期记忆写入时都会做 Embedding用户发起新请求时先从向量库检索与本次意图最相关的记忆片段放进本次的上下文。这三层看起来复杂早期完全没有必要上一套重分布式系统。我刚开始只用了 SQLite 存结构化记忆配合一个开源向量索引库来做检索几千条记忆规模也能跑得很好。真正需要升级是当你发现检索延迟超过几百毫秒或者量级到达几十万条之后才需要考虑的事。很多 Agent 项目死于过早引入重型中间件这一点值得反复提。5.3 减少记忆写入噪音的一个过滤策略记忆系统最大的风险不是“存不下来”而是“什么都存”。如果 Agent 把每轮普通对话都写进长期记忆很快档案柜里就会堆满垃圾检索时召回的内容全是无关的日常闲聊。我设计了一个三问过滤器只有当三个问题都通过时才允许写入长期记忆这条信息在五次或更多次对话后还有价值吗如果丢失这条信息会不会导致 Agent 重复犯同一个错误或重复问同一个问题未来是否可以通过明确的关键词检索到这条信息用这个过滤器跑了几个月后记忆库里的数据质量明显比之前不设门槛时高一个级别。用户问过“帮我记录一下报告格式以后都用 PDF”这种属于显式偏好该记用户随口说了句“今天天气不错”就不该记。另外记忆里存放的是事实和偏好而不是原始对话逐字稿。模型判断出值得记的内容后需要先将它转写成结构化短句再入库这样既省存储空间也更容易被检索到。当然涉及密码、密钥、身份证号这类敏感信息压根就不应该写入长期记忆这一点在合规和伦理上都应当成为硬性规定。6. 编排与网关当“单兵”变成“作战小队”只有一个 Agent 加一堆技能很多任务也能完成但到一定复杂度之后你会碰到瓶颈有的任务需要多个技能按严格顺序执行有的技能的中间结果要影响下一步的参数甚至有些任务需要让两个 Agent 角色分头协作。这时候把“单兵 Agent”升级成“编排体系”就成了一堂必修课。6.1 一个个技能最终怎么长成 Agent技能仓库里的技能再多也只是零件真正让它们成为一个整体的是编排层。一个全能 Agent 本质上是一个执行循环接收用户请求理解意图生成执行计划按计划调用技能拿到结果后判断是否继续还是已经可以生成最终答案。我倾向把编排层分成两个部分模型负责“决策”部分代码负责“稳定”部分。模型说“先查天气再决定是否提醒用户带伞”这个判断是决策但是一旦决定要查天气怎么把城市名解析成查询参数、怎么处理天气 API 的异常、怎么在超时后重试这些通通应该由代码模板完成不能依赖模型自由发挥。编排阶段谁负责产物意图分析模型一句话目标 是否可用现有技能完成技能选择模型 注册中心有序的技能调用列表参数构造代码模板 模型补参符合 JSON Schema 的参数技能执行技能实现代码统一 output JSON结果校验规则引擎success/error/retry 判断最终回复模型面向用户的自然语言回答这张表格是整个编排层的最小骨架直接照着搭即可。很多开源 Agent 框架做了一大堆复杂抽象但本质上仍然在做这张表格里的事情。把这个逻辑吃透看框架源码也会轻松很多。6.2 框架选型与自研之间的平衡我见过不少人受社区氛围影响一上来就选重量级 Agent 框架结果出了问题很难排查因为框架替你隐藏了太多细节。所以我的建议是从一个最小编排内核开始自研等确定需要联网搜索、多角色辩论、自动规划这些复杂能力时再考虑引入专门框架。自研的编排内核不需要太复杂可以用一个状态机来表达。状态包括等待输入、规划中、执行技能、等待人工确认、生成回复、任务失败。每个技能执行完状态机根据返回值决定下一个状态。如果技能返回 success继续下一步如果返回 error模型需要决定是换参数重试、换技能还是终止并向用户解释原因。这个逻辑代码量不大但会让你的 Agent 行为