Agent技能库从0到1：大模型工具编排的工程实践

1. 项目概述agent-skills 到底在解决什么问题第一次看到“agent-skills”这个项目名可能有人会以为它是个游戏角色的技能系统或者是某种职场软技能训练工具。但实际上在当下大模型应用快速落地的圈子里这名字指向的是一个很具体、也很关键的方向智能体技能库。简单说它是一套让 AI Agent智能体按需调用、组合、扩展“能力模块”的工程化方案。这两年做大模型应用的人应该都有同感模型本身越来越聪明但光有聪明的“大脑”不够Agent 要真正干活必须能操作外部工具、访问数据、执行复杂流程。早期做法是把所有能力都写死在代码里后来有了 function calling再往后大家发现技能太多、逻辑太杂维护成本直线上升。agent-skills 这种项目就是想解决这个痛点——把每个可复用的能力封装成独立“技能”让 Agent 可以像搭积木一样灵活选用而不是每次都在 Prompt 里堆一大堆混乱的指令。这篇文章我会从整体设计思路出发逐步拆解技能库的核心机制、实现细节、以及我在实际部署和调用中踩过的坑。适合正在做 Agent 应用、研究 AI 自动化工作流、或者对“大模型工具编排”感兴趣的朋友。不管你是用 Python 写过 function calling 的初学者还是已经在搞多 Agent 系统的老手这篇文章里应该都能找到值得参考的内容。2. 整体设计拆解为什么技能库是 Agent 工程的“基础设施”2.1 从“写死逻辑”到“动态技能”思路转变是关键早期我做 Agent 应用时习惯把调用外部 API、读取数据库、发送消息这些操作全部硬编码在业务流程里。比如用户问天气我就写一个 if 分支去调天气接口用户要查订单再写一个 if 分支去查数据库。这种方式在功能少时还算清晰但当技能扩展到十几个甚至几十个时代码会变得非常臃肿Agent 的决策逻辑也常常被大量无关分支干扰。agent-skills 带来的思路转变是把“能力”本身抽象成独立模块每个模块包含三个关键信息——触发条件、执行逻辑、返回结果的描述。Agent 在运行时根据用户的请求自动匹配技能而不是靠人为写死的 if-else 去决定调用路径。这个设计很像是给 Agent 装了一个“工具箱”它自己决定用哪把扳手、哪把螺丝刀而不是由你去替它选。这种思路的价值在实践中很快体现出来。最直接的一点是新增一个能力时你不再需要改动主流程代码只需要新增一个技能文件然后注册到技能库中即可。团队协作也是如此负责不同技能的人可以并行开发互不干扰。2.2 技能库比 Function Calling 高明在哪里可能有人会问OpenAI 的 function calling 不是已经能做这件事了吗为什么还要自己搞技能库我在对比二者后有一个很实际的感受function calling 更像是一个“协议”而技能库是建立在协议之上的“管理系统”。Function calling 的核心机制是你在请求里给模型一系列函数描述模型决定调哪个函数、传什么参数。它解决了“模型如何理解工具”的问题但它并没有解决“工具如何组织、如何管理、如何复用”的问题。举个具体例子如果你的 Agent 需要支持上万个历史订单查询或者需要根据环境变量动态禁用某些技能function calling 本身是做不到的你需要在外面包一层管理逻辑。agent-skills 这类方案的核心价值就是补上这层“管理逻辑”。它可以做到根据任务难易程度动态筛选可用技能而不是把所有技能一股脑塞进上下文技能之间支持组合调用复杂任务可以拆分成多个技能链式执行每个技能可以附带示例、使用限制、依赖关系等元信息帮助模型更精准地做决策所以我的理解是function calling 是“让模型能调用工具”agent-skills 是“让工具的集合可以被高效管理”。2.3 技能模块的抽象层次粒度太粗会笨太细会乱在设计技能库时最让我头疼的问题不是写代码而是“技能的粒度到底该定多粗”。我一开始把粒度切得很细比如“打开浏览器”“输入文本”“点击按钮”各是一个技能。结果发现 Agent 在处理复杂任务时经常迷失方向因为它需要顺序调用十几个细碎技能才能完成一个简单操作任何一个环节判断失误都会导致整个链路中断。后来我调整了思路技术的粒度应当对齐“用户的真实意图”而不是对齐“操作的最小单位”。举个例子“查询天气”“发送邮件”“创建日程”这些才应该是一个技能至于内部是调 API 还是操作浏览器那都属于实现细节。这个调整之后Agent 的决策准确率有了明显提升因为模型不需要在那么多低层操作中做选择。当然粒度也不能太粗。如果你把一个“处理所有办公自动化任务”封装成一个技能那本质上又回到了写死逻辑的老路上模型根本没有灵活性可言。找到一个合适的抽象层级需要结合你的实际业务场景反复测试这是技能库设计中最有艺术感的部分。3. 核心细节解析从技能定义到执行引擎3.1 技能描述怎么写直接影响调用准确率Agent 选择技能的依赖是什么不是依靠“心意相通”而是依靠技能描述文本。所以描述写得越精准模型选错技能的概率就越低。我最初尝试用一句话描述技能比如“查询用户订单数据”效果一般。模型经常把“查询订单”和“修改订单”搞混尤其在两个技能描述相似时。经过多轮测试我认为一个合格的技能描述应当包含以下要素功能定义明确说明“这个技能做什么”用词要具体避免宽松含糊适用场景说明“用户在什么情况下会需要这个技能”限制条件说清楚“这个技能不支持什么”提前帮模型排除错误选项参数说明每个参数的格式、范围、必填与否都要有清晰标注使用示例给出一个简短的调用示例模型可以通过类比理解我见过一些开源项目的技能库描述写得相当详细甚至会用一小段自然语言描述技能的输出格式。这看似冗长但实际上大幅降低了模型误判的概率。记住一个原则你在技能描述上偷的懒都会变成模型调用时犯的错。3.2 技能加载机制全部加载是最简单的方案但不是最好的方案另一个关键设计点是技能加载方式。最简单粗暴的思路是启动时把所有技能全部加载进去每次请求都把所有技能描述塞给模型。这种做法在技能数量少时可运行但当技能数量增长到几十个你会发现两个问题一是上下文窗口被大量无关描述占据真正有用的对话信息被挤压二是模型需要从一堆技能里选一个选择一多准确率就会下降。更合理的加载方式是“按需加载”。类似搜索引擎的思路先根据用户的请求做一个技能候选集筛选只把最相关的一批技能描述送入模型。我测试过一种很实用的实现维护一个技能索引表为每个技能打上标签和关键词请求进来时先做一次轻量级的语义匹配或关键词匹配筛掉明显无关的技能。这个机制还能处理一个更复杂的场景不同用户可能有不同的权限范围。比如普通用户只能调用查询类技能管理员才能调用配置修改类的技能。在技能加载阶段进行权限过滤比在执行阶段再校验要高效得多。3.3 技能组合执行流程串联、并联、还是条件分支真实的业务任务往往不是单个技能能搞定的这就需要技能引擎支持组合执行。我遇到过的最常见场景是串联执行比如用户说“总结一下今天所有未读邮件的要点然后把这些要点发到工作群里”这需要先调用“获取邮件列表”技能再调用“总结内容”技能最后调用“发送群消息”技能三者必须按顺序完成。串联执行的关键在于“信息传递”。前一个技能的输出结果如何转换成后一个技能的输入参数这是组合流程中最容易出错的地方。我的做法是定义一个统一的数据中间格式每个技能输出时都规范化后续技能从中间结构中提取自己需要的字段。这个设计让我避开了很多“字段名对不上”的尴尬情况。并联执行我用的场景相对较少但确实存在。比如需要同时查询多个来源的数据再汇总此时如果逐个串行查询耗时就会成倍增加。技能引擎需要支持并发调用并等待全部返回后再合并结果。这里要特别注意并发调用时每个技能的上下文是独立的不能共享中间变量所以并联流程设计要提前明确好数据合并的策略。条件分支则更复杂一些。比如用户意图可以走两条完全不同的路径Agent 需要根据中间结果判断走哪条分支。这种场景下我的经验是不要让技能引擎本身去处理分支逻辑而是把分支决策权交给模型每次技能执行完后把结果送入决策模块让模型决定下一步该调用哪个技能。这种方式牺牲了一点效率但换来了更大的灵活性。4. 实操过程从零搭一个最小可用的技能库4.1 环境准备和基础框架选择我建议先从一个人单枪匹马能维护的最小框架开始。别一上来就上分布式任务调度、消息队列这些重型组件除非你的场景是真的大规模并发。我搭建时的环境配置如下Python 3.10主流大模型框架都有较好的支持使用 FastAPI 提供 HTTP 接口便于后续扩展技能注册采用目录扫描方式新增技能文件即自动注册用 Pydantic 做参数校验和数据中间格式定义模型接口使用 OpenAI 兼容格式方便更换不同后端这套技术栈的好处是简单、文档多、遇到问题能搜到大量现成答案。作为一个实验性的项目骨架它足够稳定能满足绝大多数初期的功能验证需求。4.2 技能定义的数据结构我踩过的坑我试过最少字段的方案每个技能只有名称、描述、函数指针三个字段。这个方案在初期很顺利但技能数量一多就发现了短板没有参数描述的情况下模型经常编造出根本不存在的参数名导致执行阶段频繁报错。后来我参考了 OpenAI function calling 的参数定义方式为每个技能增加了完整的 JSON Schema 风格参数结构。一个典型的技能定义文件我建议至少包含这些字段{ name: search_web, description: 根据用户提供的关键词搜索互联网内容返回相关网页标题和链接列表。适用于用户需要查找最新资讯、了解某个话题的情况。, keywords: [搜索, 查询, 资讯], parameters: { query: { type: string, description: 搜索关键词例如2025年人工智能大会上发布了哪些新模型, required: true }, max_results: { type: integer, description: 返回结果数量默认为5最大不超过20, required: false } }, handler: web_search, timeout: 10 }这里特别注意keywords字段这是我后来加上的。虽然模型可以理解自然语言描述但增加一组明确的关键词可以配合简单的文本匹配做初筛在加载阶段就过滤掉明显不相关的技能。这个字段带来的准确率提升很可观强烈建议加上。4.3 核心执行引擎实现其实没那么神秘核心执行引擎的作用是把模型的决策翻译成实际的 Python 函数调用。它的工作流程很简单接收用户的请求文本从技能库中筛选候选技能将候选技能的描述送入模型模型返回选定的技能名和参数 JSON引擎根据技能名查找对应函数解析参数后调用将函数结果格式化后返回给模型生成最终回复对照代码大概长这样from fastapi import FastAPI, HTTPException from pydantic import BaseModel app FastAPI() class Skill: def __init__(self, name, description, json_schema, handler): self.name name self.description description self.json_schema json_schema self.handler handler # 技能注册表 skills {} def register_skill(skill): skills[skill.name] skill class AgentRequest(BaseModel): user_message: str conversation_id: str None def filter_candidates(user_message): 根据关键词和语义对技能做初步筛选 # 这里用简单关键词匹配演示实际可按需替换成向量检索 msg_lower user_message.lower() matched [] for skill in skills.values(): for kw in skill.json_schema.get(keywords, []): if kw.lower() in msg_lower: matched.append(skill) break return matched or list(skills.values()) def call_llm_to_choose_skill(candidates, user_message): 将技能描述拼成 prompt 送给模型让模型返回选择结果 # 项目里实际使用的 prompt 模板 skill_lines [] for skill in candidates: skill_lines.append( f技能名: {skill.name}\n描述: {skill.description}\n参数: {skill.json_schema[parameters]} ) prompt ( f用户请求: {user_message}\n\n f可用技能:\n \n---\n.join(skill_lines) \n\n请根据用户请求选择最合适的技能并输出 JSON格式为{\skill\: \技能名\, \arguments\: {参数对象}} ) # 这里的调用省略具体模型 API 细节使用兼容 OpenAI 的客户端 # 返回一个 dict类似 {skill: search_web, arguments: {query: ...}} ... app.post(/agent/execute) async def execute_agent(req: AgentRequest): candidates filter_candidates(req.user_message) if not candidates: raise HTTPException(status_code404, detailNo skill matched) decision call_llm_to_choose_skill(candidates, req.user_message) skill skills.get(decision[skill]) if not skill: raise HTTPException(status_code400, detailSelected skill not found) args decision.get(arguments, {}) try: result skill.handler(**args) except Exception as e: return {status: error, error: str(e), skill: skill.name} return {status: ok, skill: skill.name, result: result}有几点我说一下实际运行后的体会。第一候选技能筛选一定不能太严格宁可多给模型几个选项也不要误删关键技能。我最初的关键词匹配写得太严导致用户表达方式稍微变化技能就筛没了。后来调整策略关键词匹配是“加分项”而不是“必要条件”没有任何技能匹配时全部加载兜底避免漏选。第二模型返回的 JSON 需要做健壮性处理不一定每次都严格符合格式有时会漏掉引号或拼错参数名。我建议在解析环节加一个容错层遇到解析失败时重新让模型生成一次而不是直接崩溃。4.4 技能函数的编写规范与超时控制有了技能定义和引擎框架剩下最关键的就是写技能函数本身。这个部分最容易被人忽略但粗暴地说——你的技能库最终靠不靠谱70% 取决于函数写的质量。我给自己定的技能函数编写规范是每个技能函数应当是无状态的不依赖上一个技能调用的遗留数据函数内部必须做异常捕获并把异常转成可读的错误信息返回给模型函数要有明确的超时控制尤其涉及外部 API 调用时不能无限等待输出统一为结构化数据不要直接打印人类可读的大段文本超时控制值得单独提一句。我一开始没做超时控制结果一个技能调用了某个响应极慢的第三方接口导致整个 Agent 请求卡住几十秒用户的体验非常糟。后来我在技能定义结构里加了timeout字段在引擎层用asyncio.wait_for包了一层超时后返回错误信息模型就能根据这个错误决定下一步是重试、换方案还是请用户补充信息。这引出一个重要认知技能函数不应该只返回成功的数据也应该返回清晰、结构化的失败原因。模型本身是有推理能力的你给它一个“技能执行失败原因是接口超时”的反馈它有可能自己调整参数重试但如果你只给“Error”它就只能傻眼。5. 常见问题与排查技巧我在实战中踩过的那些坑5.1 问题一模型总是选错技能描述也写了还是选错这种情况在我早期使用中非常频繁。排查思路是这样的先看“候选技能集合”本身有没有问题。我发现一个很有迷惑性的坑——当候选技能集合里包含多个相似技能时模型选错的概率会显著上升。比如我有 5 个技能都和“文档处理”沾边模型很可能选到其中一个在语义上接近但你本意并不想用的技能。解决方法有两种。第一个方法是“归一化描述”把所有相似技能的描述风格、术语尽量统一并在描述里明确写清边界差异。第二个方法是“减少候选数量”通过关键词、标签或向量检索把候选压缩到 2~3 个再送给模型选择少准确率自然高。另外我强烈建议打开每次调用时模型的“决策日志”把模型选中的技能名、参数、用户请求原文都记录下来。你就能直观看到到底哪一步出现了偏差是提示词不清晰还是候选集合过滤有问题。5.2 问题二技能函数传参类型不一致总是报错最开始我天真地以为模型生成的参数一定是符合 JSON Schema 的 DTO。直到看到模型输出了page: 3字符串而函数定义里需要的是整数才意识到容错必须做在前端。后来我引入了 Pydantic 做运行时校验与转换在真正的业务逻辑执行前就把类型统一好。这个方法让我对参数类型的把握从“不可控”变成了“稳当”。还有一个更隐蔽的问题模型偶尔会编造函数定义里根本不存在的参数。我在试一次技能调用时技能定义里只有query和max_results但模型返回的参数里多了一个search_engine。后来我在参数解析时加了“额外参数过滤”把所有未知字段直接丢弃问题就解决了。5.3 问题三技能执行结果太长把上下文窗口撑爆了如果你调用的技能返回一个很大的数据结果比如搜索返回 20 条网页摘要每条摘要几百字一次调用就可能消耗掉几千 token。如果这个技能是串联流程的中间步骤后续还要再调用模型做总结上下文开销会让你很快逼近窗口上限。我的处理策略是技能函数在返回结果给模型之前先做一次“结果精简”。改写后的版本通常只保留核心摘要字段截断过长的文本把关键信息压缩到几百字以内。这个操作对最终生成质量的影响有限但对成本控制帮助极大。我是这么做的如果技能返回的是列表数据只取前 N 条并附上总条数说明如果返回的是长文本用摘要模型先做缩减。实践下来这套组合拳在保证效果的同时省了不少 token 预算。5.4 问题四技能调用链路很长中间哪一步失败了怎么办前面提到串联执行流程其中任何一个环节出问题整个链路就断了。比如“获取邮件→总结→发群消息”第二步总结成功了但第三步发送失败此时用户的真实预期是什么是要重试发送还是让 Agent 告诉用户“总结好了但发送失败需要再次尝试”我建议给每个链路步骤设计独立的“错误恢复策略”。对于幂等操作可以直接重试比如查询、搜索对于有副作用的操作比如发消息、改配置则必须谨慎不能盲目重试否则可能产生重复消息。我的方案是触发重试前检查是否有成功日志没有才执行有就直接返回上次结果同时在失败后让模型生成一个面向用户的解释性消息说明失败原因和下一步建议。这套机制虽然不能解决所有问题但能把“不可控的故障”转变成“可理解的交互”。6. 写在最后的几点实在建议做技能库这段时间我最大的体会是技术方案并不是越复杂越好真正好用的是能跟业务场景严丝合缝的方案。一开始我总想搞一个什么都能干的通用引擎后来发现每个业务场景对技能划分方式、加载策略、错误处理的要求差别很大通用方案往往意味着处处妥协。如果你正在规划自己的 agent-skills 项目我的建议是先把手头最频的 5~10 个场景做成技能跑通一个最小闭环。在这个过程中你会真切感受到哪些设计是有用的、哪些是多余的。等验证完第一版的功能闭环再逐步扩展技能数量、优化加载策略也不迟。再分享一个小技巧技能库上线后记得持续观察“模型选错技能”的日志这些日志是完善技能描述最宝贵的原材料。每隔一段时间把真实日志中选错的案例拿出来复盘校准描述文本和关键词准确率就会像滚雪球一样越滚越高。最后用一句话收束全文技能库的本质不是代码结构而是为“模型的无限能力”和“工程的可控运行”之间搭起的那座桥梁。把这座桥搭稳了Agent 才能真的跑起来。