做LLM Agent开发的人大概都经历过这种尴尬模型推理能力上来了Agent却卡在工具调用这一层一堆if/else拼起来的调度逻辑改一个参数就要担心连环炸。前阵子做的这个agent-skills项目就是为了把技能管理这件事彻底理清楚。你可以把它理解成一个给智能体用的“工具技能库”——以标准Schema注册技能、动态加载工具、统一编排调用链换模型平台不需要重写工具层排查问题也不用再靠肉眼盯日志。这篇文章我会从需求拆解讲到核心实现再把实际跑通项目时踩过的坑一起倒出来适合已经能写出简单Agent、但想把工具调用做得更工程化的开发者参考。1. 这个项目要解决的痛点以及我的动机1.1 工具调用的工程化困局先说我的实际感受Agent应用的开发进度前期往往被模型选型和提示词设计占据但真正到了要稳定上线的时候瓶颈几乎全部集中在“技能层”。我遇到过几个特别典型的场景。第一是技能定义散落一团。数据库操作、外部接口、本地脚本各自散在不同文件里Agent需要通过工具调用去触达它们时只能靠一份随时过期的接口清单。某个查询逻辑改了入参提示词和调用代码没同步更新Agent就会反复用旧参数试错。第二是Schema格式不统一。不同大模型平台的Function Calling参数格式存在明显差异A平台用的是数组结构B平台可能要求对象再套一层描述。每次切换底层模型工具层就要跟着改一遍成本非常高。第三也是最容易被忽略的问题技能不可复用。同一个“发送邮件”功能在项目甲里写了一遍换到项目乙又复制一份改改。哪天邮件服务的认证方式变了你得同时去改三个地方。第四是可观测性几乎为零。Agent到底调用了哪个技能、传了什么参数、返回值是什么、这一步消耗了多少token没有统一打点的话出了问题根本无从复盘。agent-skills的出发点就是把技能当作一等公民来管理。核心不再是“让模型直接调用一堆零散函数”而是先为每个技能建立一份标准化的身份档案——名称、描述、入参Schema、执行函数、可缓存性、超时策略、权限标签。所有技能进入注册中心由统一的执行器调度这样Agent团队只需要关心业务技能的编写不用每次重复处理格式转换、参数校验、日志埋点这些基础设施。1.2 为什么不自研工具链也不用现成框架有人可能会问市面上做Agent的开源框架不少为什么还要自己做一套技能编排我的判断依据是通用框架擅长解决“能不能调用工具”的问题但解决不了“工具规模变大之后怎么组织”的问题。我当时先用某个主流Agent框架做原型验证了最基本的工具调用流程。但到了第二个星期需要接入十几个外部系统时痛点就很明显了框架里的工具只是简单的函数列表缺少技能分组、权限隔离、缓存注解、幂等等概念。团队里某位开发者在注册工具时看漏了参数说明测试直接把生产环境的库存改乱了。这类事故跟模型能力无关纯粹是工具管理层缺少约束。另一个原因是我需要一套能同时兼容多个模型平台的适配层。与其等框架补全多平台格式转换不如自己在技能注册层就统一成内部Schema再做一层薄薄的适配器。这样上游业务代码不感知底层使用的具体LLM平台以后想换更强的新模型技能收录完全不用动。需要说清楚边界agent-skills不是要去重造一个Agent框架。规划决策、上下文管理、提示词模板这些能力该用框架的继续用框架。这套方案专注的是从“技能声明”到“技能执行”之间的那段管道把每个环节标准化。1.3 适合什么场景不适合什么场景这套方案的优势要发挥出来需要一定的前提条件我在做技术选型的时候也让团队对照过。适合的场景是技能数量在几十个以上并且持续增长Agent承担的流程涉及多步调用经常需要把一个技能的输出喂给另一个技能项目需要同时对接两个或以上的不同模型平台团队里有人专门负责技能质量而不是所有技能都临时在对话代码里“攒”出来。不太适合的场景也需要坦白讲。如果你只是在做一个演示性质的小型AI助手总共只有三五个固定工具用最简单的手写调用即可引入注册中心反而增加理解成本。另一种情况是业务流程本身极其单一——每天就是调同一个接口返回结果不需要模型去理解和选择工具。这种情况下做技能编排属于过度设计先把交互跑通更重要。2. 整体设计与核心架构拆解2.1 技能的最小单元是什么我在设计agent-skills的第一个模型时用的类比是“菜谱”。菜谱要有菜名、适合什么场合、原料清单和做法步骤一份技能定义也遵循类似结构。一个技能由六部分组成name是唯一标识模型不会直接看到这个字段的底层变量但日志和监控会依赖它description是给LLM看的索引应当写清楚“这个技能在什么情况下使用”而不是简单一句话带过schema定义入参结构字段类型、必填项、取值范围、字段说明都放这里fn是实际执行函数只负责完成业务动作不关心调用它的模型是谁元信息部分注明tags、cacheable、timeout_ms、requires_auth最后是version技能逻辑升级时保留旧版本线上可以灰度切流。这种设计最大的好处在于模型“理解技能”和“执行技能”彻底分离。模型理解技能只依赖description和schema而真正干活的是fn。因此我可以随时优化技能描述、调整参数格式只要Schema版本兼容Agent的决策层无需同步改动。2.2 注册中心的目录结构与动态加载技能注册我采用了目录扫描机制而不是聚在一个文件里手工注册。项目启动时注册中心会递归扫描skills/目录下所有__init__.py声明的模块装饰器负责把每个技能登记到全局注册表中。我踩过手工注册的坑。技能一旦变多手动在注册文件里加一行代码特别容易漏另一层风险是模块循环依赖A挂了B的装饰器B又引用A启动就崩。自动扫描配合装饰器之后新技能只要放在约定目录下就会自动出现在Agent候选列表里新人上手也直观。目录结构大致是agent-skills/ ├── registry.py ├── executor.py ├── adapter/ │ ├── platform_a.py │ └── platform_b.py └── skills/ ├── __init__.py ├── email/ │ ├── __init__.py │ ├── send_mail.py │ └── list_inboxes.py ├── metrics/ │ ├── __init__.py │ ├── query_daily.py │ └── export_report.py └── database/ ├── __init__.py └── safe_query.py每个技能子目录里的__init__.py不写逻辑代码只负责import本目录下的技能模块。注册中心扫描时通过约定避免加载到废弃文件夹。某个团队以前留了个skills/backup/目录没加排除规则结果模型总能用到一个“不存在”的旧技能排查了很久才发现是扫描器把备份模块也加载进去了。2.3 技能描述对上下文窗口的影响每轮对话LLM平台都会索要可用工具列表。这里有个现实约束上下文窗口不是无限的模型能同时感知的技能数量也是有限的。所以在agent-skills里技能不是一股脑全量注入的而是有一个“技能检索分组裁剪”的流程。我给每个技能打上多个维度的标签比如email、read_only、analytics。每次构造工具列表时执行器先根据用户当前意图做一次粗筛再把命中的技能按优先级排序最多只暴露前20个。剩下的技能不是不能用而是放在“二级列表”里模型可以先调用一个skill_search技能去搜索。相当于给Agent开了一个“工具商店”常用工具摆在货架前排冷门工具自己去仓库找。技能描述本身的写法也决定上下文占用。我建议每条description控制在200个汉字以内只写明使用条件和关键参数语义。那些长篇大论的注意事项、示例输入输出应该是开发者文档的内容不能塞给模型看——不然五六个技能就把prompt撑爆了真正留给业务上下文的空间变少。2.4 可观测性与权限边界设计调用链的追踪是工程化落地的关键。我在每个技能执行点都放置了一个高频打点器记录四项内容技能名称和版本、实际入参快照、返回值摘要、耗时与token开销。打点数据进异步队列不阻塞主流程。初期直接用同步日志结果高并发压测把磁盘IO干满了后来改成批量上报才能控住。权限边界也同样重要。技能层必须有能力区分“只读技能”和“写技能”。比如查询报表是只读发送邮件是写操作删除记录就是高风险操作。agent-skills的注册信息里有一个risk_level字段默认所有技能都是low。写技能必须声明为medium或high执行器在模型要求调用时会先走一次策略检查必要时强制要求用户二次确认。不做这层保护的话模型一旦被诱导连番触发写操作后果很难收拾。3. 核心实现细节与关键代码解析3.1 技能定义的标准写法技能定义我采用了装饰器模式最大的优势是强制无状态。开发者只需要提供一个普通函数不必继承某个基类或者维护一个技能对象实例。这样技能天然可重复调用不会因为几次调用之间残留状态而出现“第二次跑结果跟第一次不一样”的老大难问题。一个典型的技能定义长这样from agent_skills import skill skill.register( namesend_email, description发送电子邮件适合需要通知、报告或告警的场景。收件人必须是非空的邮箱地址。, schema{ type: object, properties: { to: {type: string, description: 收件人邮箱地址}, subject: {type: string, description: 邮件标题}, body: {type: string, description: 邮件正文支持纯文本}, }, required: [to, subject, body], }, tags[email, notification], cacheableFalse, timeout_ms30000, risk_levelmedium, ) def send_email(to: str, subject: str, body: str) - dict: # 实际业务逻辑走某个邮件服务的可用接口 return dispatch_email(to, subject, body)这个函数体足够干净因为它只管“发邮件”这一个动作。参数已经被Schema层和适配器归一化函数拿到的to、subject、body一定是正确的字符串类型——除非业务代码自己写崩了否则参数类错误不会进入函数内部。3.2 Schema校验与参数归一化模型返回的工具调用参数远比你想象的更不可靠。我见过模型把to字段传成数组把count: 5写成count: five甚至把必填字段整个遗漏。如果不对参数做严格校验技能执行层会陷入一种低效重试循环调用失败报错信息返回模型模型猜一个参数再试又失败白白烧掉大量token。因此agent-skills在执行技能前内置了两道关卡。第一道是JSON Schema校验基于注册定义逐字段检查类型与必填项不通过直接返回结构化错误错误信息会明确告诉模型“哪个字段缺失期望什么格式”。第二道是参数归一化每种技能可以声明一个normalizer函数做类型强制转换和格式统一。比如把时间字段统一成ISO 8601字符串把数字字段从字符串解析成整数把逗号分隔的标签拆成数组。参数归一化的一个典型例子是“时间段”参数。用户可能说“昨天”“最近三天”“从5月1日到5月10日”接入的语义解析模型输出什么格式都有可能。在技能侧统一接收一个range_start和range_end两个绝对时间戳由编排层在调用前完成相对时间的换算。这样做的好处是技能内部永远不需要关心自然语言里隐含的时区、节假日偏移等逻辑只处理标准化输入。3.3 适配器层与执行器的分工执行器是整个管道的枢纽具体职责是根据用户输入匹配候选技能把内部技能定义转换成当前模型平台需要的Tools参数格式接收模型返回的工具调用请求调用技能函数并回传结构化结果。适配器层是这里最值得投入设计的地方。不同平台对Tools参数的JSON结构要求确实不一样例如有的平台用function嵌套name和arguments有的平台要求tool_choice单独声明。我在内部维护了一套统一Schema然后为每个平台各写一个几十行的转换器。新增平台时只需要实现两个方法internal_to_platform(skill_def)和platform_call_to_internal(raw_tool_call)。反过来执行器对技能函数返回结果也做了统一封装。无论函数返回的是字符串还是结构化字典执行器都会统一包装成带有result键的JSON回传给模型。这样模型在下一步推理时能稳定读取到固定的结果结构不会因为某种技能返回一个纯文本就语无伦次。3.4 幂等设计、超时控制与重试策略写技能发送通知、修改数据、调用第三方写接口都必须考虑幂等。模型在对话流程中可能会出于各种原因重复调用同一个技能——第一次超时了用户催了一句模型再调一次。如果这个技能是“转账”或者“发送短信”副作用就会双倍产生。我在技能层引入了一个可选参数request_id执行器每次发起调用前自动生成并且在技能执行过程中先查一次“事件表”看这个request_id是否已经处理过。处理过就直接返回上一次的结果不重复执行。这个设计不必每个技能都接入但所有写技能和涉及扣费的读改写流程建议一律开启。超时控制采用“全局默认值单技能覆盖值”的策略。全局默认设置15秒超时长时间运行的任务单独指定timeout_ms120000。为什么单独设置这么重要因为大文件导出类技能如果也按照15秒掐断会频繁触发超重试反而把事情搞得更糟。重试策略我推荐梯度重试第一次失败后隔1秒重试第二次隔4秒第三次直接放弃并返回错误。重试次数超过三次的意义不大模型会进入死循环式猜测。这个阈值是压测后得到的感受低于三次成功率不足高于三次成本过高。4. 实操从零到一跑通一个Agent技能编排4.1 最小可运行示例如果你在本机尝试运行agent-skills我建议先用两个内置的演示技能跑通整体链路。演示技能一个是query_daily_sales用来查最近一段时间的销售汇总另一个是send_email用来发送结果邮件。启动代码很简洁from agent_skills import SkillRegistry, AgentRuntime registry SkillRegistry() registry.scan(skills) runtime AgentRuntime( registryregistry, platformplatform_a, modeldefault-model-name, ) resp runtime.chat(查一下最近三天的销售数据整理成摘要后发到某个管理者的邮箱) print(resp)这个例子里模型会自动完成两个技能的接力先解析出“最近三天”这个相对时间调用query_daily_sales拿到报表数据再结合用户提到的收件人信息调用send_email。表面上看起来像是模型突然“会思考”但实际上每一步都是由技能描述和Schema驱动的。注意输出里我刻意用了platformplatform_a的抽象——真实项目里这个参数对应你已经写好的适配器实现一旦要切换到另一个平台只要保证平台名对应关系正确技能层代码完全不用变。4.2 技能组合的两种形态原子型与复合型把技能做得足够小之后就需要考虑怎么组合它们。简单的组合发生在模型推理层用户任务包含多个子目标模型按顺序依次触发多个原子技能。比如“查看销售数据并发送邮件”这中间的query_daily_sales和send_email都是原子技能调用顺序由模型自主决定。但有些流程必须固定顺序不能让模型自由发挥。比如“生成每日报告”先查数据、再聚合成摘要、最后发邮件三步缺一不可、顺序不能乱。这种情况我建议写一个复合技能通过工作流编排把原子技能串起来对外只暴露一个generate_daily_report接口。复合技能内部可以调用注册中心里的其他技能这样既保留了原子技能的复用性也保证了关键流程的确定性。实操中复合技能经常被设计成一个“计划者”技能——先让Agent调用它它内部把任务分解成子步骤再按顺序逐一触发原子技能。有一个细节复合技能的description一定要写清楚它在什么条件下使用避免模型绕过原子技能直接意图不明确地乱调用。我一度把generate_daily_report的描述写得过于宽泛结果模型在用户只想“看一下昨天数据”的时候也去触发报告生成白白发了一封邮件。4.3 压测之前先检查的三件事跑通链路只是起点真正能上线还要做一轮针对性压测。我建议至少检查三件事技能匹配成功率、上下文消耗、并发注册中心的线程安全性。技能匹配成功率是衡量description质量的指标。准备一百条近似真实用户的随机意图把这些意图分别发给Agent统计模型是否选择了正确技能。第一次测试我的匹配成功率只有六成原因是技能描述里用了过多内部术语比如“调取营销归因模型数据”而用户说的是“看看这次活动带来多少单”。把描述改成贴近用户表达以后成功率到了九成以上。上下文消耗统计的是每轮调用大约吃掉了多少token。你可以专门定制一版日志在每轮结束记录prompt_tokens与completion_tokens。如果发现工具定义占的比例过高就按2.3节的做法做技能分组与裁剪。并发场景下注册中心的scan和技能查询应该都是只读操作我加了读写锁保证热加载新技能时不会出现“查到了注册表内容但不完整”的问题。5. 常见问题与排查技巧5.1 问题速查表问题现象常见原因解决办法技能不生效模型说无法调用某个技能技能描述缺少用户同义表达扩充描述贴近用户口语参数校验失败调用报错但模型不改参数缺少参数归一化步骤配置normalizer做类型转换上下文溢出请求直接超长报错技能全量注入分组裁剪、延迟加载、二级技能技能循环调用同一个技能被连续触发多次返回结果没有正确回传检查执行器回传逻辑重复副作用邮件或通知发送了两遍缺少幂等机制引入request_id事件表旧技能残影模型调用一个已被废弃的技能扫描器加载了备份目录配置排除规则5.2 一个典型的“技能时灵时不灵”排查过程有一次测试同学反馈某个查询技能“时而能用、时而不能用”。我盯着日志看了一会儿发现触发成功的对话里包含技能描述里的关键词触发失败的对话里用户换了另一种表达。问题不在模型推理能力而在于技能的description没有覆盖用户可能的表达方式。排查的基本思路是先看技能是否被成功注入到工具列表里再核对模型返回的tool_call中的name最后看技能执行结果。任何一环没有出现都说明问题出在那一层之前的链路。日志里如果同时有“skill_loaded”和“tool_call_miss”两个标记基本可以断定是技能匹配阶段出了问题。修法也很直接把用户侧高频说法列出来反向扩充description的同义表达。不是让你堆砌关键词而是围绕“这个技能到底服务于什么意图”来写。比如“查询销售数据”不妨写清楚“支持按时间范围汇总销售额、订单量、客单价也可以按区域或渠道拆分”——让模型看到描述就知道“这里有它要的维度”。5.3 几个平时文档里不怎么会写的细节我在实际跑项目时有几个印象深刻的细节分享在这里。第一是别让required字段管得太宽。Schema里必填字段越多模型就越容易因为缺一两个字段而反复尝试、反复失败。只有真正不可缺的参数才放进required其余参数尽量给默认值。第二是要为每次技能调用保留原始入参快照包括模型生成的原始参数和归一化之后的参数。后续复盘Agent决策链没有这两份数据几乎是盲复盘。第三个细节是技能执行函数的日志格式必须结构化——直接写人类可读的字符串会很难检索统一成JSON单行日志会让排查效率高得多。还有一点关乎安全不要给Agent暴露“执行任意SQL”或“执行任意Shell命令”这类泛化技能。你需要把这些能力封装成参数受限的技能比如只允许查询特定视图、只允许在指定目录下创建文件。否则一个越狱指令就可能让模型借技能之手做越权操作这是我在权限边界上反复做过强约束的领域。6. 后续扩展方向技能库做到后面越来越像一个小型内部服务市场。我目前正在尝试给agent-skills加两个扩展一个按技能调用频率生成“冷热排行榜”高频技能自动排列在提示词工具列表的前排另一个是针对技能质量本身做回归测试每次技能描述改了之后自动跑一遍覆盖用例防止“修好一个描述、弄坏另一个场景”。如果你也在打磨Agent工具层建议先从最小技能集开始把两三个高频流程用这套方式管起来再逐步扩展规模。做这层工程化确实要花时间但它能让你后续的Agent迭代变得特别清爽加新能力、换模型、追问题都不再是一团乱麻。