Agent技能库设计：从函数调用到可编排的工程化实践

直接切入主题。最近在落地AI Agent相关项目，我发现一个很有意思的现象：很多人把Agent的骨架搭起来了，对话、记忆、规划都有，但真正用起来，效果就是不对。问题出在哪？出在Agent只会"聊天"不会"干活"。说白了，Agent缺的不是大脑，是手脚，而这双手脚就是我要聊的agent-skills。

我自己在做的这个agent-skills，本质上是一个技能库模块。它不是某个现成的开源框架，也不是某个特定平台的插件，而是一套让Agent具备可复用、可编排、可管理技能能力的通用设计。你可以把它理解为给Agent装上一个工具箱：需要查天气时有查天气的技能，需要算账时有算账的技能，需要操作数据库时有写SQL的技能。Agent根据用户的意图，自己去工具箱里挑合适的"工具"，而不是每次都靠模型临场发挥、自由发挥、乱发挥。

这篇文章我打算从设计思路讲起，再把核心细节、实操步骤、踩坑经验全部铺开来说。适合谁看？正在做Agent应用落地的工程师、研究LLM应用架构的开发者，还有那些把Agent接进真实业务但效果不稳定的团队。都会从中找到对应的解法。

1. 内容整体设计与思路拆解

1.1 先搞清楚Agent和"技能"到底是什么关系

很多人把Agent理解为"一个很能聊的模型"，这是最大的误区。模型本身是大脑，它有推理能力，但推理的终点如果只是生成文字，那它永远停留在"纸上谈兵"阶段。真实世界的Agent必须执行动作：调接口、查数据库、写文件、发消息、跑脚本。这些动作要能稳定、可靠、可重复地执行，就必须脱离"让模型直接生成代码"这种不可控的方式。

所以我把Agent的能力从下往上分成三层：底层是模型，负责理解意图和拆解任务；中间层是技能库，也就是agent-skills，负责提供原子操作；顶层是策略，负责决定在什么场景下调用哪些技能。技能层如果缺失，整个Agent就是个空壳。

再往深里说，技能的本质是什么？是一次被结构化的函数调用。它包含三样东西：契约、实现、描述。契约是描述这个技能参数格式的schema，实现是真正干活的代码逻辑，描述是给模型看的"说明书"，告诉模型这个技能是干什么的、什么时候该用、什么时候不该用。这三者缺一不可。

1.2 从单体对话到组合技能的演变

早期做AI对话应用，大家习惯把所有逻辑塞进一个巨大的Prompt里，让模型"看着办"。比如让模型直接写Python代码执行数据分析，看起来灵活，实际上极其危险：模型生成的代码可能有语法错误，可能操作了不该操作的文件，可能输出格式不稳定。我见过太多跑一次就崩的案例。

后来大家开始用函数调用（Function Calling）的方式，把工具定义传给模型，让模型在结构化参数中选择。这条路是对的，但只解决了"能调函数"的问题，没有解决"技能体系"的问题。函数调用是孤立的，每个函数都是一个孤岛，没有版本管理，没有依赖关系，没有权限控制，没有统一的可观测性。

agent-skills要做的就是把这一堆孤立的函数升级成一套完整的技能体系。每个技能有名字、有描述、有参数契约、有实现逻辑、有白名单权限，技能之间还可以编排组合。这就好比从"给员工一份手写清单"升级到"给员工一套标准作业流程+SOP工具库"。

1.3 技能库的本质：把模型能力变成工程能力

我做了不少Agent项目后，得出一个坚定的结论：模型的能力是天花板，但技能的工程化能力是地板。同一个模型，配上精心设计的技能库，和配上随手写的几个函数，落地效果可能天差地别。

为什么？因为模型的不确定性是天然的，但工程系统不能建立在不确定之上。技能库做的事情就是把模型的不确定性"关进笼子里"：模型可以决定先后顺序，可以决定参数取什么值，但最终执行的动作必须是预定义好的、经过测试的、行为可控的。这样一来，系统的可靠性从"赌模型这次不犯错"变成了"只要模型选对了技能，执行结果就是确定的"。

