当初把Agent从demo推到生产环境我卡在第一个绕不过去的问题上模型很聪明但手脚很笨。让它写一段文案、做一次翻译效果惊艳让它去查一张报表、发一封邮件、操作一套内部系统就开始满嘴跑火车。你问它“刚才那步执行成功了吗”它能给你编一个像模像样的成功结果。后来我才想明白缺的不是更强的模型而是那层叫agent-skills的东西——把一条条具体能力封装成模型可理解、可调用、可反馈的“技能”。这个项目要解决的就是给Agent装上真正能干活的手脚。它适合两类人一类是正在做Agent应用但被工具调用折磨得焦头烂额的开发者另一类是准备从“聊天机器人”往“数字员工”方向转型的团队负责人。下面这些内容是我从实际落地过程中扒出来的经验包括技能注册表怎么设计、编排层怎么搭、以及为什么我强烈建议你把每个技能都做成“有状态”的。1. 从“会聊天”到“能干活的Agent”还差一个技能层先说我踩过最疼的一个坑。早期我做了一个所谓的Agent模型用的是当时能力最强的那一档Prompt写得自认为天衣无缝工具函数也挂上了七八个。结果在内部试用的时候运营同事丢给它一句“帮我看看上周华东区的投放数据顺便把异常波动的日期标出来”它折腾了五分钟最后给出一个表格——数据全是编的波动日期是模型猜的因为它根本没找到真实数据的入口但又不想承认自己做不到。这个问题的根源在于模型天然是一个“文本生成器”不是一个“任务执行器”。它擅长的是把输入映射到输出而不是操控真实世界里的资源。想让模型稳定地操控外部工具必须有中间那一层——技能层。这层要做三件事第一把外部能力抽象成模型能理解的“技能卡片”第二把执行结果变成模型能接收的“反馈信号”第三把多个技能串成一条可追踪的“任务链路”。1.1 别急着写代码先把Agent的“能力边界”画出来很多团队一上来就急着写注册函数我觉得这是本末倒置。你首先要想清楚一个哲学问题你的Agent到底应该拥有哪些能力是只做信息查询还是也要做状态变更是只读数据还是要写回数据每多一个技能模型的选择空间就大一分出现幻觉和误调用的概率也涨一分。我建议先用一张白纸把技能边界画出来。我的画法分三列必须有的技能跟业务核心强相关Agent没有它就像人没有手。比如数据分析Agent必须能连数仓、能跑SQL、能渲染图表。锦上添花的技能属于增强体验在核心链路之外。比如自动生成周报摘要、把结论推送到钉钉群。这类技能初期可以只做一两个。坚决不要的技能涉及高风险操作、权限边界不清晰、或者模型当前能力很难稳定驾驭的动作。比如直接删除生产数据、修改线上配置。优先级宁可后面再加也不要一上来全给。这个边界画完了你才知道后面要写的技能注册表该长什么样。我见过太多团队把Agent做成一个塞了二十多个工具的“瑞士军刀”结果模型在选择工具时反而像个选择困难症患者每调用一次就要纠结半天还经常选错。1.2 技能列表最终长什么样在agent-skills项目里我最终把技能定义成了一种高度结构化的描述语言。一个完整的技能至少要包含以下字段{ skill_name: query_sales_data, description: 查询指定时间范围和区域的销售数据返回聚合后的统计结果适用于周报、月报、异常分析等场景, input_schema: { start_date: string, 格式YYYY-MM-DD, end_date: string, 格式YYYY-MM-DD, region: string, 可选值[华东, 华南, 华北, 西南] }, output_schema: { total_revenue: number, order_count: number, daily_breakdown: array }, side_effects: read_only, timeout_ms: 10000 }这个定义很关键。description不是给人看的是给模型的。模型通过这个描述来判断“当前这个任务该不该调用你”所以描述里必须写清楚这个技能“能干什么、在什么场景下用、有什么限制”。side_effects字段尤其重要它告诉模型这个技能是只读的还是会改数据的这直接决定了模型在面对复杂任务时是敢直接执行还是要先跟用户确认。2. skill注册表把工具调用从“临时拼凑”变成“工程化基座”有了概念设计接下来就是代码层面的落地。agent-skills项目的核心模块是一个技能注册表它承担两件事一是所有技能的注册和管理二是给模型提供一个统一的查询入口。我把它比喻成“工具箱上的标签贴”——标签写得清清楚楚模型才知道去哪个抽屉拿什么工具。2.1 用装饰器和元数据构建统一入口Python语言下我用装饰器来实现技能注册代码极简效果却非常好from agent_skills import register, SkillContext register( namequery_sales_data, description查询指定时间范围和区域的销售数据返回聚合统计结果, input_schema{...}, output_schema{...}, side_effectsread_only, timeout_ms10000, ) def query_sales_data(ctx: SkillContext, start_date: str, end_date: str, region: str 全国): # ctx 里封装了调用方信息、链路追踪ID、鉴权token等 data ctx.db.query(...) result aggregate(data) return result这里有一个设计细节值得多说两句所有技能函数的第一个参数都是SkillContext。这意味着技能不只是一个孤立的函数它跟调用链、上游状态、鉴权信息是绑在一起的。没有这个context技能就只能做无状态的计算一旦要牵扯到用户身份、请求追踪、数据源切换代码就会变得到处都是隐式参数非常难维护。2.2 模型是怎么“看懂”技能列表的注册表的核心逻辑是把上面那一堆技能定义转换成模型能看懂的格式。我现在用的方案是在每次请求进入编排层时动态组装一个“技能说明全集”放进system prompt里同时配合一个tool_choice参数约束模型行为。这个全集不能太长。模型对 prompt 的注意力是有限的你把所有技能不分青红皂白全塞进去效果反而差。我做了个两步筛选策略粗筛根据用户输入的关键词把候选技能从全量列表中过滤到5~8个以内。比如用户问“上周华东区投放怎么样”query_sales_data、query_ad_metrics、send_report_to_group会被筛出来而restart_server这种完全不相关的会被干掉。精排根据技能描述与用户输入的语义相似度再排一遍把最相关的放在最前面。模型在选择时通常更倾向于排在靠前的技能这个跟大模型的注意力机制有关系。这个两层筛选的效率提升非常明显。之前直接把20个技能全量塞进prompt模型工具选择的准确率大概在82%左右偶发乱选。改成筛选精排之后准确率稳定在了96%以上调用耗时才多了不到30ms。如果你也在做类似的工具路由强烈不建议直接一股脑全塞。3. 决定成败的不是单个技能而是组合编排单个技能写得再好只能证明“工具能用”真正让Agent显得“聪明”的是把多个技能按正确的顺序串起来形成一条完整的工作流。agent-skills项目把我逼到最痛苦的地方也恰恰是这里——组合编排。以最典型的“数据分析报告输出”场景为例一次完整的任务大概需要这样一串动作解析用户意图确认数据范围和时间粒度调用查询技能获取原始数据调用异常检测技能标记异常波动点调用报告生成技能把结果整理成结构化文本调用消息推送技能把报告发送到指定群。如果你让模型自由发挥去调这些步骤它大概率会在第2步和第3步之间天马行空比如突然去调一个毫不相干的“客户信息查询技能”。所以我在编排层引入了一个轻量级的“计划器”它不直接调用工具而是先输出一个执行计划plan将任务拆解成有序的子步骤每一步都指定应该用哪个技能。def execute_plan(plan, ctx): results [] for step in plan.steps: skill registry.get(step.skill_name) if not skill: ctx.log.warning(f跳过未注册技能: {step.skill_name}) continue result skill.execute(ctx, **step.arguments) results.append(result) # 关键把上一步的结果作为上下文传给下一步 ctx.update_context(step.skill_name, result) return results这个循环看起来简单真正起作用的是update_context这一步。它保证了后面的技能能看到前面技能的输出模型不会“失忆”。我在实际使用中发现如果不做这个上下文传递模型经常会把前面已经查出来的结果忘了然后重新查一遍或者拿中间过程的假设数据去做后续计算错误率直接翻倍。3.1 分支与回退Agent面对错误时的优雅姿势编排层还有一个绕不开的话题技能执行失败了怎么办。很多Agent应用一遇到工具报错就直接把错误信息抛给模型让模型“看着办”。这是个坏做法——模型看到错误后往往会产生幻觉编一个根本不存在的结果出来。我的做法是在编排层加分支策略。具体来说当某个技能执行失败时按照优先级依次处理重试一次如果错误是超时或临时网络抖动重试往往有效降级到替代技能比如主力查询技能挂了自动切换到备份查询接口或者用离线缓存的近似数据显式返回“无法完成”如果降级也不行就如实告诉用户“这个任务目前无法完成原因是xxx”而不是让模型编一个假结果。这套分支逻辑让Agent在非理想情况下也能保持诚实。工程上“能力不行但诚实”比“能力不行但爱编”要好一万倍——至少用户信任你不会被消耗殆尽。3.2 并行技能的可行性与收益边界一个自然浮现的优化点是当多个技能彼此之间没有依赖关系时能不能并行执行来缩短总耗时比如同时查销售数据和查广告数据完全可以各自跑各自的。技术上没有问题但有个收益边界需要心里有数。我实测下来当并行技能不超过5个时收益明显超过5个以后收益会被线程切换、资源竞争、以及下游汇总逻辑的复杂度给吃掉。而且并行还会带来一个副作用多个技能同时返回后模型需要对结果做汇总这时候上下文会变得很拥挤反而更容易出错。所以我的建议是先串行跑通再考虑并行。并行是优化手段不是默认选项。4. 让Agent在实战中“长出”新技能组织级的技能演化机制agent-skills这个名字里有个“skills”是复数它天然暗示了一件事技能集合不是静态的它会随着业务发展不断生长。一个合格的项目必须为“新技能如何被发现、被沉淀、被复用”提供一套机制否则每个业务线都在各自造轮子Agent的能力池就是一盘散沙。4.1 从一次手动操作中发现新技能我们的做法是给Agent加了一个“技能沉淀”循环。过程是这样的当模型在计划中生成了一步操作但注册表里找不到匹配技能时把这步操作记录到“未覆盖需求池”运营或研发定期review需求池把那些高频出现、重复发生的操作提炼成一个新的技能新技能写完之后走一次评测流程拿历史数据验证准确率达标后再注册进正式技能表。这套循环跑起来之后最明显的变化是技能数量的增长不再靠拍脑袋而是跟着真实用户需求走。之前我们是“有什么工具就给Agent配什么技能”现在变成了“用户需要什么动作我们就去开发什么技能”。方向完全反过来了但效果天差地别。4.2 技能质量怎么评估别只看调用成功率我给技能质量建了一套评估维度想分享给大家参考。传统的工具调用测试只关注“它成功返回了没有”这远远不够。我的评估框架有四个维度维度衡量内容我的达标线调用成功率技能执行过程中没有报错≥98%结果准确率返回数据和真实值一致不编造≥95%语义匹配率模型是否在正确的场景下调用此技能≥96%端到端贡献该技能是否真正帮助用户完成了任务定性评估用户反馈这里特别说一下语义匹配率。技能注册表里如果描述写得模糊模型就会在错误的场景下调它比如“查询订单”和“查询物流”描述里都写了“查订单”模型就分不清了。后来我把两个技能的description分别细化成“订单金额、商品明细、支付状态”和“物流轨迹、配送节点、预计到达时间”语义冲突立刻缓解了。这个细节可以直接抄。5. 落地过程中的几个反直觉经验项目做到后期我踩了一些听起来反直觉但实际非常深刻的坑。最后把这些经验整理出来希望能帮后来人少走弯路。5.1 技能越“薄”越好不要把业务逻辑写进技能里这是我吃过亏之后得出的结论。早期我把一个“生成周报”的技能做得非常厚里面塞了取数逻辑、计算逻辑、排版逻辑、文案逻辑结果每次业务规则一变这个技能就要大改而且单个技能过大模型的调用和调试都非常困难。后来我把它拆成了“查数据”“做分析”“写摘要”“组装文档”四个薄技能由编排层把它们串起来。每个技能只干一件事干得干净利落。这样拆完之后单个技能的复用度大幅提升“查数据”被其他好几个场景复用上了。技能设计的原则应该是“职责单一”跟微服务拆分的道理一模一样。5.2 必须给技能加“状态”否则Agent是个失忆症患者这个观点我在前面反复提过但值得单独再说一次。无状态的技能函数就像不带钱包出门的人每次都要重新回家拿钱。技能的调用必须能感知当前会话、当前任务、当前上下文。我用了一个简单的全局上下文对象来维护状态它至少包含session_id当前会话的ID用于追踪整个对话历史task_stack当前任务拆解成的子步骤栈memory一个轻量的KV存储记录已获取的信息permissions当前调用者的权限集技能执行前做鉴权。有了状态技能才能在不同的调用间共享信息Agent才谈得上“连续性”。没有状态每个技能调用都是一座孤岛模型永远在做重复建设。5.3 Prompt里全塞技能描述不如结构化定义最后一个经验别把技能描述当成某种“Prompt工程技巧”去随便写。技能描述的结构化程度直接决定了模型对技能的利用率。我发现下面这种写法比一长串自然语言描述更稳开头一句话说明技能职责中间列出关键参数和行为约束结尾明确侧效应副作用参数用JSON Schema表达而不是口语化说明。比如input_schema写清楚了参数类型和格式模型就会规规矩矩传2025-01-01而不是传January 1st给它然后返回一个校验失败。这类格式化的定义虽然写的时候麻烦点但对模型是实打实的友好。5.4 涉及敏感动作的技能一定要走“人工确认”环节这也是我在实际业务里被逼出来的设计。某些技能虽然看起来人畜无害比如“发送邮件到客户”“修改订单状态”“执行生产环境脚本”一旦模型误判调用了后果不堪设想。所以我给这类技能加了一个requires_confirmationTrue的标记。执行流程变成编排层发现技能需要确认先把动作描述和目标数据返回给用户等用户确认后再真正执行。这个“问一句”的动作在很多时候就把事故化解在萌芽状态了。对应到代码实现其实就是在执行循环里加一个分支判断遇到需要确认的技能就挂起等待信号量置位后再放行。6. 从项目里趟出来的几条硬指标做agent-skills这个项目我最大的感受是Agent应用开发跟传统后端开发最不一样的地方在于你面对的是一个概率系统不是确定性系统。模型每次调用同一段Prompt结果都可能不一样。这个底层逻辑决定了我们做技能层时永远要考虑“如果模型选错工具怎么办”“如果技能返回异常怎么办”“如果用户输入有歧义怎么办”。也因此我给自己的技能层设了两条硬指标建议每个做Agent的团队也抄一下任何技能都不能静默失败要么返回正确结果要么返回明确错误禁止吞异常、禁止返回空壳数据。任何技能调用必须可追踪从模型决定调哪个技能到技能执行的入参、出参、耗时、错误信息全链路日志一条不能少。出了线上问题你能五分钟之内定位到是哪一步、哪个参数、哪个分支导致的。这两条当时帮我节约了无数的Debug时间。模型的行为不可控但日志可以做得足够细细到你从日志里就能还原出模型当时的“思考轨迹”。这个对线上Agent尤其重要——它不是给你一个人用的demo是几十上百个人每天都在用的生产系统。如果让我重新做一遍我可能不会再从“选个大模型”开始而是从“梳理清楚我的Agent需要哪些技能”开始。模型型号差一点可以在调度层弥补技能层设计得一塌糊涂再强大的模型也救不回来。