Agent技能化架构设计：告别Prompt失控，打造可编排的AI助手

之前说过一句话一直憋到现在很多Agent项目不是死在模型能力上而是死在什么都能聊但什么都做不精。用户打开你的Agent不是来听它讲道理的是来让它干活的。可你把一堆能力全塞进Prompt里模型就开始表演失忆指令一多反而什么都抓不住。一年前我折腾的这个项目代号就叫agent-skills核心思路很简单把Agent的能力从Prompt里的描述拆成一个个可注册、可调用、可编排的技能。这篇把整套设计思路、踩坑过程和代码实现都整理出来给正在搭Agent的同行做个参考。1. 为什么我放弃了全知全能Prompt转而给Agent搭技能库先说几个真实场景你大概率也遇到过。第一个是客服类Agent。最开始把所有业务规则写进system prompt大概两千字效果还不错。后来产品要求加退款流程、物流查询、优惠券计算Prompt涨到五千字模型开始答非所问用户问A问题它能扯到B业务上。我把规则精简、重排、加分隔符折腾了整整两周效果依然不稳定。第二个是内部效率工具类的Agent。我给它接了日历查询、待办管理、邮件草稿、周报生成能力都在一个Prompt里描述。结果它经常分不清该调哪个能力明明有日历查询技能用户问明天几点开会它非要现编一个答案。更要命的是各个能力的输入输出格式不统一返回结果堆在上下文里模型自己都不知道哪段数据是哪个请求的。第三个更典型是把Agent从演示环境推到生产环境时的问题。你自己测试的时候一个能力跑通了感觉一切OK。但真实用户会乱问、会打错别字、会提边界条件模型处理不了的时候不会说我做不到而是硬编一个让人哭笑不得的结果出来。三个问题指向同一个根因你根本没给Agent定义清楚能做什么和怎么做而是把所有可能性都塞给了一个概率模型去猜。1.1 单体Prompt的失控过程你可以把单体Prompt想象成一个新员工的入职培训手册里面写了你要为用户提供全方位的帮助然后附了五百条业务规则。这个新员工脑子确实好使但每处理一个问题它都要把五百条规则从头到尾过一遍。规则越来越多它就开始混淆把退款规则套到物流问题上把优惠券计算逻辑套到售后场景里。而且单体Prompt还有个隐藏问题所有能力共享一段上下文。日历查询的返回结果、邮件草稿的生成内容、周报的模板这些信息全部混在一起。模型在处理当前任务时注意力会被无关信息干扰。这就好比一个程序员同时开着五十个项目的上下文切换任务时很难不串线。另一个失控点是调试困难。Prompt出问题你根本定位不了是哪条指令导致的。改一句话可能影响所有场景的表现。加一个新能力可能把旧能力的触发条件挤掉。这种牵一发而动全身的改法在业务快速迭代时基本是灾难。1.2 技能化架构的核心逻辑agent-skills的思路是把每个能力做成一个独立的技能每个技能有自己清晰的输入、输出、触发条件和边界约束。Agent不再猜测自己该干什么而是从一个登记在册的技能列表里做选择和组合。我可以用一个很土但贴切的比喻单体Prompt像让一个万能助理同时管行政、财务、技术、客服他忙不过来技能化架构则是给助理配了一堆专门的工具和应用每个工具只解决一类问题助理要做的事情是——知道什么场景用哪个工具并且按顺序把工具串起来。这套架构带来三个直接好处边界清晰。每个技能只对自己的输入输出负责上下文不再大锅烩。日历技能返回的数据不会污染邮件技能的判断。独立迭代。技能之间互不干扰。修搜索技能的bug不会影响周报生成技能的稳定性。可观测可审计。Agent调用过哪些技能、传了什么参数、返回了什么结果全部有日志。出问题能回溯到具体环节。后面我会逐层拆解这套技能库的完整设计以及每一步的代码实现逻辑。2. 技能到底长什么样拆开看一个Agent技能的五要素我在agent-skills里对技能的定义经历了三个版本的迭代。第一版很简单就是一个函数加一段文字描述跑通后发现模型经常选错技能。第二版加了参数JSON Schema选对率明显提升但遇到边界情况还是会翻车。第三版才沉淀出稳定的五要素结构这版在多个项目里都稳定运行。一个完整的技能包含五个部分能力声明name description技能叫什么、在什么场景下使用、有什么限制。触发条件triggers什么样的用户意图应该路由到这个技能。参数规范parameters Schema调用这个技能需要传什么参数每个参数的类型和约束。执行逻辑execute技能被调用后实际执行的函数或接口。边界约束guardrails超时时间、重试策略、失败后的兜底行为、权限范围。这五要素里最容易被人忽略的是边界约束。很多人定义一个技能就写个name和description然后直接接函数结果线上跑着跑着某个技能因为外部接口超时直接让整个Agent挂掉。我后面会用一整章讲这块踩过的坑。2.1 五要素各自的作用能力声明是给Agent看的广告词。你描述得越准确模型选技能的选择就越准确。这里有个容易被忽略的技巧描述里一定要写清楚不适用什么场景负面示例能大幅提升选择准确率。只写正面场景模型容易把相关但不完全匹配的问题也路由过来。触发条件是给路由模块看的分流规则。它可以是关键词规则、语义相似度阈值也可以交给模型做意图判断。触发条件写得越具体路由越稳。参数规范是给参数校验器看的合同。模型生成的参数必须先通过Schema校验才真正传给执行函数。这样能拦截掉大量非法输入。执行逻辑是真正干活的代码。它不一定要是Python函数也可以是HTTP接口、SQL查询、外部服务调用。关键是执行逻辑必须和参数规范严格对齐。边界约束是给系统的保险丝。超时就断、失败就降级绝不能让技能执行失败变成Agent的幻觉素材。2.2 一个完整的技能定义示例以查询天气技能为例第五版的设计大概是这样的skill_weather { name: query_weather, description: 查询指定城市当前天气及未来3天预报。当用户询问天气、气温、降雨、风力等情况时使用。不适用于查询历史天气、空气质量指数或台风路径这些请使用其他技能。, trigger_keywords: [天气, 气温, 会不会下雨, 风力, 天气预报], parameters: { type: object, properties: { location: { type: string, description: 城市名或行政区名如北京、上海浦东 }, days: { type: integer, minimum: 1, maximum: 3, default: 1 } }, required: [location] }, execute: fetch_weather_from_service, timeout: 5, retry: 1, fallback: 天气服务暂时不可用请稍后再试 }这段定义里最值得玩味的是description里的负面声明。写了不适用于查询历史天气、空气质量指数或台风路径模型的技能选择准确率能提升不少。原因后面会细讲。2.3 技能分类感知、操作、推理与交互技能不是只有调用API一种形态。我跑了几个项目后发现把技能按职责分类对后续编排和复用非常关键。我最后常用的分类是四类技能类型典型职责示例交互特点感知类获取外部信息天气查询、新闻检索、数据库查询只读不改变系统状态操作类改变系统状态创建工单、发送邮件、更新订单有副作用需要授权确认推理类纯计算或逻辑判断价格计算、日程冲突检测、代码执行依赖明确参数无外部副作用交互类向用户询问补充信息收集订单号、确认操作意图多轮对话需要挂起恢复这四类技能在编排时的待遇完全不同。操作类技能我会强制增加用户确认步骤交互类技能会设计专门的上下文挂起机制推理类技能则优先用确定的计算代码而不是让模型自己算。这些细节直接决定了Agent在生产环境下的可靠度。3. 从定义到上线的完整链路注册、编排、调用与降级定义好单个技能只是第一步。真正让Agent具备干活能力的是一整套从注册到调用的运行链路。这一章我把agent-skills运行时核心的几个环节展开讲全部是可直接复用的工程实践。3.1 技能注册表与模型决策每个技能定义好之后第一步是注册到一个全局的技能注册表里。注册表本质就是一个字典key是技能名value是整个技能定义对象class SkillRegistry: def __init__(self): self._skills {} self._name_to_keywords {} def register(self, skill: dict): name skill[name] self._skills[name] skill for kw in skill.get(trigger_keywords, []): self._name_to_keywords.setdefault(kw, []).append(name) def match_by_intent(self, user_query: str): # 优先关键词精确匹配 for kw, names in self._name_to_keywords.items(): if kw in user_query: return names return None registry SkillRegistry() registry.register(skill_weather) registry.register(skill_create_ticket) registry.register(skill_calculate_price)这里有个设计取舍值得说技能选择到底用确定性规则还是让模型来选我的实践结论是分层过滤。先用关键词和规则做粗筛得到候选技能列表如果粗筛结果唯一直接执行不浪费模型调用如果粗筛结果有多个或为空再让模型从候选列表里做最终选择。这种方式既省Token又比纯规则或纯模型判断都稳定。3.2 参数校验与失败兜底模型选择了技能后紧接着就是参数校验。这一步必须用JSON Schema严格校验不能依赖模型自觉传参数。我在实际项目中遇到过模型把日期传成明天、把金额传成带逗号的字符串、把必填字段漏掉等情况全是在校验层拦下来的。校验通过后执行器会做几件事记录调用日志包含入参、时间戳、调用方会话ID按技能配置的超时时间执行函数默认5秒如果超时或抛异常按retry次数重试默认1次最终失败时返回一个标准错误信息而不是让异常直接上抛。错误信息格式我固定为{ status: error, error_code: weather_service_timeout, message: 天气服务暂时不可用请稍后再试 }之所以用这种结构化错误格式是为了让Agent在拿到错误结果时能明确知道技能失败了而不是把错误信息误当成正常数据继续编故事。这一点我会在踩坑章节重点解释。3.3 一次真实调用背后的完成流程把完整链路串起来一次用户请求到最终回应的流程是这样的用户输入上海明天会不会下雨路由模块用trigger_keywords粗筛命中query_weather技能。参数提取器从用户输入里抽取出 {location: 上海, days: 2}。这里的抽取可以交给模型但必须有Schema约束。参数校验器检查通过。执行器调用天气服务拿到返回数据。结果规整器把外部数据转成Agent友好的格式 根据天气服务上海明天2025-01-15有小雨气温5~9℃东南风3级。结果回填到Agent的上下文窗口Agent基于这段真实数据生成用户可读的回复。这个流程里第6步经常被忽略但特别重要。外部服务返回的原始JSON通常包含大量无关字段直接塞进上下文既浪费Token又会干扰模型。我在agent-skills里为每个技能配了一个result_formatter函数负责把原始返回精简成一段话。这一步做好模型回复的准确率能肉眼可见地提升。4. 技能编排实践让多个技能像团队一样协作单技能场景其实不太需要Agent参与规则引擎就够了。Agent真正体现价值的地方是多个技能组合起来完成一个复杂目标。这一章讲编排的几种模式以及我在实战中的观察。4.1 四种基础编排模式在agent-skills里我总结了四种基础编排模式顺序编排一步做完做下一步上一步的结果是下一步的输入。典型场景是查日历确认空闲时间再创建会议邀请。条件分支根据某个技能的结果决定走哪条分支。典型场景是查询库存如果低于阈值就去创建补货工单否则提示用户一切正常。并行编排多个技能互不依赖同时执行节省时间。典型场景是查天气和查航班同时进行。循环编排对一组数据逐个执行同一个技能。典型场景是批量检查多个服务的健康状态。这些模式在代码层面就是普通的控制流但关键问题是谁来编排我试过两种策略效果差异巨大。4.2 周报自动生成场景的编排拆解拿我做过的周报Agent当例子。这个Agent的核心目标用户说帮我生成这周的周报它要自动汇总本周的日程、代码提交记录、待办完成情况然后生成一份结构化的周报。我最初设计为链式调用def generate_weekly_report(user_id): # Step 1: 查询本周日程 events query_calendar(user_id, week) # Step 2: 查询代码提交记录 commits query_code_commits(user_id, week) # Step 3: 查询待办完成率 todos query_todo_stats(user_id, week) # Step 4: 汇总生成周报 report generate_report(events, commits, todos) return report第一个版本就是把四个技能用Python代码固定编排好顺序执行。效果很稳但有个问题用户的需求一旦变化比如只汇总日程和待办不要代码记录代码逻辑就要改。后来我改成了模型生成计划代码执行计划的方式。模型先看用户意图生成一个技能执行计划比如[ {skill: query_calendar, params: {user_id: ..., range: week}}, {skill: query_todo_stats, params: {user_id: ..., range: week}}, {skill: generate_report, params: {}} ]然后一个计划执行器按顺序执行这些技能再把结果汇总。这种方式灵活度高但稳定性比固定代码差一截需要在编排层加约束。4.3 动态编排让模型当指挥的得失模型动态编排最大的坑在于它会自作主张。我遇到过模型在生成周报计划时自己发明了一个不存在的技能叫get_weekly_summary注册表里根本没有。还有一次模型擅自改变了技能执行顺序先调生成报告再查数据结果报告里全是空的。后来我加了两道保险只允许从注册表已有技能中选择。模型生成的计划必须在已注册技能集合内否则直接拒绝并让模型重新生成。计划校验器。用Schema定义计划的格式校验技能名是否存在、参数是否合法、是否包含必选步骤。加了这两道保险之后动态编排的稳定性基本赶上了固定代码编排同时保留了灵活度。我现在的建议是核心流程用固定代码非核心或长尾需求用动态编排两者结合的收益最高。5. 实测踩坑记录技能冲突、上下文污染与幻觉兜底技能化架构不是银弹它只是把一部分不确定性从模型侧转移到了工程侧。工程侧的坑一点也不少。这一章是全文最硬核的部分我把实测踩过、又逐一解决的坑位写清楚。5.1 技能描述写太泛模型总选错这是第一个版本遇到的问题。我一开始把query_weather的描述写成查询天气信息。结果用户问上海适合穿什么衣服模型居然把它路由到了query_weather。表面看也没错但查询天气返回的只有气温和降水根本没有穿衣建议模型只能硬编一个。后来我研究了一下模型选择技能的行为模式发现它特别吃边界描述。所以我给每个技能的description加了正反两面描述正面当用户询问天气、气温、降雨、风力等情况时使用。 反面不适用于穿衣建议、空气质量、台风路径、历史气候统计这些请使用或路由到其他技能。这个改动让技能选择准确率提升非常明显。为什么因为负面描述减少了语义空间的不确定性模型在匹配时有了排除项不再把相似但不等同的意图拉进来。5.2 上下文污染模型分不清哪个结果对应哪个请求并行编排或连续编排多个技能时所有技能的结果都堆在上下文里模型经常分不清哪段数据是哪个技能的。一开始我以为这是小事后来发现后果很严重。最典型的一次事故用户先问北京天气怎么样再问那北京明天呢Agent先调query_weather(北京, 1)又调query_weather(北京, 2)两次结果都在上下文里。模型在生成回复时引用了第一天的数据回答第二天的天气而且语气非常确定。解决方案是在结果规整阶段给每段技能结果加明确的标签前缀[技能: query_weather | 参数: {location: 北京, days: 2} | 时间: 2025-01-14 10:30:22] 天气服务返回北京明天2025-01-15有小雨气温5~9℃。这样一来模型能清楚区分哪个请求的哪个返回。加标签之后上下文污染导致的错答问题基本消失了。5.3 幻觉兜底技能失败后模型编答案这是所有坑里最危险的一个。技能执行失败返回了错误信息但模型拿到错误信息后不会老实说查询失败而是会基于错误的上下文猜测一个合理答案。比如天气服务超时模型直接回答北京明天多云气温8℃——它自己编的语气还特别笃定。我排查了很久才发现问题出在错误信息的措辞上。我之前返回的错误JSON是{ status: error, message: 服务超时 }模型看到这段文字可能理解成这是用户的查询结果。后面我改成强语义的错误隔离格式并且在回填上下文时对错误结果前缀加上明显的阻断标记[执行失败] 技能 query_weather 调用异常天气服务超时。请不要猜测或编造结果直接告知用户服务暂时不可用。同时在系统提示里写死一条规则当技能返回状态为error时严禁编造任何数据结果。这一套组合拳下来才把幻觉应答率压到可接受的范围。5.4 常见坑位速查表把这一章踩过的坑整理成一张表方便直接排查现象根因解决方案技能选择不准description缺少负面示例正反两面写描述明确排除场景模型传非法参数未做Schema校验加JSON Schema严格校验层多个结果混淆上下文缺少结果标识结果回填前加技能名参数标签技能失败后编答案错误信息被当成正常结果强语义错误隔离系统提示禁止编造动态编排乱序模型自由度高计划Schema校验只允许注册表内技能一个技能报错整站不可用缺少超时与降级统一timeoutretryfallback这张表是我每次接入新项目时都会拿出来核对一遍的清单省了很多线上下排查的时间。6. 技能库的演进方向复用、评测与生态化agent-skills从最初的一个简陋脚本变成一个勉强能称为框架的东西中间最大的转折就是我意识到技能的维护成本和技能的复用价值决定了这套架构能不能活下去。技能写得再漂亮如果不可评测、不可复用那它只是又一套一次性代码。6.1 独立评测是技能复用的前提单个技能在集成到Agent之前必须可独立评测。我在每个技能定义里强制加了一个evaluate函数负责跑一组预先设计的测试用例。比如query_weather的评测集至少包含正常查询北京明天天气如何 → 期望命中query_weather且参数解析正确边界输入北京和上海哪个更冷 → 期望不直接命中单城市天气技能可能需要对比逻辑负面场景推荐一件适合北京的羽绒服 → 期望不路由到query_weather评测逻辑很简单跑一组输入看技能路由选择对不对、参数解析对不对、最终输出质量如何。只有通过评测的技能才有资格注册到生产环境的技能库里。这套机制让我敢放心地加新技能不用怕污染已有的能力。6.2 观察指标调用成功率、延迟与Token消耗技能上线后监控指标是另一个关键环节。我每个技能挂钩了三个核心指标调用成功率成功执行的次数 / 总调用次数。延迟从发起调用到返回结果的耗时P50和P99都要看。Token消耗技能描述、参数Schema、结果回填一共吃掉多少上下文Token。Token消耗是最容易被忽视的。一套大技能库每个技能的description都可能几百字把这些描述全部塞给模型每次对话都要消耗大量Token。我后来采用了一种按需加载的策略——先用粗筛选出候选技能只把候选技能的描述和Schema注入上下文而不是每次把全部技能定义都塞给模型。这招让每次调用的Token成本降了将近一半。6.3 从个人技能库到团队技能市场当技能数量超过二十个之后我开始有意识地把它当成一个市场来运营。团队里每个人都可以提交技能但必须先满足三件事有完整的五要素定义、通过评测集、有监控指标的报告。程序上收窄就会倒逼质量。这里有一个真实的体会少即是多。我曾经维护过一个六十多个技能的库里面一半技能一个月都没被调用一次。这些僵尸技能不仅占用上下文还会干扰模型的选择。后来做了一个季度清理把所有调用率低于1%的技能下线Agent的整体回答准确率反而涨了一截。我现在对技能库的目标不再追求数量而是追求每个技能都能回答三个问题它能解决什么问题、它不能解决什么问题、它失败了会留下什么可追踪的痕迹。想通这三点技能的体系就算立住了。