所以我在设计agent-skills时，第一原则就是：让技能执行路径尽量短、尽量确定。所有外部副作用操作全部封装在技能内部，Agent只负责做出选择和传参，不负责实现过程。

2. 核心细节解析与实操要点

2.1 技能清单设计：三个维度想清楚

设计技能库之前，先把技能清单列出来。我一般从三个维度梳理：场景维度、动作维度、数据维度。

场景维度回答"用户可能想干什么"。比如一个客服Agent，场景有查订单、退换货、开发票、催发货；一个数据分析Agent，场景有查指标、做趋势分析、导出报表。每个场景至少对应一个技能，复杂场景可以拆成多个技能。

动作维度回答"每个场景需要执行什么原子操作"。查订单需要调用订单接口；退换货需要调用售后创建接口加权限校验；开发票需要调用财务系统接口并同步状态。动作要拆到"不可再拆"的程度，比如"查询订单详情"和"解析订单列表结果"就是两个不同粒度的动作。

数据维度回答"这些操作涉及什么数据实体"。订单、用户、商品、发票、报表，每个数据实体就是一个技能的天然边界。我习惯把技能按数据实体聚合：订单域只放订单相关技能，用户域只放用户相关技能，避免技能之间相互纠缠。

这三个维度梳理完之后，技能清单基本就成型了。数量上我建议宁精勿杂，优先保证每个技能都是真实场景会用到的高频操作，不要为了技能数量好看而硬造需求。

2.2 技能函数的典型结构

一个标准的技能函数，我的模板是固定的：

def query_order_status(order_id: str) -> dict: """查询订单实时状态。 Args: order_id: 订单号，通常为字母和数字组合的字符串。 Returns: dict: 包含订单状态、物流信息、预计送达时间的字典。 """ # 1. 参数校验 if not order_id or len(order_id) < 6: raise ValueError("order_id 格式不合法") # 2. 调用内部数据服务 result = order_service.query(order_id=order_id) # 3. 结果规范化和脱敏处理 return { "order_id": result.order_id, "status": result.status, "logistics": mask_phone(result.logistics), "eta": result.eta.isoformat() }

注意几个细节。第一，参数校验不能省，模型传参时经常出现空值、格式错误、超长字符串，技能函数必须在入口处挡住。第二，返回结果一定要规范化，把所有字段统一成固定的结构，方便Agent后续的推理去解析。第三，凡是涉及隐私的数据（比如手机号、地址）在返回前就做脱敏，不要让敏感数据流入模型的上下文。

2.3 技能注册表与权限边界

技能不是函数写完了就完事，还要注册到一个统一的注册表里。注册表里要记录的信息包括：技能名称、技能描述、参数schema、所属技能域、权限级别、调用限制（比如每分钟最多调多少次）、依赖关系（如果技能B依赖技能A）、版本号。

对于权限，我的做法是把所有技能分成三类：

有一点务必记住：凡是会对外部系统产生副作用的操作，都往高了定权限。Agent跑偏不可怕，可怕的是Agent跑偏之后还自动执行了删除操作。我在设计时会在注册表里维护一个黑名单，某些命令词和敏感操作直接禁止注册为技能，连调用的机会都不给。

3. 实操过程与核心环节实现

3.1 从零到一搭建简易技能库

这一节我把一个最小可用的agent-skills实现完整走一遍。考虑到不同项目背景的读者，我用最简洁的结构来说明，不依赖任何重型框架，纯Python就能跑。

首先是技能类定义：

class Skill: def __init__(self, name, description, parameters, func, permission="L0"): self.name = name self.description = description self.parameters = parameters # JSON Schema dict self.func = func self.permission = permission self.version = "1.0.0" def execute(self, **kwargs): """执行技能，统一异常包装""" try: return self.func(**kwargs) except Exception as e: raise SkillExecutionError(f"技能 {self.name} 执行失败: {str(e)}") from e

