1. Agent有大脑，但很多时候缺手脚
做AI Agent相关的开发有一段时间了，一个很深的感触是：模型本身的能力再强，真正跑起来的时候，最卡脖子的往往不是"思考"环节，而是"行动"环节。我在一个面向内部团队的Agent项目里就遇到过这样的尴尬——模型很聪明，能理解需求，能把复杂的问题拆解成步骤，但到了需要它实际做点什么的时候，它基本没招。
比如让它"查一下测试服务器最近的负载情况"或者"帮我跑一下某个目录下的回归测试脚本"。它可以给你一段建议，告诉你应该怎么看、怎么跑，甚至把命令都拼出来了，但就是不会自己去执行。原因很简单：模型本身没有访问服务器、没有执行命令的通道。这就好比一个人脑袋转得飞快，但手脚被绑住，想法只能在脑子里打转。结论很直接：Agent的核心竞争力，不在思考链有多惊艳，而在脚下有多少双能落地干活的"手"。
这时候就需要一个可插拔的技能体系，也就是把Agent需要的能力按标准化的方式包起来，让模型在对话中能按需调用。我做的这套"agent-skills"，就是围绕这个目标展开的——它不算什么复杂框架，核心就三件事：技能的注册、技能的触发、技能的执行。说得直白点，我做了一个"工具柜"，每一个技能是一个抽屉，抽屉上写清楚了"我是干什么的、需要什么参数、能返回什么结果"，模型在对话过程中按需求自己去开抽屉。
这套东西适合谁用？对正在搭Agent原型、想把LLM真正接进业务链路里、但不想每次都去啃各种底层函数调用细节的开发者，参考价值比较大。它的好处在于：技能和模型之间是松耦合的，技能的接入不要求改模型prompt，只要把技能清单告诉模型即可。后面我会把设计思路、主体结构、踩坑经历都拆开讲。这些坑基本都不在模型那边，而在技能设计和运行时调度上，新手一踩一个准。
2. "技能"到底是个什么东西：我把它定义成四条规则的集合
既然要做一套技能体系，先把"技能"这个词定义清楚，否则后面啥都白谈。很多初级方案把技能当成"一段prompt + 一个函数"，看起来简单，实际运行起来全是洞。比如模型想调用技能，但参数传得不对；或者技能返回了一堆原始文本，模型根本没法提取关键信息。这类问题几乎都不是模型蠢，而是技能定义得模棱两可，给模型的"操作说明书"写得不清不楚。
2.1 一个技能由什么组成
我在这个项目里把技能抽象成四个组成部分：技能索引、参数规范、执行逻辑、返回结果。这四个部分各司其职，缺一个后面就得补课。
技能索引差不多就是"抽屉上的标签"。给技能一个唯一名称和一句人话描述。名字尽量用动词开头，描述里说清楚它在什么时候用、能干什么。比如一个查服务器状态的技能，名字叫get_server_status，描述就可以写成"查询指定服务器CPU、内存、磁盘使用率，用于需要了解机器负载的场景"。
参数规范特别容易被忽视。LLM调用技能，不是像传统函数那样由程序员传参数，而是由模型从对话内容里自己提取参数。所以参数的名称、类型、是否必填、取值范围，都必须写得很清楚。用结构化的JSON Schema来描述，模型的提取准确率会明显高一个档次。
执行逻辑就是真正干活的代码。它接收模型传过来的参数，经过校验、执行实际操作后，返回一个结构化的结果。这里的关键点是结果要给模型留好"咀嚼空间"——如果返回的是大段日志，模型容易被淹死；如果返回的是结构化摘要，模型就能很快形成结论。
返回结果最好用JSON承载，里面包含状态、数据、以及给用户看的最终信息。设计得好的话，模型拿到结果后基本不用再猜，直接整理成自然语言反馈给用户就行。
可能有人觉得这四步太直白，没有新鲜感。但实际去写的时候就会发现，绝大多数"技能不听话"的坑，都能追溯到这四个环节里某一环没做干净。
2.2 为什么不能把技能全塞进系统提示词里
最开始的版本，我确实干过这种"暴力"事：把所有技能说明塞进系统提示词，让模型自己理解、自己想办法调。技能少的时候还好，三五个技能时模型勉强应付得过来。技能一多就出问题了——提示词被塞得又长又臭，中间几层技能描述被模型忽略。更麻烦的是，一旦技能内容调整，整个提示词就要重新生成，调试成本极高。
技能和系统提示词解耦，是这套设计里最重要的一步。技能清单可以用一份独立的JSON传给模型，作为工具定义的一部分。模型看到的是"当前可用技能列表"，而不是"一大坨夹杂在人格设定里的操作说明"。这既保住了提示词的简洁，也方便动态增删技能。
后来我甚至把技能触发做成了类似函数调用的协议格式：模型在生成回复时，如果判断需要某个技能，会输出一个结构化的调用标记，包含技能名和参数。然后由后端拦截这个标记，执行对应技能，把结果回传。整个过程对模型来说就像"打了个电话"，打完电话拿到回执再继续对话。这个模式兼容性很好，主流模型都能适配，现在很多Agent框架底层也是这么做的。
这套定义方式，核心逻辑就是让技能变成"自描述的、可独立装卸的部件"，模型只需要看懂描述就会用，不需要懂内部代码。听起来简单，但当技能数量从几个涨到几十个的时候，这个抽象的价值就非常明显了。
3. 一个技能从零到一是怎么走通的：以服务器状态查询为例
聊定义容易，落到具体实现才能看到细节里的魔鬼。我拿这个项目里最常用的一个技能来完整走一遍——查询服务器实时状态。选它是因为逻辑足够简单，适合讲清楚架构，同时又涉及网络请求、超时、异常处理这些常见工程问题，不是那种糊弄人的Hello World。
3.1 先写一个干净的JSON Schema
参数规范这件事，直接决定模型传参的质量。最开始我自己写参数说明用纯文本，比如"ip_address：服务器IP"，结果模型经常传IP时不带引号、或者把IP和端口混在一起传，解析的时候直接报错。
后来换成正式JSON Schema，情况好多了。对模型来说，Schema就是一份无歧义的格式说明书。我当时的定义大致长这样：
{ "name": "get_server_status", "description": "获取指定服务器的CPU、内存和磁盘使用率，用于判断机器负载情况", "parameters": { "type": "object", "properties": { "host": { "type": "string", "description": "服务器IP地址或域名", "examples": ["192.168.1.10"] }, "port": { "type": "integer", "description": "SSH或HTTP服务端口", "default": 22 } }, "required": ["host"] } }有个细节值得注意：我给每个参数都加了examples。这在文档里看不算什么，但对模型效果影响很大。模型在不确定参数格式时，会倾向于模仿样例格式输出，加了样例之后参数格式出错的概率低非常多。
参数校验也要在入口做一次，不能让错误参数直接打进执行逻辑。模型不是你同事，它不是一个严谨的工程师——它可能把必填参数漏了，也可能把一个字符串塞进整数字段里。入口校验挡掉这些脏数据，后面执行代码才敢安心做事。
3.2 执行逻辑里藏着不少坑
技能执行逻辑看起来就是一段"请求服务器并解析结果"的代码，但真实环境里要处理的问题比想象中多。一次查询别人机器，返回慢、超时、连不上，都是家常便饭。如果技能执行没有超时控制，Agent可能整个卡在那个技能里，后续对话全废了。
我给这个技能加了两层超时：连接超时设为5秒，读超时设为10秒。超时后返回一个状态为"TIMEOUT"的结果，模型看到这个状态会主动告诉用户"服务器响应超时，建议稍后再试"。这种结果其实已经算"有效失败"了——系统没有崩溃，模型也有信息可答。
还有个坑是返回数据的"可读性"。我早期版本直接把原始监控数据全量返回，比如一堆内存缓冲区的细碎指标，模型根本分不清哪个是关键。后来我改成只返回三个关键数值：CPU使用率、内存使用率、磁盘使用率，再附加一行简短的健康状态描述。模型拿到这种"半成品结果"，直接就能组织出对用户友好的回答。
3.3 结果回传的格式决定了模型的下半场表现
技能的返回格式，直接决定了模型下一步的表现。我用的是这样的结构：
{ "status": "SUCCESS", "data": { "cpu_percent": 23.5, "memory_percent": 41.2, "disk_percent": 67.8 }, "message": "CPU 23.5%，内存 41.2%，磁盘 67.8%，整体负载正常" }status字段告诉模型"这次调用行不行"，data是结构化数据，message是给用户看的现成人话。模型拿到这个结果，通常有两种处理方式：直接引用message，或者结合data再做一点补充分析。无论哪种，用户体验都是顺滑的。
如果技能返回的是status为"FAILED"的结果，我会在message里写清楚失败原因，比如"连接超时，请检查网络或地址是否正确"。这样模型就能顺着message给用户一个合理的解释，而不是自己编一个。
整个过程走下来你会发现：技能的代码反而是最不复杂的部分。真正决定体验的，是那些给模型看的"说明书"和"回执"——这本质上是另一套结构化沟通协议，跟写给人看的编程接口完全是两码事。
4. 技能调度的核心链路：从模型"想用"到代码"真正执行"
单个技能跑通不算本事，多个技能协同工作才是Agent落地的真正考验。我在项目里同时挂了十几个技能，一开始手动写判断逻辑来决定"这轮对话该调哪个技能"，写得我头皮发麻。后来才明白，这套调度逻辑根本不该由程序猿硬编码，而是应该交给模型来决策。
4.1 触发机制：注册表驱动，而不是if-else驱动
我的做法是建了一张技能注册表，表里每一行就是一个技能的元数据（技能名、描述、参数Schema、执行函数的引用）。运行时把这张表以工具定义的形式整体发给模型，让模型在生成对话时自主选择。模型觉得需要查询服务器状态，它会在回复里生成一个函数调用标记，指定get_server_status和相应的host参数；后端通过统一的调度器解析这个标记，查表找到对应的执行函数，传参执行，拿结果回灌给模型。
判断要不要用这个技能、用哪个技能，是模型的工作；判断怎么执行、参数怎么校验，是后端调度器的工作。这件事分开之后，新增一个技能就变成了纯配置行为：注册表加一行，再写一个执行函数，不用改调度代码，也不用改提示词。技能从"写死的逻辑"变成了"可热插拔的积木"。
技能少的时候你们可能感受不到这个设计的价值，反正这两个if怎么都能跑。但当技能数量过二十，交互分支开始指数增长，if-else路线基本就走进死胡同了。注册表加模型决策的路线，边际成本几乎为零。
4.2 技能召回：技能太多，模型也会挑花眼
另一个问题接踵而至：技能一多，把所有技能的描述一次性塞给模型，token占用大且会造成注意力稀释。做过长上下文调优的朋友都知道，内容太多时模型会"近视"——排在后面的技能描述容易漏看。更别说技能描述本身也是token，几十个技能塞下来，每次请求要多花几千token，成本和延迟双双上涨。
我的解法是做一个轻量级的召回过滤层。技能注册表里每条记录都附带几个关键词标签，比如"服务器""数据库""日志""文件"。用户的问题进来后，先用一个小的匹配器，按标签和语义相似度筛出最相关的5-8个技能，再把它们的描述传给模型。这个筛的过程其实不需要很大的模型，一套基于关键词和嵌入向量的简单匹配就够用了。
加了这层之后，两个收益立刻体现：一是模型的工具选择准确率上来了——候选少了，注意力更集中，选错的概率自然降了；二是token成本和响应延迟都下来了。唯一需要注意的是召回阈值的把握。筛得太狠，模型需要但没召回的技能就"隐身"了；筛得太松，过滤层形同虚设。我在实际项目里通常保留top-8，同时对置信度设了一个下限，低于下限的宁多勿少。
4.3 调用链路上最容易"静默失败"的环节
多技能协同的时候，有个非常隐蔽的坑：一个技能执行成功，但它的结果被后一个技能误用。我在一个数据处理场景里踩过这雷——技能A清洗数据返回了一个规范的DataFrame结构，技能B要统计数据却把它当成纯文本处理，结果统计出来的数字全是错的。
问题根源在技能之间的数据契约没有对齐。修法是在返回结果里携带明确的格式标记，同时在技能描述里写清楚它期望接收什么格式。后来我更进一步，让每个技能在返回结果里带上自己的"输出Schema版本号"，下游技能拿到结果后先验一下格式，不合格就报错而不是硬着头皮处理。这种防御式设计，在技能数量多了以后基本是必需品。
调用链路还有一个容易忽视的点是执行并发。如果Agent在处理过程中连续触发了多个技能，比如既查服务器状态又查数据库，调度器要不要并行执行？我一开始图快直接并发，结果两个技能同时去连一个数据库，连接池被占满，双双失败。后面加了并发控制，最多允许3个技能同时执行，并且把共享资源的技能绑定在同一批串行执行。这属于那种不实际跑起来永远想不到的工程细节。
5. 技能多了以后怎么管：注册表、热更新和可观测性
技能的工程化管理，是"agent-skills"从demo走向可维护系统的关键分水岭。很多项目前期跑得好好的，一到技能数量上来了就乱套——病根几乎都是监管手段没跟上。技能在这种架构里已经不是一段代码，而是一项需要持续治理的资产。
5.1 注册表设计：多存一点元数据，多省很多事
我的注册表结构经历了从"能跑就行"到"能管才踏实"的演进。早期注册表就三列：技能名、描述、函数。后面逐步加了负责人、创建时间、修改时间、调用次数、平均耗时、最近执行状态这些元数据。
加这些看似多余，实际上帮助极大。比如模型偶尔选错技能，我可以直接去看调用统计，揪出哪些技能描述存在混淆，因为如果两个技能的语义相近，模型常常选错。典型的案例是"获取服务器状态"和"获取服务器配置"——名字都很接近，模型经常混淆。通过调用记录里的交替调用情况，就能定位问题，然后手动调整描述做语义隔离。
注册表设计上我还做了一个小优化：给每个技能加了一个默认置信度阈值。模型工具选择机制在某些实现里可以设置最低触发分，低于阈值的技能不允许调度，能挡掉一堆低质量的触发乱象。
5.2 热更新：技能的增删改不能重启服务
Agent系统一旦提供服务，就不可能"改完代码重新部署"这么随意了。技能需要动态增删改。我的做法是让注册表支持从外部配置中心加载，执行函数本身以独立模块形式注册，做好接口约定就能热挂载。
这里必须提一个差点炸掉线上环境的操作：我在更新一个技能的执行函数时，没有先做灰度，直接替换了注册表里的引用，结果新版本函数有个参数没兼容旧格式，线上调用全部报错。从那以后我给自己定了一条铁律：技能的修改必须带版本号，注册表里保留上一个稳定版本；切换时先切少量流量试运行，观察一段时间再全量。年纪越来越大，胆子就越来越小了，但稳定性确实换回来了。
热更新的另一个好处是跑实验方便。我想试一种新的工具调用策略，不用开分支、不用改代码，直接在配置中心注册一个新版本的技能，用标签路由把一部分测试流量引过去就行。这个玩法在Agent迭代期特别好用，建议大家可以尝试一下。
5.3 可观测性：给每个技能调用打上全链路标记
没有可观测性的Agent系统，排查问题基本靠猜。技能调用涉及模型决策、参数生成、执行、结果回灌多个环节，任何一环出问题都可能让用户看到"答非所问"或"卡住不动"。我当时引入了一套全链路标记的做法：每次会话生成一个跟踪ID，技能调用时把它透传到执行层和日志系统。这样查问题时可以看到"这轮对话模型要调哪个技能→参数传了什么→执行结果是什么→模型基于结果回了啥"，整条链路一目了然。
有次用户反馈Agent给出了一串莫名其妙的数字，我顺着跟踪ID查下去，发现是技能B在数据转换时把单位KB和MB搞混了，返回了一个数量级完全错误的结果。模型并不知道这个数据是错的，还一本正经地引用给用户。要是没有全链路日志，这种问题只能靠运气才能碰出来。
跑了一段时间以后，我又加了一个"技能调用摘要"页面，展示每个技能的成功率、平均耗时、失败原因分布。这些数据不只是给开发者看的，也是优化Agent质量的重要依据——比如发现某个技能经常超时，就应该在描述里加上"该技能可能响应较慢"，模型遇到时会提前给用户打预防针，体验立刻不一样。
6. 踩坑实录：技能描述翻车、参数幻觉、还有一次直接把我数据跑挂了
最后把这一路上踩过的坑集中复盘一下。前面每个章节都提到了一些，但有几条值得单独拎出来展开，因为它们属于"文档里不会告诉你、自己踩了才知道"的经验，对正在做Agent技能体系的朋友应该有实际帮助。
6.1 技能描述是给模型看的，不是给程序猿看的
这个认知我调整了很久。程序员习惯的"技能描述"往往是技术栈词汇，比如"执行SSH命令""解析Nginx日志"，但模型对技能的理解完全依赖自然语言的语义，不是代码层面的功能标签。有次我在描述里写了"调用ffmpeg转换格式"，模型能识别；但我写"执行视频转码"时，模型反而更流畅。关键规律是：描述里少用冷门缩写，多用常见自然语言，配合使用场景说明。后来我把所有技能描述重写了一遍，每条都明确包含三要素：技能做什么、什么场景使用、什么情况别用。模型的选择准确率肉眼可见地提升了。
还有个细节：一些技能的语义边界容易重叠。比如"查服务器CPU"和"查服务器性能"，模型很可能认为它们是一回事。做法是要么合并技能，要么在描述里强化边界，比如"查服务器CPU仅返回CPU使用率，不包含内存和磁盘信息；完整性能数据请用get_server_status"。这本质上是给人做接口文档的思路，但服务对象变成了模型。
6.2 参数幻觉：模型会编造它以为是对的参数
做技能体系，最让人头秃的问题之一就是参数幻觉。模型在不确定用户上下文时，可能会编出一个看起来合理、实际不存在的参数值。比如用户只问"看看那台服务器怎么样了"，模型面对必填的host参数，可能就会编一个"127.0.0.1"或者"localhost"来应付。这在人看起来离谱，但模型确实会产出这种结果。
应对策略第一条：参数尽量不缺省，能设计成从上下文中提取的就不要依赖模型猜测。第二条：对于实在无法提取的必填参数，明确在Schema中标记required，这样模型被迫追问用户而不是自己编。第三条：在技能执行入口做一层白名单校验。比如host字段可以校验是否为合法的IP格式或域名，不合法直接拦下并返回友好错误。这层校验挡掉的不只是幻觉，还有用户的误输入——两全其美。
6.3 超时和重试：技能不能无限等，也不能一失败就放弃
一次事故让我彻底记住了超时配置的威力。当时一个技能调用一个外部统计接口，平常几百毫秒就返回，可那天服务端异常，接口一直不响应。技能没有设置超时，整个Agent卡了将近3分钟，用户以为系统挂了，直接发消息来投诉。排查完我立刻给所有涉及网络请求的技能加了超时控制，并且做了重试策略：对幂等操作（比如查询类技能）允许重试一次；对非幂等操作（比如提交类技能）失败就失败，绝不能让后端重复提交。
超时配置本身也不是统一的，内部服务可以给短一点的超时（比如3-5秒），外部第三方服务得留宽一些（10秒以上）。工具执行器的实现里，可以用并发控制+超时取消的方式，确保任何一个技能失控时，整体会话还能继续往下走。
6.4 重脚本类技能的"环境边界"
还有一个教训：技能执行的是脚本/命令时，运行环境最好隔离。我在某公司的模拟项目里遇到过这种情况：技能执行一个数据合并脚本，因为跑在Agent服务所在的环境里，脚本误用了环境变量中指向错误目录的路径，结果把一份存储库里的数据误覆盖了。那次之后我做了一个强制规定：凡是执行任意命令或代码的技能，一律在独立沙箱环境里运行，并且只给最小权限，要操作的目录必须在参数里显式声明，不允许从环境推断路径。
这类问题的根本原因不是Agent的"智能"不够，而是它作为执行通道，权限太大，保护太少。安全边界没有提前划好，等到出事了才后悔，成本太高了。一条铁律：Agent的所有技能执行都必须遵循最小权限原则，技能能拿到什么文件、能访问什么服务、能调用什么命令，全部要提前界定清楚。
6.5 并发环境下的状态隔离
最后一个是并发场景的状态问题。Agent系统往往不是单用户单会话在跑，而是一堆会话同时在进行。如果技能执行逻辑里引用了全局变量或者共享缓存，很容易出现会话A的数据串到会话B的情况。就在我公司内部试运行阶段，出现过A用户查数据，结果显示为B用户的数据结论，查了半天发现是技能里用了一个全局缓存变量，结果并发时交叉污染了。
修复方案也很简单：所有技能的状态信息都按会话ID隔离，二级缓存一律加会话维度前缀；如果技能内部有跨会话共享的数据，用显式加锁的方式控制。这种问题在单用户测试时完全暴露不出来，一定得上并发量才能现形。
以上这些坑，归纳起来其实就是三句话：技能是给模型看的接口，所以描述和Schema比代码更重要；技能是跑在真实系统里的代码，所以超时、并发、安全边界一个不能少；技能是持续演化的资产，所以注册、版本、可观测性必须跟上。做Agent技能体系做到后面，会发现它更像是在设计和维护一套"模型友好型微服务"，而不是简单地写几个函数给模型调用。这套思路分享出来，希望对正在做Agent落地的朋友有些启发。接下来每个技能的设计、调试、治理，都是一步一个脚印走出来的，我现在回头看，最大的体会反而是：再先进的模型，落地时拼的仍然是这些基础工程的一板一眼。
