Agent Skills实战：从Function Calling到技能调度系统

1. 为什么我会动手折腾 agent skills 这件事1.1 所谓 Agent Skills到底解决的是哪类问题先说结论agent-skills 这个词最近在 AI 应用圈子里出现的频率越来越高但你如果去翻那些项目仓库会发现它并不是一个严格定义的学术概念更多是大家在实战中沉淀出来的一种“给智能体封装能力”的工程范式。简单讲它就是把一个智能体需要执行的某个具体任务——比如检索文件、运行 Python 脚本、调用外部 API、处理表格数据——抽成一个独立的、可注册、可调度、可复用的“技能单元”然后让大模型在对话中动态选择合适技能来完成用户的真实需求。我为什么要专门写一篇东西聊这个因为过去半年我一直在做助手类产品的后端最大的体会就是直接让大模型裸奔式地回应用户请求跟把各种能力封装成“技能”再交给模型调度体验完全是两个量级。裸奔的时候模型遇到稍微复杂一点的需求就会开始“胡编”——它不是不想做好而是缺少一个明确的能力边界和调用路径。你问它“帮我把这份 CSV 按月份汇总一下”它能给你写一段看起来很像样的 Python 代码但代码跑不跑得通、数据格式对不对它完全不负责。而当你把“CSV 汇总”封装成一个带参数约束、带执行逻辑、带结果回传的 skill 之后模型只需要做它最擅长的事情理解用户的意图、填好参数、触发执行剩下的脏活累活交给技能去完成。所以这个东西适合谁看两类人。一类是正在做 AI 应用、但发现纯 prompt 工程已经顶不住复杂场景的开发者另一类是想把团队里已经沉淀下来的各种脚本、API、工作流统一接入到大模型对话体系里的技术负责人。这篇文章不聊那些花哨的 Agent 框架也不炒概念就把我实际搭建一套 agent-skills 系统时踩过的坑、验证过的方案、写过的核心代码拿出来跟你一条条过一遍。1.2 它跟普通 function calling 有什么区别很多朋友一听到 agent skills第一反应是“这不就是 function calling函数调用吗”确实有关系但严格说它是 function calling 的一种升级形态或者说是站在函数调用之上的一层更完整的工程封装。function calling 解决的是“让模型从一堆函数里选一个并生成正确的参数”这件事。它给模型的是一个扁平的函数清单每个函数有名字、有描述、有参数 schema。模型在每次对话时根据用户输入决定“我要调用哪个函数、传什么参数”。这套机制本身非常成熟OpenAI、Anthropic、Google 的模型都有原生支持我早期也是这么干的。但用着用着你会发现几个痛点。第一个痛点是函数数量一多模型的选择准确率会明显下降。你挂 10 个函数的时候还好挂到 30 个、50 个的时候模型经常会在两个功能相似的函数之间犹豫甚至干脆选错。第二个痛点是单个函数太“细”。真实的用户需求往往是“我要做数据分析”拆开来看至少涉及读文件、清洗数据、聚合统计、生成图表四个步骤你要是只给模型一个“执行 Python 代码”的函数它倒是全能干了但你根本没法控制它在代码里干了什么——安全性和稳定性都是大问题。第三个痛点是没有状态和上下文。function calling 是“无记忆”的每次调用都像第一次见面技能中途失败、重试、结果缓存这些事全得自己另写一套逻辑。Agent skills 的思路本质上是在 function calling 之上加了一层“技能层”每个技能不再是孤立的函数而是一个自包含的执行单元它既有模型的调用入口名字、描述、参数 schema也有自己的执行逻辑、前置条件、后续处理。整个系统分两层外层是模型的“技能选择器”内层是技能的“真正执行器”。模型只负责做路由决策具体怎么干由技能内部实现说了算。这样设计的好处非常直接能力边界清晰了、单个技能可以做得足够复杂、而且多个技能之间可以通过编排组合出更大粒度的能力。我后面会拿完整代码演示这套结构。2. Agent Skills 的核心设计与落地模型2.1 技能描述给模型一张“能看懂”的技能地图如果你把所有技能都注册好之后发现模型总是不调用你希望它调的技能那问题大概率不是出在模型身上而是出在你的技能描述写得太“程序员化”了。这一点我特别想先拎出来讲因为它是整个 agent-skills 系统里投入产出比最高、却最容易被忽视的部分。我在设计技能描述的时候遵循一个很朴素的准则假设对面坐的是一个刚入职的实习生他手边有一堆工具你需要让他光看工具标签就知道哪个工具对应哪类活儿。描述要回答三个问题这个技能是干什么的、什么场景下应该用、什么情况下不应该用。举个实际例子。早期我把一个技能描述写成“execute_sql_query(query: string)”结果模型在用户问“帮我看看上个月销售额是多少”的时候经常不选它反而去选一个叫“run_python_script”的技能。后来我把描述改成“在用户需要查询数据库、分析表格数据、获取统计结果时使用。支持传入标准 SQL 语句。注意如果用户只是问文本类问题不要使用本技能。”效果立刻好了很多。不光是加了场景还加了“什么时候不要用”的负向提示模型在语义匹配上的困惑度会明显下降。还有个细节是技能分类。当技能数量超过 15 个之后建议在描述里带上明确的领域前缀比如“数据处理 文件读取”“数据处理 聚合统计”“绘图 柱状图”。模型在路由时看到这种分类信息会更容易锁定正确的技能组然后在小范围内做精确选择。这跟你自己用搜索引擎时先限定分类目录再找具体页面是一样的逻辑。我实测下来技能数量 20 个左右时带分类前缀比不带分类前缀的选择准确率能差出 8 到 12 个百分点这个提升在工程上是实打实的。2.2 参数合约把自由度控制在模型能搞定的范围技能描述决定了模型选不选得对参数合约决定了模型用不用得顺。这一块我踩的坑最多也是我后来反复跟团队强调的“技能设计最核心的环节”。所谓参数合约就是每个技能暴露给模型的参数定义。很多人写这块的时候会犯一个毛病参数定义得特别粗全用 string 类型描述写一句“用户的请求内容”。这种设计等于把自由裁量权全部交给了模型结果就是模型传参随心所欲——同一个技能这次传一个 JSON 字符串下次传一个自然语言句子下下次传一个数组你的技能执行代码就得不停地做兼容处理且每次都有可能解析失败。后来我定了一个硬性规则所有参数必须用结构化 schema 定义能枚举的字段绝不放任自由输入能拆成多个参数的就不要塞成一个对象每个参数必须写明格式要求、取值示例、常见错误。举个例子。我有一个“生成月度报表”的技能早期只有一个参数 payload后来我拆成了 report_type、start_date、end_date、group_by 四个参数每个参数都有明确的枚举或格式约束。模型需要做的工作变简单了就是把用户自然语言里的信息映射到这四个字段上剩下的组合、处理、生成全在技能内部完成。结果非常明显参数解析失败率从最早的接近 30% 降到了 5% 以下。这里有个关键点你要明白——模型天然是一个“填空题选手”你给它越清晰的空位它填得越准你给它一个空白作文纸它就只能自由发挥而自由发挥对稳定性来说往往是灾难。2.3 状态与权限技能不该是无限制的“万能遥控器”技能系统上线跑了一段之后我开始认真考虑两件容易被人忽略的事状态管理和权限控制。这俩问题在最开始只有几个技能的时候完全不是问题但技能一多、用户一多瞬间就能变成事故现场。先说状态管理。function calling 时代函数是无状态的每次调用一拍两散。但技能不一样一个技能可能是一个多步骤的执行流程。比如“数据清洗”技能它可能要经历读取文件、识别格式、处理缺失值、输出清洗报告四个阶段其中任何一个阶段失败都需要知道上下文从哪里恢复。我的做法是给技能调用引入一个 session 概念每次技能执行都会生成一个 execution_id技能内部的关键中间结果、状态快照都挂在这个 execution_id 下面。这样技能内部可以自愈外部也能对执行过程做审计。权限控制就更要命了。技能一旦能操作文件、能访问数据库、能调外部 API它就是一个“有手有脚”的执行体比单纯只会“说”的模型危险得多。我的原则是最小权限原则每个技能声明自己需要访问的资源范围调度内核在执行时强制校验。比如读取文件技能只能访问指定工作目录下的文件数据库查询技能只能用一个只读账号连接。你可能觉得这些是老生常谈但在我接触过的很多 agent 项目里这部分往往是最薄弱的——大家光顾着让模型“能干”没怎么考虑“哪些不能干”。等真的出现一次误删文件或者越权访问再回头补就非常被动了。3. 手写一套技能系统从注册到调用的完整实现3.1 技能注册与元数据组织概念聊完了上点干货。下面这套实现我尽量精简保留核心骨架但设计思路和线上版本一致。技术栈用的是 Python模型接口我按 OpenAI 风格的 SDK 来写你换成任意兼容的模型服务都可以。技能系统的底层就是一张注册表。每个技能被一个装饰器标记注册到全局字典里字典的键是技能名值是技能对象。技能对象包含五部分name技能名、description给模型看的技能描述包含场景和反例、parameters参数 JSON Schema、handler真正的执行函数、permissions所需权限声明。我直接贴代码。# skills/registry.py from typing import Callable, Any, Dict, Optional import inspect SKILL_REGISTRY: Dict[str, Skill] {} class Skill: def __init__( self, name: str, description: str, parameters: dict, handler: Callable[..., Any], permissions: Optional[list[str]] None, ): self.name name self.description description self.parameters parameters self.handler handler self.permissions permissions or [] def execute(self, arguments: dict) - dict: # 参数校验、权限校验都放在这一层 try: result self.handler(**arguments) return {status: success, result: result} except Exception as e: return {status: error, error: str(e)} def skill(name: str, description: str, parameters: dict, permissions: Optional[list[str]] None): def decorator(func: Callable[..., Any]): s Skill( namename, descriptiondescription, parametersparameters, handlerfunc, permissionspermissions, ) SKILL_REGISTRY[name] s return func return decorator这里有一个我特别想强调的设计执行函数 handler 和模型路由是解耦的。handler 就是一个普通 Python 函数它不关心什么大模型、什么 token、什么 prompt它只负责“收到结构化参数 - 干活 - 返回结果”。这个解耦带来的好处是你的技能函数可以单独写、单独测、单独特调完全不依赖整个 agent 系统复用性也非常好。我团队里现在很多技能是数据分析同事写的他们根本不关心模型怎么调用它。3.2 调度内核让模型“点单”而非“炒菜”有了注册表接下来就是核心的调度内核。所谓的调度内核干的事情说起来非常简单把系统提示词和可用技能列表交给模型让模型决定调用哪个技能、传什么参数然后执行技能、把结果返回给模型模型再结合结果生成最终回答。这整条循环就是 agent 最经典的 ReAct 模式但实现细节上有不少讲究。# skills/agent.py from openai import OpenAI from .registry import SKILL_REGISTRY client OpenAI() def build_system_prompt() - str: lines [ 你是一个能够调度技能完成任务的助手。, 当用户请求涉及具体操作时你必须选择最合适的技能并传入正确的参数。, 技能执行结果会以工具消息的形式返回给你请基于结果继续回答。, 如果你认为没有技能可处理该请求请直接拒绝或告知用户调整需求。, ] return \n.join(lines) def build_tools_payload(): tools [] for name, skill in SKILL_REGISTRY.items(): tools.append( { type: function, function: { name: skill.name, description: skill.description, parameters: skill.parameters, }, } ) return tools def run_agent(user_message: str, max_rounds: int 5): messages [{role: system, content: build_system_prompt()}] messages.append({role: user, content: user_message}) for _ in range(max_rounds): resp client.chat.completions.create( modelgpt-4o-mini, messagesmessages, toolsbuild_tools_payload(), tool_choiceauto, ) msg resp.choices[0].message messages.append(msg) # 模型没有要求调用技能说明对话可以结束 if not msg.tool_calls: return msg.content for tc in msg.tool_calls: skill SKILL_REGISTRY.get(tc.function.name) if skill is None: messages.append({ role: tool, tool_call_id: tc.id, content: 技能不存在请向用户说明。, }) continue import json args json.loads(tc.function.arguments) exec_result skill.execute(args) messages.append({ role: tool, tool_call_id: tc.id, content: json.dumps(exec_result, ensure_asciiFalse), }) return 执行轮数超限请稍后再试。这套内核跑起来之后整个交互就很像“点单制”用户说需求模型当服务员技能当后厨。模型根据菜单技能列表判断用户要什么然后把订单参数传给后厨后厨做好菜端回去服务员再把菜摆盘组织语言送到用户面前。模型从头到尾不需要自己动手“炒菜”它只需要做决策和表达。这个模式的可控性比让模型直接写代码执行高出一个层级。3.3 技能执行与结果回传的细节处理主循环跑通了但真正决定上线体验的往往是那些骨架之外的琐碎细节。我挑三个最影响稳定性的点详细说说。第一个是结果截断。技能执行结果可能非常长——你让模型跑了一个数据分析技能返回一个几千行的 CSV 或大段 JSON如果你不做任何处理直接塞进 messages 里下一轮请求的 token 量会飞速膨胀很快就会超上下文窗口。我的做法是在 result 回传前做一个智能截断默认只保留前 2000 个字符同时把完整的执行报告单独存储只在消息里附一个 report_id 方便后续追溯。为了让模型在信息不足时知道还有更多数据可看我还加了一句话“完整结果过长已截断如需查看特定部分请明确询问”。这样模型就会知道去向用户追问、或者去调用另一个查询技能而不是对着截断的数据瞎猜。第二个是异常信息要“翻译”成人话。技能执行抛异常的时候如果你直接把 Python 的 traceback 原样丢给模型模型倒是能看懂一部分但生成给用户的回答通常很生硬充满了“KeyError: month”这种术语。我在 Skill.execute 里做了异常兜底统一返回结构化错误同时在描述里要求模型“必须用用户能理解的语言解释错误说明可能的原因和下一步建议”。这样用户体验会好很多。经验之谈agent 应用里异常处理不只是给程序员看的更是给模型看的“上下文材料”。第三个是并发和超时。线上环境里同一个技能可能被多个用户同时触发如果技能里有共享资源比如一个全局变量或文件句柄并发问题就会找上门。我查过几次线上 bug最后发现都是技能函数里用了模块级变量导致的。现在的规范是所有技能函数内部只使用局部变量共享数据一律通过参数传入。超时方面每个技能执行我都建议用 asyncio.wait_for 包一层给一个合理的上限——数据分析类技能我给 60 秒文件读取类技能 10 秒比这更长的操作改成任务队列异步执行。这一步看着不起眼但能救你很多次——模型是不等人的技能卡死会直接把整个 agent 卡成呆滞状态。4. 实操中踩过的坑与排查指南4.1 模型老是选错技能怎么办这个问题我收到的抱怨最多。技能一多模型就开始“乱点鸳鸯谱”明明有专门的技能不用非要选一个效果相近的替代品。排查思路我一般分三步走。第一步看描述里有没有负向约束。我之前说过描述里强调“什么情况下不要用”是提升区分度的利器。比如“查询订单”和“查询用户”两个技能如果都只写“查询数据”模型区分不开很正常但如果分别写明“订单查询技能仅用于查询订单状态、金额、物流等信息。用户问题涉及个人资料如姓名、手机号时请使用查询用户信息技能不要使用本技能”准确率立刻能上来。第二步看技能名称是否足够语义化。早期为了图省事我用过 sort_data、cli_run 这种内部代号做技能名结果模型完全抓瞎。后来统一改成“数据排序处理”“命令执行工具”这种可以直接从名字推断用途的风格选择准确率又涨了一截。不要小看名字的作用模型在路由时对名字和描述是同样看重的。第三步检查参数 schema 是否有歧义。有时候模型选错技能不是因为技能本身分不清而是因为它想传的参数在目标技能里找不到对应的字段于是退而求其次选了一个参数“宽松”的技能。这种情况就回到参数合约的问题上了——把技能能处理的操作边界在描述里说清楚参数字段宁可多定义几个必备项也不要留一个万能的 options 字符串。如果这三步都走完还是频繁选错我才会考虑上更重的方案比如给技能加一个“预路由”分类器先用一个小模型或者规则引擎把用户请求分到大类再在大类内部让大模型精确选择。但这是少数场景才需要的优化大多数项目把前三点做好就够用了。4.2 参数解析失败和幻觉参数模型调用技能时传参不规范的频率比你想象的高得多。我最早期上线第一天就遇到一个经典案例用户说“查一下最近30天的数据”技能参数定义是 start_date 和 end_date模型老老实实传了两个日期字符串但格式一个是“2024-05-01”另一个是“5月30日”。这种“幻觉参数”不一定是模型凭空捏造更多时候是它理解得不够精确就把语义直接塞了进去。针对这个问题我在技能参数处理上加了三道保险。第一道是强类型校验每个参数进来先按 JSON Schema 校验类型类型不对直接拒绝并返回明确错误提示。第二道是格式归一化比如日期、百分比、金额这些常见格式在技能内部做一层解析器能兼容多种常见的自然语言写法归一化为统一格式再往下传。第三道是缺省值兜底有些参数是必填的、有些是可选的我会在参数 schema 里把必填项标得非常清楚并且用 required 字段约束模型模型没传必填参数时返回错误信息并模糊提醒“缺少必要参数start_date”让模型自己意识到问题后补充。这里我特别想提醒一个容易踩的误区不要为了让模型“少犯错”就无限放宽参数校验。有一段时间我把所有参数都设计成宽松可选容错率确实高了但带来的副作用是模型越发不认真读 schema传参越来越随意整个系统的可预测性大打折扣。后来我收回了一部分宽容度对必填字段坚决要求格式合规模型反而变得更“守规矩”了。这就像一个团队里如果永远没有硬性标准大家做事就会越来越潦草。4.3 上下文过长、执行超时与并发冲突这三个问题几乎是 agent 应用上线后一定会遇到的“三座大山”。我分别讲一下我的应对办法不一定最优雅但都是在真实环境验证过的。上下文过长是最快出现的。用户跟 agent 聊上十轮八轮每轮都触发一两个技能messages 里累积的工具执行结果可能比正文还长。我的处理方案是分层压缩对历史对话做摘要对工具结果做截断对技能输出做统计摘要而非全文回传。核心原则是“模型需要的信息保留用不到的彻底丢弃”。比如数据分析技能我回传给模型的不是完整表格而是“总行数、列名、前5行预览、缺失值统计”这一组摘要指标模型基于这些足以回答大多数问题。等到用户真想看数据细节再走下一个技能去拉。执行超时的问题本质上要区分“操作本身慢”和“系统卡死”。前者用异步化解决——技能一旦超过一定时间立刻返回“任务已提交正在后台处理”轮询或者回调再更新结果后者要靠超时和重试机制兜底避免无限等下去。我见过不少项目没做超时控制结果模型等技能等得都快把用户晾在那了这种体验绝对不能接受。并发冲突最经典的场景是多个用户同时触发“写文件”或“改配置”类技能导致数据互相覆盖。我的方案是给这类技能加锁同一时间内同一资源只允许一个技能执行再往根上治理就是技能设计时尽量避免共享可写状态必要写入时用带唯一后缀的临时文件处理完再原子替换。这套思路跟我维护普通后端服务时的一致本质上没有区别只是很多人写 agent 时下意识觉得“AI 应该有特权”忘了它背后的执行代码跟普通程序没两样。5. 快速验证技能效果的实测方法5.1 用评测集代替“拍脑袋调优”技能系统搭好之后最忌“感觉挺好”就直接上线。我吃过亏。有一版技能系统改了几个描述自己试了几轮感觉顺畅多了结果上线后用户反馈“模型还是不怎么调用新技能”。后来我才发现我自己测试时用的那几条 query 太典型、太容易匹配根本覆盖不了真实用户千奇百怪的说法。后来我养成了一个习惯给技能系统维护一个评测集。每个技能下面挂至少 10 条真实用户可能说的话包含标准表述、口语化表述、模糊表述、负向样本不应该调用本技能的输入四类。每次调整完技能描述或参数 schema就把评测集完整跑一遍统计技能选择准确率、参数解析成功率、任务完成率三个指标。这个做法看着笨但它能让你在改了一个描述后清楚地知道这次改动是变好了还是变差了而不是靠感觉猜。我印象很深的一回我把一个技能描述里增加了一句“如果用户只是询问数据是否存在请直接回答不要调用本技能”结果这个技能的误触率从 18% 降到了 6%同时其他技能的调用率几乎没受影响。这种优化没有评测集根本发现不了。5.2 日志是最好的老师就算你评测集做得再齐全也不可能覆盖所有线上场景。所以日志系统必须从第一天就做好。我这里说的日志不是普通的 print 输出而是结构化的技能调用日志至少要记录用户原始输入、模型选择了哪个技能、模型生成的参数原文、参数校验结果、技能执行耗时、执行返回结果摘要、最终用户看到什么。这些日志放在一起你能非常清晰地观察到模型的决策链条。排查实际问题的时候我通常按这条路径走先看用户输入和技能选择是否匹配不匹配就回到技能描述上去找原因匹配但参数解析失败就去查参数 schema 的约束是不是不够明确参数没问题但执行出错再去查技能内部逻辑和外部依赖。这套排查路径基本能解决九成以上的线上问题。有一次用户反馈“查不到上周的报表”日志一看模型选择了“报表查询”技能却把 start_date 传成了当前日期而不是上周日期——问题不在技能在于用户输入里的“上周”模型没有换算成具体日期。这个问题的解决方案是在技能描述里特别标注“涉及相对时间如今天、上周、本月时请先换算为具体日期再传入参数。”6. 最后分享一点我的选型与演进建议很多人看完上面的实现会问我要不要直接用现成的 agent 框架。我的观点是如果你只是做 demo、验证想法直接用 LangChain、LlamaIndex 或者各家平台自带的能力封装省心省力但如果你是做真正要上线的产品我建议至少把技能注册、技能执行、技能日志这三层自己写一遍。不是因为框架不好而是因为技能系统跟你的业务逻辑耦合太紧通用框架往往会在你最需要定制的地方变成瓶颈到那时候再改造的成本远高于一开始就自己搭一个轻量的。另外一个演进方向是把技能做成“可组合”的。我现在的系统里技能分两层原子技能是最基础的操作比如读文件、跑查询、发请求复合技能则是把多个原子技能按固定流程编排起来形成更上层的业务能力。比如“生成竞品分析周报”这个复合技能内部就是“抓取数据、清洗数据、聚合统计、生成文案、推送文档”五个原子技能的有序组合。模型只需要学会调用这一个复合技能就能完成一串复杂的任务这对用户来说体验是质的飞跃。而且复合技能可以由我们的业务团队自己配置不需要每次改代码整个系统的扩展性一下子打开了。最后再说一句关于“技能数量”的经验。技能不是越多越好每加一个技能模型选择时面临的干扰就多一分。我个人的经验是在模型能力没有特别强的情况下一次暴露给模型做路由选择的技能数量控制在 20 个以内比较稳妥。如果确实技能太多就上分组路由——先按领域分组用分类模型或规则确定领域再在对应组内做精确选择。与其让一个模型在 50 个技能里大海捞针不如让它在 5 组 10 个技能里精准定位效果和成本都更好控制。这套东西并不酷炫但每一层都是我在真实项目里被磨出来的。希望这篇分享能让你在搭自己的 agent-skills 系统时少走几步我已经走过的弯路。