然后是技能注册表：

class SkillRegistry: def __init__(self): self.skills = {} self.aliases = {} def register(self, skill, aliases=None): """注册技能，支持别名""" if skill.name in self.skills: raise DuplicateSkillError(f"技能 {skill.name} 已存在") self.skills[skill.name] = skill if aliases: for al in aliases: self.aliases[al] = skill.name def get_skill(self, name): """通过技能名或别名获取技能""" real_name = self.aliases.get(name, name) return self.skills.get(real_name) def list_skills(self): """返回所有技能的名称和描述""" return [{"name": s.name, "description": s.description} for s in self.skills.values()]

注册表设计成单例。整个Agent进程里只有一个注册表，避免多个实例导致技能状态混乱。并发场景下注册表本身就是只读性的，写操作只发生在启动阶段，运行时只做查找，这样就不需要加锁。

再写两个实际技能看看效果。一个查询技能，一个计算技能：

def skill_calc_percentage(part: float, total: float) -> dict: """计算某部分占总体的百分比。""" if total == 0: raise ValueError("total 不能为 0") percentage = round(part / total * 100, 2) return {"part": part, "total": total, "percentage": percentage} def skill_query_stock(instrument_code: str) -> dict: """查询指定代码的实时行情快照。""" # 模拟行情数据接口 data = fake_market_data(instrument_code) return {"code": instrument_code, "price": data["price"], "change_pct": data["change_pct"]}

注册一条技能链路，可以看看是什么效果：

registry = SkillRegistry() registry.register(Skill( name="calc_percentage", description="计算占比百分比，适用于分析各项指标占比。", parameters={ "type": "object", "properties": { "part": {"type": "number", "description": "部分值"}, "total": {"type": "number", "description": "总值，不能为0"} }, "required": ["part", "total"] }, func=skill_calc_percentage )) registry.register(Skill( name="query_stock", description="查询实时行情，适用于用户询问股价、涨跌幅等场景。", parameters={ "type": "object", "properties": { "instrument_code": {"type": "string", "description": "证券代码，如600519"} }, "required": ["instrument_code"] }, func=skill_query_stock ))

这样一套下来，Agent拿到用户的问题后，第一步是用意图识别模块从注册表里筛出候选技能，第二步是把候选技能的描述和参数schema塞给模型，第三步是让模型输出结构化的调用请求，第四步才是真正执行技能。

3.2 意图调度策略：几条路线怎么选

技能库建好了，关键的枢纽是调度策略。目前我在实践中试过三种路线，各有适用场景。

第一种是规则路由。用关键词和正则做粗筛，比如用户输入包含"占比"就优先推"calc_percentage"，包含"股价"就优先推"query_stock"。好处是快、可控、不消耗模型上下文；坏处是泛化能力差，换个说法就不认了。适合技能数量少、用户表达模式固定的内部工具。

第二种是向量检索。把所有技能的描述、参数说明和示例句子embedding到向量库，用户问题时先做语义检索，把最相关的Top-K个技能捞出来再喂给模型。好处是泛化能力强，用户怎么说都能找到对的技能；坏处是要维护向量库，还占用一定的检索耗时。

第三种是纯模型决策。把全部技能描述一次性塞进Prompt，让模型直接选择。好处是最灵活，坏处极其明显：技能一多，上下文窗口根本装不下，且模型容易在相似技能之间纠结。

我现在的做法是混合路线：先用规则和向量检索做粗筛，把技能从几百个压到五六个，再让模型在这几个候选项里精确选择。这个"粗筛+精排"的结构，既保住了泛化能力，又控制了上下文损耗。

我在实际项目中比较过三种方案的参数预算，可以参考：

3.3 参数设计与返回结构：模型的"说明书"

