1. 从“有模型”到“会干活”为什么我重新思考了Agent的技能组织方式大概从去年下半年开始我就不太愿意跟人聊“你接入了几个大模型”这种话题了。原因是模型本身的差距在缩小真正拉开体验差距的恰恰是模型外面那一层——它能不能自己查数据、调接口、操作软件、按规范产出结果。简单说一个Agent光会聊天没有意义它得“会干活”而“会干活”靠的就是一套扎实的技能体系。我接触过的很多项目早期都喜欢把工具函数一股脑塞进system prompt里甚至把几个外部API的调用逻辑直接写死在业务流程中。项目Demo阶段这么搞没毛病但一旦进入真实业务问题就会成串地冒出来技能复用性差、权限边界模糊、错误处理混乱、每次版本迭代都要全局回归。我确实是在被这些问题反复“教育”之后才开始认真研究agent-skills这种思路——它本质上是在回答一个问题如何让Agent的能力沉淀成可管理、可复用、可审计的标准化单元。这篇文章就围绕agent-skills这个话题展开。我会从设计思路、接口规范、实际搭建过程、常见坑点四个维度把这段时间落地的经验整理成一套可参考的做法。文章偏实践适合正在做智能体应用、机器人流程自动化、或者任何需要把大模型能力接到实际业务里的开发者和技术负责人。2. agent-skills的核心思路把“能力”当作一等公民来设计2.1 为什么需要把技能独立出来以前我写过一套客服问答机器人逻辑很简单用户问问题机器人检索知识库然后调用大模型生成回答。当时所有动作都写在一个Python服务里工具函数大概二十多个用一堆if-else判断意图然后路由到对应函数。跑起来没问题但改起来非常痛苦。产品经理说“加一个查订单功能”我得在路由层加判断、在函数层写新逻辑、在prompt层补说明测试一次至少半小时。后来我意识到问题的关键在于我把技能查订单、退换货、物流查询和业务流程搅在了一起。技能本身应该是独立、可插拔、可被Agent按需调用的能力单元。就像工具箱里的螺丝刀它不该跟某张特定的工作台绑在一起。agent-skills的思路就是把每个能力封装成一个相对独立的、有明确输入输出契约的“技能包”由Agent的大脑也就是LLM的规划能力来动态选择和编排。2.2 技能库的分层逻辑与整体架构在实际落地时我把整个系统分成三层技能层、调度层、执行层。技能层是基础负责定义“有什么能力”。每个技能包含名称、描述、参数Schema、执行函数或外部API端点、权限标注等元数据。调度层相当于Agent的“编译器”它读取当前对话上下文结合用户意图和技能层的描述信息决策调用哪个技能以及传入什么参数。执行层是最底层真正去操作数据库、调用HTTP接口、读写文件、执行Shell命令等。这个分层给了我很高的灵活性。比如我想给Agent增加“导出Excel报表”的能力我只需要在技能层新增一个技能包然后在调度层的技能列表里注册一下即可业务代码完全不用动。更关键的是安全和审计也更好做了——我可以在执行层统一做权限校验、操作日志记录而不是分散在每个业务函数里。Agent的操作轨迹也变成了“调用了技能A → 传入参数X → 返回结果Y”这种可追溯的结构化记录这对于TOC产品来说尤其重要。2.3 从单体函数到开放技能生态的演进路径很多团队不是不想做技能化改造而是不知道第一步怎么迈。我个人建议用渐进式演进的方式不推荐一次性重构。第一步把现有的工具函数按照“动词宾语”的命名方式梳理出来比如query_order、cancel_refund、send_email这种。第二步给每个函数写一份标准的描述文档说清楚它是干嘛的、什么时候用、参数是什么。第三步把这些信息整理进一个JSON或YAML文件里作为Agent可读取的技能列表。最后再逐步把函数体迁移到独立模块中规范好异常处理和权限控制。这个过程中不需要一开始就上复杂的技能编排框架先把“技能清单化”这件事做好收益就已经很明显了。我在做客服机器人的第二阶段就是这么干的——没有引入任何重型框架只是把技能清单整理成了结构化文件接入了LLM的function calling机制整体效果直接上了一个档次模型不再乱答而是学会了“没把握就调技能”。3. 技能包的规范化设计接口、元数据与描述策略3.1 设计一份可被LLM稳定理解的技能描述在agent-skills的体系里最容易被忽视但又最影响效果的就是描述怎么写。很多人以为反正大模型能力强你写个大概它就能懂。实际上LLM做工具调用时非常依赖描述文本的质量描述模糊或信息不全轻则参数传错重则干脆调错技能。我总结了一套相对稳定的描述模板{ name: query_order, description: 根据订单ID或手机号查询用户订单状态。当用户询问订单进度、物流信息时使用。只有在用户提供订单号或注册手机号后才能执行。返回结果包含订单状态、商品列表、预计送达时间。, parameters: { type: object, properties: { order_id: { type: string, description: 用户的订单编号格式为10位数字例如2025001234 }, phone: { type: string, description: 用户注册时使用的手机号用于无订单号场景的查询 } }, required: [order_id] }, auth: { required: true, scopes: [order:query] } }模板里有几个关键点值得展开。名称必须是动词名词结构且保持全局唯一避免同义技能过多时模型做选择困难。描述部分我要求自己写清楚三件事技能是干什么的、什么时候用触发条件、什么时候不能用限制条件。参数部分的每个字段也要有清晰的说明包括类型、格式、是否必填以及一个具体示例。最重要的一点是参数的描述直接影响LLM的参数提取准确率。我实测过如果我不写格式说明模型会把“2025年第00123号订单”这种带中文的数字串直接传给order_id字段导致后端报错写了格式说明之后模型会主动提取纯数字部分准确率提升非常明显。3.2 注册、更新与版本管理的工程实践技能多了之后如果没有一套管理机制库就变成了“垃圾场”。我在agent-skills体系里引入了三个简单但有效的工程实践。技能注册采用配置即代码的方式所有技能定义存放在一个独立的git仓库里由开发者提MR进行增删改CI里跑一遍Schema校验和描述质量检查比如描述长度低于50字符就告警通过后自动同步到线上配置中心。这样技能库的变更就全程可追溯、可回滚。技能版本管理上我用语义化版本号标记每个技能包Agent在调用时记录版本号这样线上出现问题后我可以快速定位是某个技能的新版本引入的问题还是模型调度的问题。为了稳定性我通常会保留最近两个版本的技能实现一旦发现异常可以秒级回退。技能下线的节奏也需要注意。跟API治理的原则一样不能直接删要先标记为deprecated状态在描述中提示模型“此技能即将下线请使用xx技能替代”观察一段时间无调用后再正式移除。有一次我直接下线了一个技能第二天就有用户反馈机器人答不了物流问题因为相替代的技能描述不够具体模型压根没学明白该什么时候用它。3.3 面向Agent的权限与审计设计Agent能调用的技能越多风险面就越大。这个“风险”不光是安全问题也有业务正确性的问题——一个技能被误调用可能给用户发错短信、开错工单、甚至执行了不可逆的操作。所以在技能层我做了一层轻量级的权限标注在技能注册时就必须声明该技能的权限范围scope。比如query_order需要order:query权限cancel_refund需要order:write权限send_email需要message:send权限。调度层在装配技能清单时会根据当前会话的授权情况过滤掉无权调用的技能这样有两个好处一是LLM不会尝试调用未被授权的技能减少幻觉犯错的可能性二是即使提示词注入或意图被恶意构造底层不会有未被授权的能力可以被利用。审计方面我实现了一个简单的调用链日志每次技能调用都会记录用户ID、会话ID、技能名称、版本号、调用时间、输入参数对敏感信息做脱敏、执行结果状态码、耗时。这套数据在排查“为什么Agent给出了这个回答”的时候极其有价值。我很多次发现问题都是靠日志回放定位的——用户说“帮我改收货地址”日志显示模型实际调用的是create_return_order显然它的意图理解出了偏差这种问题不看调用链根本无从查起。4. 手把手实测从零搭建一个可运行的技能化Agent4.1 环境与基础框架选型开始动手之前先快速过一下环境需求。语言方面我用Python 3.11框架选了比较成熟的LangChain作为Agent编排基础LLM这块我建议先用一个支持function calling的模型国内可选的如通义千问的qwen-plus或智谱的glm-4-flash接口上都有工具调用兼容模式实测效果足够稳。项目结构我建议这样组织agent_skills_demo/ ├── agent.py # 主入口初始化Agent与调度逻辑 ├── skills/ │ ├── __init__.py │ ├── registry.py # 技能注册与发现逻辑 │ └── builtin/ │ ├── query_order.py │ ├── cancel_refund.py │ └── send_message.py ├── config/ │ └── skills.yaml # 技能的静态配置信息 ├── logs/ # 调用日志存储 └── requirements.txt这种结构跟普通单体应用最大的区别在于skills目录的独立性——每个技能模块只对外暴露一个标准化的函数入口模块内部怎么实现都行甚至可以各自维护独立的依赖。这给团队并行开发提供了很大便利。4.2 一步步编写技能注册与执行脚本下面我带你来走一遍核心代码。先定义技能的基类接口确保所有技能都遵循统一规范# skills/base.py from abc import ABC, abstractmethod from typing import Any, Dict class BaseSkill(ABC): 技能基类所有技能必须实现name、description、execute三个核心成员 property abstractmethod def name(self) - str: 技能唯一名称 pass property abstractmethod def description(self) - str: 技能描述用于LLM做意图匹配 pass abstractmethod def execute(self, params: Dict[str, Any]) - Dict[str, Any]: 执行技能并返回结构化结果 pass接着写一个技能注册器用来管理所有可用的技能实例并生成LLM友好的工具描述列表# skills/registry.py from typing import Dict, List, Type from .base import BaseSkill class SkillRegistry: def __init__(self): self._skills: Dict[str, BaseSkill] {} def register(self, skill: BaseSkill): 注册技能同名覆盖并给出警告 if skill.name in self._skills: print(f[WARN] skill {skill.name} already registered, will be replaced) self._skills[skill.name] skill def get(self, name: str) - BaseSkill: return self._skills.get(name) def list_tools(self) - List[dict]: 生成OpenAI function calling格式的工具列表 tools [] for skill in self._skills.values(): tools.append({ type: function, function: { name: skill.name, description: skill.description, parameters: skill.parameters, # 每个技能需额外提供parameters属性 } }) return tools这个registry是调度层和技能层之间的桥梁。实际运行中Agent拿到用户问题后会把list_tools()的返回结果整体传给LLMLLM根据对话上下文决定调哪个函数、传什么参数。为了演示我写一个最简单的订单查询技能# skills/builtin/query_order.py from typing import Any, Dict from ..base import BaseSkill class QueryOrderSkill(BaseSkill): property def name(self) - str: return query_order property def description(self) - str: return (查询用户订单状态适用于用户询问订单进度、物流状态、发货情况。 需要用户提供订单号或注册手机号。) property def parameters(self) - dict: return { type: object, properties: { order_id: { type: string, description: 10位纯数字订单编号 } }, required: [order_id] } def execute(self, params: Dict[str, Any]) - Dict[str, Any]: # 实际场景这里会查数据库或调用订单中心API order_id params[order_id] # 模拟返回 return { order_id: order_id, status: shipped, estimated_delivery: 2025-06-20 }最后在主程序里把所有技能实例化并注册然后接入LLM# agent.py import json from agency_swarm import Agent # 也可以用LangChain的create_agent from skills.builtin.query_order import QueryOrderSkill from skills.registry import SkillRegistry registry SkillRegistry() registry.register(QueryOrderSkill()) # 在LLM请求参数中注入工具列表 def run_agent(user_input: str): tools registry.list_tools() # 此处省略具体的LLM调用代码关键在于messages中追加tool结果 # 1. 将user_input和tools一起发给LLM # 2. LLM返回tool_calls # 3. 根据tool_calls执行对应skill.execute() # 4. 把执行结果作为tool消息回传给LLM # 5. LLM生成最终回答 pass if __name__ __main__: while True: user_text input(用户: ) if user_text in (exit, quit): break print(Agent:, run_agent(user_text))上面第4部的衔接是整条链路的核心也就是常说的“function calling循环”LLM决定调用工具 → 代码执行工具 → 把结果返回给LLM → LLM继续决策。很多第一次做的朋友在这个循环上翻车最常见的问题就是忘了把工具执行结果传回去导致LLM只能“含含糊糊”地编一个答案。4.3 一次完整的调用演练与结果解读假设用户问“你好我的订单2025008888现在到哪了”这时候LLM会输出一个结构化的工具调用请求大概是这样的[{ tool_calls: [{ id: call_abc123, type: function, function: { name: query_order, arguments: {\order_id\: \2025008888\} } }] }]我在代码里拿着function.name去registry里get到对应的技能实例用json.loads(arguments)解析参数再调用execute()。在上面的模拟实现里返回的是{order_id: 2025008888, status: shipped, ...}。接下来把这个结果作为工具消息拼接到对话上下文里再让LLM生成面向用户的自然语言回答最终的输出可能是这样的“您的订单2025008888已发货预计6月20日送达。请您保持电话畅通快递员派送前会与您联系。”到这里你就完整跑通了一次“用户提问 → LLM规划 → 技能执行 → 结果反馈 → 自然语言回复”的闭环。这是一个极简但五脏俱全的agent-skills雏形。在这个基础上加技能无非就是新增一个继承BaseSkill的类然后把实例注册进registry不需要改任何Agent层的逻辑——这跟我之前说的“技能可插拔”完全是同一个道理。5. 真实场景迭代中的坑点与排查经验5.1 描述不清导致的调用混乱这个坑我踩得最深。最初写技能描述时只写了“查询订单状态”结果模型经常把用户对物流投诉的意图也路由到这个技能上。后来把描述改成“查询订单状态适用于订单正常流转状态查询如果用户抱怨物流慢或丢件请使用after_sales_feedback技能”效果立竿见影。经验是描述里一定要写清“边界”明确哪些情况“不用这个技能”。相当于给LLM划定了一个决策围栏减少意图模糊地带。5.2 参数校验缺失造成下游连锁故障有一段时间我们的Agent在调用“取消订单”技能时频繁报错排查看日志发现模型传了一个已经取消过的订单号进来。底层的取消接口幂等性没做好直接抛异常Agent回答“系统繁忙请稍后重试”用户体验很差。后来我做了两处调整。第一是技能内部增加参数预校验发现订单状态不是待发货就直接返回业务错误码而不是让底层接口兜底第二是给技能执行包了一层统一的异常捕获任何异常都转为结构化的错误结果并附上一段面向用户的可理解文本。这样Agent拿到错误结果后会主动解析并向用户解释“这笔订单已取消无需重复操作”。问题的关键不是让Agent不犯错而是给它一套能优雅处理错误的机制。5.3 性能与并发控制技能调用的限流与降级上线一段时间后我又遇到了一个问题技能化改造太顺滑业务方疯狂往技能库里堆技能有些技能背后依赖的外部接口QPS限制很低一旦Agent进入连续调度模式就会瞬间打爆下游服务。这事的解法不复杂我给技能层加了一个简单的限流装饰器支持按技能维度配置每秒最大调用次数超出后直接返回“服务繁忙”提示。同时针对一些非核心操作比如发送营销短信在技能描述里额外标注“此为低优先级操作如果长时间未响应可向下游询问替代方案”让模型在调度策略上也留有余地。整体的效果是即便大促期间流量翻倍下游服务也没有再出现过雪崩。5.4 一个值得保留的习惯定期做技能调用复盘最后分享一个我坚持了大半年的习惯。每周我会拉取一次技能调用日志按“调用次数、成功率、平均延迟、失败原因Top5”这几个维度做复盘。这个动作的收益是慢慢显现的——有一次复盘时发现某个技能描述命中率不足60%细查之后才明白是这个技能的名称太宽泛了跟另一个技能描述有重叠模型经常混淆。我花了一下午把这两个技能的边界重新梳理了一遍第二天调用准确率直接提升了近二十个百分点。如果你也在做agent-sills相关的工作我特别建议把“复盘”当作正式流程的一部分而不是可有可无的工作。在技能数量的上升期定期复盘能防止你的技能库在不知不觉中变成一个新的“垃圾堆”——Agent的能力边界会因为技能混乱而显著缩水这种问题比模型能力本身的限制更隐蔽也更值得认真对待。 Agent技能化改造：从杂乱工具到可复用技能库的工程实践
1. 从“有模型”到“会干活”为什么我重新思考了Agent的技能组织方式大概从去年下半年开始我就不太愿意跟人聊“你接入了几个大模型”这种话题了。原因是模型本身的差距在缩小真正拉开体验差距的恰恰是模型外面那一层——它能不能自己查数据、调接口、操作软件、按规范产出结果。简单说一个Agent光会聊天没有意义它得“会干活”而“会干活”靠的就是一套扎实的技能体系。我接触过的很多项目早期都喜欢把工具函数一股脑塞进system prompt里甚至把几个外部API的调用逻辑直接写死在业务流程中。项目Demo阶段这么搞没毛病但一旦进入真实业务问题就会成串地冒出来技能复用性差、权限边界模糊、错误处理混乱、每次版本迭代都要全局回归。我确实是在被这些问题反复“教育”之后才开始认真研究agent-skills这种思路——它本质上是在回答一个问题如何让Agent的能力沉淀成可管理、可复用、可审计的标准化单元。这篇文章就围绕agent-skills这个话题展开。我会从设计思路、接口规范、实际搭建过程、常见坑点四个维度把这段时间落地的经验整理成一套可参考的做法。文章偏实践适合正在做智能体应用、机器人流程自动化、或者任何需要把大模型能力接到实际业务里的开发者和技术负责人。2. agent-skills的核心思路把“能力”当作一等公民来设计2.1 为什么需要把技能独立出来以前我写过一套客服问答机器人逻辑很简单用户问问题机器人检索知识库然后调用大模型生成回答。当时所有动作都写在一个Python服务里工具函数大概二十多个用一堆if-else判断意图然后路由到对应函数。跑起来没问题但改起来非常痛苦。产品经理说“加一个查订单功能”我得在路由层加判断、在函数层写新逻辑、在prompt层补说明测试一次至少半小时。后来我意识到问题的关键在于我把技能查订单、退换货、物流查询和业务流程搅在了一起。技能本身应该是独立、可插拔、可被Agent按需调用的能力单元。就像工具箱里的螺丝刀它不该跟某张特定的工作台绑在一起。agent-skills的思路就是把每个能力封装成一个相对独立的、有明确输入输出契约的“技能包”由Agent的大脑也就是LLM的规划能力来动态选择和编排。2.2 技能库的分层逻辑与整体架构在实际落地时我把整个系统分成三层技能层、调度层、执行层。技能层是基础负责定义“有什么能力”。每个技能包含名称、描述、参数Schema、执行函数或外部API端点、权限标注等元数据。调度层相当于Agent的“编译器”它读取当前对话上下文结合用户意图和技能层的描述信息决策调用哪个技能以及传入什么参数。执行层是最底层真正去操作数据库、调用HTTP接口、读写文件、执行Shell命令等。这个分层给了我很高的灵活性。比如我想给Agent增加“导出Excel报表”的能力我只需要在技能层新增一个技能包然后在调度层的技能列表里注册一下即可业务代码完全不用动。更关键的是安全和审计也更好做了——我可以在执行层统一做权限校验、操作日志记录而不是分散在每个业务函数里。Agent的操作轨迹也变成了“调用了技能A → 传入参数X → 返回结果Y”这种可追溯的结构化记录这对于TOC产品来说尤其重要。2.3 从单体函数到开放技能生态的演进路径很多团队不是不想做技能化改造而是不知道第一步怎么迈。我个人建议用渐进式演进的方式不推荐一次性重构。第一步把现有的工具函数按照“动词宾语”的命名方式梳理出来比如query_order、cancel_refund、send_email这种。第二步给每个函数写一份标准的描述文档说清楚它是干嘛的、什么时候用、参数是什么。第三步把这些信息整理进一个JSON或YAML文件里作为Agent可读取的技能列表。最后再逐步把函数体迁移到独立模块中规范好异常处理和权限控制。这个过程中不需要一开始就上复杂的技能编排框架先把“技能清单化”这件事做好收益就已经很明显了。我在做客服机器人的第二阶段就是这么干的——没有引入任何重型框架只是把技能清单整理成了结构化文件接入了LLM的function calling机制整体效果直接上了一个档次模型不再乱答而是学会了“没把握就调技能”。3. 技能包的规范化设计接口、元数据与描述策略3.1 设计一份可被LLM稳定理解的技能描述在agent-skills的体系里最容易被忽视但又最影响效果的就是描述怎么写。很多人以为反正大模型能力强你写个大概它就能懂。实际上LLM做工具调用时非常依赖描述文本的质量描述模糊或信息不全轻则参数传错重则干脆调错技能。我总结了一套相对稳定的描述模板{ name: query_order, description: 根据订单ID或手机号查询用户订单状态。当用户询问订单进度、物流信息时使用。只有在用户提供订单号或注册手机号后才能执行。返回结果包含订单状态、商品列表、预计送达时间。, parameters: { type: object, properties: { order_id: { type: string, description: 用户的订单编号格式为10位数字例如2025001234 }, phone: { type: string, description: 用户注册时使用的手机号用于无订单号场景的查询 } }, required: [order_id] }, auth: { required: true, scopes: [order:query] } }模板里有几个关键点值得展开。名称必须是动词名词结构且保持全局唯一避免同义技能过多时模型做选择困难。描述部分我要求自己写清楚三件事技能是干什么的、什么时候用触发条件、什么时候不能用限制条件。参数部分的每个字段也要有清晰的说明包括类型、格式、是否必填以及一个具体示例。最重要的一点是参数的描述直接影响LLM的参数提取准确率。我实测过如果我不写格式说明模型会把“2025年第00123号订单”这种带中文的数字串直接传给order_id字段导致后端报错写了格式说明之后模型会主动提取纯数字部分准确率提升非常明显。3.2 注册、更新与版本管理的工程实践技能多了之后如果没有一套管理机制库就变成了“垃圾场”。我在agent-skills体系里引入了三个简单但有效的工程实践。技能注册采用配置即代码的方式所有技能定义存放在一个独立的git仓库里由开发者提MR进行增删改CI里跑一遍Schema校验和描述质量检查比如描述长度低于50字符就告警通过后自动同步到线上配置中心。这样技能库的变更就全程可追溯、可回滚。技能版本管理上我用语义化版本号标记每个技能包Agent在调用时记录版本号这样线上出现问题后我可以快速定位是某个技能的新版本引入的问题还是模型调度的问题。为了稳定性我通常会保留最近两个版本的技能实现一旦发现异常可以秒级回退。技能下线的节奏也需要注意。跟API治理的原则一样不能直接删要先标记为deprecated状态在描述中提示模型“此技能即将下线请使用xx技能替代”观察一段时间无调用后再正式移除。有一次我直接下线了一个技能第二天就有用户反馈机器人答不了物流问题因为相替代的技能描述不够具体模型压根没学明白该什么时候用它。3.3 面向Agent的权限与审计设计Agent能调用的技能越多风险面就越大。这个“风险”不光是安全问题也有业务正确性的问题——一个技能被误调用可能给用户发错短信、开错工单、甚至执行了不可逆的操作。所以在技能层我做了一层轻量级的权限标注在技能注册时就必须声明该技能的权限范围scope。比如query_order需要order:query权限cancel_refund需要order:write权限send_email需要message:send权限。调度层在装配技能清单时会根据当前会话的授权情况过滤掉无权调用的技能这样有两个好处一是LLM不会尝试调用未被授权的技能减少幻觉犯错的可能性二是即使提示词注入或意图被恶意构造底层不会有未被授权的能力可以被利用。审计方面我实现了一个简单的调用链日志每次技能调用都会记录用户ID、会话ID、技能名称、版本号、调用时间、输入参数对敏感信息做脱敏、执行结果状态码、耗时。这套数据在排查“为什么Agent给出了这个回答”的时候极其有价值。我很多次发现问题都是靠日志回放定位的——用户说“帮我改收货地址”日志显示模型实际调用的是create_return_order显然它的意图理解出了偏差这种问题不看调用链根本无从查起。4. 手把手实测从零搭建一个可运行的技能化Agent4.1 环境与基础框架选型开始动手之前先快速过一下环境需求。语言方面我用Python 3.11框架选了比较成熟的LangChain作为Agent编排基础LLM这块我建议先用一个支持function calling的模型国内可选的如通义千问的qwen-plus或智谱的glm-4-flash接口上都有工具调用兼容模式实测效果足够稳。项目结构我建议这样组织agent_skills_demo/ ├── agent.py # 主入口初始化Agent与调度逻辑 ├── skills/ │ ├── __init__.py │ ├── registry.py # 技能注册与发现逻辑 │ └── builtin/ │ ├── query_order.py │ ├── cancel_refund.py │ └── send_message.py ├── config/ │ └── skills.yaml # 技能的静态配置信息 ├── logs/ # 调用日志存储 └── requirements.txt这种结构跟普通单体应用最大的区别在于skills目录的独立性——每个技能模块只对外暴露一个标准化的函数入口模块内部怎么实现都行甚至可以各自维护独立的依赖。这给团队并行开发提供了很大便利。4.2 一步步编写技能注册与执行脚本下面我带你来走一遍核心代码。先定义技能的基类接口确保所有技能都遵循统一规范# skills/base.py from abc import ABC, abstractmethod from typing import Any, Dict class BaseSkill(ABC): 技能基类所有技能必须实现name、description、execute三个核心成员 property abstractmethod def name(self) - str: 技能唯一名称 pass property abstractmethod def description(self) - str: 技能描述用于LLM做意图匹配 pass abstractmethod def execute(self, params: Dict[str, Any]) - Dict[str, Any]: 执行技能并返回结构化结果 pass接着写一个技能注册器用来管理所有可用的技能实例并生成LLM友好的工具描述列表# skills/registry.py from typing import Dict, List, Type from .base import BaseSkill class SkillRegistry: def __init__(self): self._skills: Dict[str, BaseSkill] {} def register(self, skill: BaseSkill): 注册技能同名覆盖并给出警告 if skill.name in self._skills: print(f[WARN] skill {skill.name} already registered, will be replaced) self._skills[skill.name] skill def get(self, name: str) - BaseSkill: return self._skills.get(name) def list_tools(self) - List[dict]: 生成OpenAI function calling格式的工具列表 tools [] for skill in self._skills.values(): tools.append({ type: function, function: { name: skill.name, description: skill.description, parameters: skill.parameters, # 每个技能需额外提供parameters属性 } }) return tools这个registry是调度层和技能层之间的桥梁。实际运行中Agent拿到用户问题后会把list_tools()的返回结果整体传给LLMLLM根据对话上下文决定调哪个函数、传什么参数。为了演示我写一个最简单的订单查询技能# skills/builtin/query_order.py from typing import Any, Dict from ..base import BaseSkill class QueryOrderSkill(BaseSkill): property def name(self) - str: return query_order property def description(self) - str: return (查询用户订单状态适用于用户询问订单进度、物流状态、发货情况。 需要用户提供订单号或注册手机号。) property def parameters(self) - dict: return { type: object, properties: { order_id: { type: string, description: 10位纯数字订单编号 } }, required: [order_id] } def execute(self, params: Dict[str, Any]) - Dict[str, Any]: # 实际场景这里会查数据库或调用订单中心API order_id params[order_id] # 模拟返回 return { order_id: order_id, status: shipped, estimated_delivery: 2025-06-20 }最后在主程序里把所有技能实例化并注册然后接入LLM# agent.py import json from agency_swarm import Agent # 也可以用LangChain的create_agent from skills.builtin.query_order import QueryOrderSkill from skills.registry import SkillRegistry registry SkillRegistry() registry.register(QueryOrderSkill()) # 在LLM请求参数中注入工具列表 def run_agent(user_input: str): tools registry.list_tools() # 此处省略具体的LLM调用代码关键在于messages中追加tool结果 # 1. 将user_input和tools一起发给LLM # 2. LLM返回tool_calls # 3. 根据tool_calls执行对应skill.execute() # 4. 把执行结果作为tool消息回传给LLM # 5. LLM生成最终回答 pass if __name__ __main__: while True: user_text input(用户: ) if user_text in (exit, quit): break print(Agent:, run_agent(user_text))上面第4部的衔接是整条链路的核心也就是常说的“function calling循环”LLM决定调用工具 → 代码执行工具 → 把结果返回给LLM → LLM继续决策。很多第一次做的朋友在这个循环上翻车最常见的问题就是忘了把工具执行结果传回去导致LLM只能“含含糊糊”地编一个答案。4.3 一次完整的调用演练与结果解读假设用户问“你好我的订单2025008888现在到哪了”这时候LLM会输出一个结构化的工具调用请求大概是这样的[{ tool_calls: [{ id: call_abc123, type: function, function: { name: query_order, arguments: {\order_id\: \2025008888\} } }] }]我在代码里拿着function.name去registry里get到对应的技能实例用json.loads(arguments)解析参数再调用execute()。在上面的模拟实现里返回的是{order_id: 2025008888, status: shipped, ...}。接下来把这个结果作为工具消息拼接到对话上下文里再让LLM生成面向用户的自然语言回答最终的输出可能是这样的“您的订单2025008888已发货预计6月20日送达。请您保持电话畅通快递员派送前会与您联系。”到这里你就完整跑通了一次“用户提问 → LLM规划 → 技能执行 → 结果反馈 → 自然语言回复”的闭环。这是一个极简但五脏俱全的agent-skills雏形。在这个基础上加技能无非就是新增一个继承BaseSkill的类然后把实例注册进registry不需要改任何Agent层的逻辑——这跟我之前说的“技能可插拔”完全是同一个道理。5. 真实场景迭代中的坑点与排查经验5.1 描述不清导致的调用混乱这个坑我踩得最深。最初写技能描述时只写了“查询订单状态”结果模型经常把用户对物流投诉的意图也路由到这个技能上。后来把描述改成“查询订单状态适用于订单正常流转状态查询如果用户抱怨物流慢或丢件请使用after_sales_feedback技能”效果立竿见影。经验是描述里一定要写清“边界”明确哪些情况“不用这个技能”。相当于给LLM划定了一个决策围栏减少意图模糊地带。5.2 参数校验缺失造成下游连锁故障有一段时间我们的Agent在调用“取消订单”技能时频繁报错排查看日志发现模型传了一个已经取消过的订单号进来。底层的取消接口幂等性没做好直接抛异常Agent回答“系统繁忙请稍后重试”用户体验很差。后来我做了两处调整。第一是技能内部增加参数预校验发现订单状态不是待发货就直接返回业务错误码而不是让底层接口兜底第二是给技能执行包了一层统一的异常捕获任何异常都转为结构化的错误结果并附上一段面向用户的可理解文本。这样Agent拿到错误结果后会主动解析并向用户解释“这笔订单已取消无需重复操作”。问题的关键不是让Agent不犯错而是给它一套能优雅处理错误的机制。5.3 性能与并发控制技能调用的限流与降级上线一段时间后我又遇到了一个问题技能化改造太顺滑业务方疯狂往技能库里堆技能有些技能背后依赖的外部接口QPS限制很低一旦Agent进入连续调度模式就会瞬间打爆下游服务。这事的解法不复杂我给技能层加了一个简单的限流装饰器支持按技能维度配置每秒最大调用次数超出后直接返回“服务繁忙”提示。同时针对一些非核心操作比如发送营销短信在技能描述里额外标注“此为低优先级操作如果长时间未响应可向下游询问替代方案”让模型在调度策略上也留有余地。整体的效果是即便大促期间流量翻倍下游服务也没有再出现过雪崩。5.4 一个值得保留的习惯定期做技能调用复盘最后分享一个我坚持了大半年的习惯。每周我会拉取一次技能调用日志按“调用次数、成功率、平均延迟、失败原因Top5”这几个维度做复盘。这个动作的收益是慢慢显现的——有一次复盘时发现某个技能描述命中率不足60%细查之后才明白是这个技能的名称太宽泛了跟另一个技能描述有重叠模型经常混淆。我花了一下午把这两个技能的边界重新梳理了一遍第二天调用准确率直接提升了近二十个百分点。如果你也在做agent-sills相关的工作我特别建议把“复盘”当作正式流程的一部分而不是可有可无的工作。在技能数量的上升期定期复盘能防止你的技能库在不知不觉中变成一个新的“垃圾堆”——Agent的能力边界会因为技能混乱而显著缩水这种问题比模型能力本身的限制更隐蔽也更值得认真对待。