很多人写技能时最容易忽略的就是参数schema。模型能不能正确调用技能，很大程度取决于你给它的"说明书"写得好不好。

参数schema我遵循几条硬性原则。第一，每个参数必须有清晰的中文描述，说清楚取值范围和含义，比如"order_id: 订单号，通常为字母和数字组合的6-20位字符串"。第二，参数名尽量直观，用snake_case命名，不要用缩写。第三，非必填参数一定要标注"可选"，并且写明缺省时的行为。第四，涉及格式化字符串的参数要给示例值，比如"date: 日期，格式YYYY-MM-DD，例如2024-06-01"。

我再强调一遍返回结构的重要性。技能的返回结果不是给用户看的，是给模型看的。模型要根据你的返回结果继续推理，所以返回结果必须是干净、结构化的dict，不要夹杂多余的文字，不要用自然语言描述"成功了，查到了订单信息"，而是直接返回字段和值。

另外，操作成功和失败一定要在返回结构里显式区分。我习惯定义一个统一包装：

{ "success": True, "data": { ... }, "error": None, "took_ms": 233 }

这样模型可以从success字段直接判断是否要继续下一步，而不是靠猜测。

3.4 技能治理进阶：版本管理与灰度发布

技能库上线只是第一步，后续的迭代才是最麻烦的。我之前吃过亏：某个查询技能改了接口返回字段，没有做平滑过渡，结果全量上线当天，Agent在部分场景下拿不到正确的数据。

后来我在技能注册表里加了一个version字段，并且保留历史版本。在Agent调用技能时，可以指定使用哪个版本的技能。如果一个新版本技能上线后观测到异常，可以直接切回旧版本，整个过程可以在运行时动态完成。

灰度发布的做法是：先让新版本技能只对5%的请求生效，观察监控指标有没有异常，确认稳定后再逐步放量。对于没有明显收益的改动，保持旧版不动的收益其实最高。

除了版本，我还会给技能打标签，记录技能最近一次执行成功率、平均耗时、被调用次数。这些元数据后续在做技能下架决策时非常有用。

4. 常见问题与排查技巧实录

4.1 技能被误触发的典型场景和治理思路

最常遇到的问题是模型在用户没有明确要求的情况下，自己决定调用了一个技能。比如用户问"你们公司几点下班"，Agent居然调用了"查询天气"技能。这种误触发产生的原因通常是技能描述写得过于宽泛，和很多通用场景都存在模糊匹配。

我的治理思路是三条。第一，技能描述里必须写清楚"when_to_use"和"when_not_to_use"，把负例写进去，例如"当用户只是询问作息时间时不要调用此技能"。第二，在意图识别模块设置阈值，比如语义相似度低于0.7就不允许进入候选列表。第三，针对高频误触发的技能，可以在调度层增加用户确认环节。

另外，我强烈建议给技能设置调用频率上限。比如某个技能每分钟最多被调用5次，超过就返回"暂时不可用"，并给模型一个提示让它换思路。我见过Agent在一个任务里反复调用同一个失败技能导致死循环的。频率限制能直接阻断这种恶性循环。

4.2 上下文窗口被技能描述挤爆

技能数量一旦多了，把所有技能描述塞进Prompt里必然会挤占正常的对话空间。我遇到过一个极端案例：上线了一个包含50个技能的辅助Agent，每次请求光技能描述就占了4000多个token，用户问题还没来得及聊几句就截断了。

应对方案就是我前面提到的"粗筛+精排"。粗筛阶段不依赖模型，用规则加向量把候选技能控制在5个以内，后面只把这5个的技能描述和当前对话相关上下文一起喂给模型。

另外还有一个很实用的小技巧：在粗筛阶段，不只看用户当前一句话，还结合对话历史里的最近几轮意图，综合判断候选技能。因为用户经常在连续对话中修正自己的需求，只凭最后一句容易理解错。

4.3 技能执行失败之后，Agent的表现像个无头苍蝇

技能执行失败分两种：一种是参数校验没过，另一种是内部服务异常。第一种通常是模型传参的问题，第二种是外部依赖的问题。但无论哪一种，Agent的反应往往都是灾难：它可能反复重试，或者编造一个假结果。

我在这块加了两个兜底机制。第一个是失败分类：如果是参数错误，就把错误信息整理成"缺少参数x，请补齐后重试"这样的结构化反馈重新发给模型，引导它修正参数。如果是服务异常，就直接告诉模型"该技能暂时不可用，请更换思路"，不要让它反复重试。

第二个是重试退避策略。同一技能在同一个任务里最多调用3次，超过次数直接锁定，防止死循环。外部服务瞬时故障时，等待一小段时间之后再重试，效果远比连续快调要好。

4.4 技能库的可观测性：上线之后你得看得见

最后强烈建议给技能调用链路加上日志和监控。我每次上完新技能，都会把以下指标记录下来：技能名、传入参数摘要、返回状态、耗时、错误信息、使用的模型、对话ID。

有了这些数据之后，可以做很多事。比如定期统计每个技能的被调用次数，如果某个技能连续两周没人用，就标记为"低活跃技能"，考虑优化描述或者下架。再比如按耗时排序找出慢技能，优先做性能优化。

还有一个我常用但容易被忽略的做法：定期把真实用户对话和技能调用序列拉出来，人工抽样检查那些"技能调用成功但用户不满意"的案例。这种案例往往暴露的是技能拆解粒度不对，或者是多个技能之间衔接的逻辑有问题。这类问题靠日志分析根本发现不了，只能靠用户视角的回溯。

5. 实操心得与经验补充

我最后再分享几个从实际项目里沉淀下来的小经验。

第一个是关于"技能文档"的，也就是注册表里的描述。很多人以为描述越短越好，其实不对。描述分成两段：一段给模型看，说明技能的能力边界；一段给人看，说明技能的维护人、变更记录、依赖关系。模型读前一段，人看后一段。我现在每新建一个技能，都会强制要求填写完整的人读文档，这样新同事接手时不至于一头雾水。

第二个是关于"技能优先完成简单任务"的。刚做技能库时，我总想设计一个全能技能，一个函数包打天下。后来发现全能的另一面是难优化。一个技能做得太宽，参数数量超过七八个，模型就很容易传错参数，出错率急剧上升。所以我的建议是：宁可拆出多个小技能，也不要硬凑一个大技能。每个技能的参数少于5个，执行路径单一，这样模型的选择成功率会高很多。

第三个经验是关于线下仿真环境的。给Agent接入真实系统之前，先在本地搭一个全mock数据的环境，把线上系统的接口全部模拟一遍。技能在这个仿真环境里跑通了，再放上真实系统。很多团队跳过仿真直接上真实环境，结果技能调试时的故障全部打到真实业务上，影响难以估量。仿真环境的成本很低，但价值极高。

第四个我想说的是"技能库的灵魂是调用策略"。同样一套技能，调度策略设计得合理与否，直接影响Agent的智能化程度。不要把技能调用做成"收到问题就选一个技能"，而要学会把大问题拆成多个小步骤、按顺序调用多个技能。这个能力，体现在调度逻辑里。我第一次做拆解式调用时，用了最简单的方式：让模型先输出一个"计划"，列出接下来要依次调用的技能列表，再逐项执行。这个简单的改法，直接把任务完成率提升了一个档次。

做了这么多实际项目之后，我的体会是：Agent能力的上限固然由模型决定，但下限绝对是由技能体系的质量决定。一个模型配一套高质量的agent-skills，可以实现非常复杂的真实业务诉求；一个再强的模型配一套乱七八糟的技能，也只能在原地打转。把技能库设计好、调度策略打磨好、观测体系搭起来，Agent才能真正意义上"动手干活"。我建议你从最小的技能清单开始搭，先跑通一个完整场景，再慢慢扩充，这条路我自己走过，稳。