1. 项目概述为什么我们需要Agent Skill设计模式最近在搞AI Agent开发的朋友估计都听过“Skill”这个词。无论是OpenAI的GPTs还是各种开源的Agent框架都在强调“技能”的构建。但说实话刚开始接触时我也有点懵这不就是一堆函数调用吗干嘛非得叫“Skill”还扯上“设计模式”直到我亲手搭建了几个复杂的业务Agent踩了一堆坑之后才彻底明白。简单来说Agent Skill设计模式解决的是“如何让一个AI智能体像乐高积木一样灵活、可靠、可维护地组合各种能力”的核心问题。想象一下你要造一个万能助理Agent它需要能查天气、订日历、发邮件、分析数据、写报告……如果你把这些功能全都写成一个几千行的“上帝函数”那代码维护起来绝对是灾难。而Skill模式就是把每个独立的能力查天气、发邮件封装成一个独立的、可插拔的“技能模块”。这不仅仅是代码组织问题。一个好的Skill设计直接决定了你的Agent能否快速适应新需求比如突然要加一个“订机票”的技能能否在不同场景下复用同一个“数据查询”技能既用于报告生成也用于实时问答以及能否清晰地管理权限和错误。网上热传的Hermes Agent、Codex Skill其背后的核心思想都离不开一套行之有效的Skill设计模式。今天我就结合自己从零搭建企业级Agent的经验把这套模式的“道”与“术”彻底讲透让你不仅能看懂更能直接用起来。2. 核心设计思想与架构模式解析设计模式不是死板的教条而是一套针对特定问题的、经过验证的最佳实践解决方案。在Agent Skill的语境下我们面对的核心问题是如何在高动态、不确定性的AI交互环境中构建稳定、可扩展的能力单元下面几种模式就是针对这个问题的“答案”。2.1 策略模式动态技能路由与执行的核心这是Skill模式里应用最广泛也最基础的一个。它的核心思想是定义一系列算法技能将每一个算法封装起来并且使它们可以互相替换。为什么是策略模式想象你的Agent接收到用户请求“帮我总结一下上周的销售数据并邮件发给经理。”这个请求至少隐含了两个技能数据查询与总结和发送邮件。如果不用策略模式你的代码里可能会塞满if-elseif “总结销售数据” in user_input: run_sales_summary() elif “发送邮件” in user_input: send_email() ...当技能增加到几十个时这段代码会变得难以维护和扩展。策略模式通过一个统一的接口来解耦。实操中的策略模式实现我们定义一个抽象的Skill基类所有具体技能都继承它。from abc import ABC, abstractmethod from typing import Any, Dict class Skill(ABC): 技能抽象基类 property abstractmethod def name(self) - str: 技能的唯一标识名 pass property abstractmethod def description(self) - str: 技能的描述用于让LLM理解何时调用此技能 pass abstractmethod def execute(self, **kwargs) - Dict[str, Any]: 执行技能的核心方法 pass # 具体技能实现 class WeatherQuerySkill(Skill): property def name(self): return “get_weather” property def description(self): return “查询指定城市的当前天气情况。输入参数city城市名” def execute(self, **kwargs): city kwargs.get(“city”) # 调用真实天气API # ... 业务逻辑 ... return {“status”: “success”, “data”: f”{city}天气晴25度”} class EmailSendSkill(Skill): property def name(self): return “send_email” property def description(self): return “发送电子邮件。输入参数recipient收件人 subject主题 body正文” def execute(self, **kwargs): # 调用邮件发送服务 # ... 业务逻辑 ... return {“status”: “success”, “message”: “邮件已发送”}关键设计考量统一的执行接口execute方法让Agent的核心调度器可以用同一套方式调用任何技能大大简化了调度逻辑。自描述性name和description属性至关重要。在基于LLM的Agent中我们通常会把所有技能的描述拼接成提示词Prompt让LLM自己决定在什么情况下调用哪个技能。这就是所谓的“技能路由”。输入输出标准化execute方法接收字典参数也返回字典结构。这为技能间的数据流转一个技能的输出作为另一个技能的输入奠定了基础。实操心得description的撰写是门艺术。它需要足够清晰让LLM能准确理解技能用途又不能过于冗长以免占用过多Token。我通常会采用“功能输入参数示例”的格式。例如“查询天气。输入city城市名称如‘北京’。输出天气状况和温度。”2.2 工厂模式技能的动态注册与生命周期管理当你的技能越来越多并且可能需要根据配置动态加载例如某些技能只在付费版本中提供时策略模式需要搭配工厂模式来管理技能的创建。工厂模式解决了什么问题它负责封装技能对象的创建过程。Agent的核心引擎不需要关心WeatherQuerySkill是如何被实例化的它只需要向一个“技能工厂”请求“给我一个叫get_weather的技能对象。”一个简单的技能工厂实现class SkillFactory: _registry {} # 技能注册表 classmethod def register(cls, skill_name: str, skill_class): 注册技能类 cls._registry[skill_name] skill_class classmethod def create_skill(cls, skill_name: str) - Skill: 根据技能名创建技能实例 if skill_name not in cls._registry: raise ValueError(f”Skill ‘{skill_name}’ is not registered.”) return cls._registry[skill_name]() classmethod def list_skills(cls) - Dict[str, str]: 列出所有已注册技能的名称和描述用于构建Agent提示词 return {name: cls._registry[name]().description for name in cls._registry} # 技能装饰器用于自动注册 def register_skill(skill_name): def decorator(cls): SkillFactory.register(skill_name, cls) return cls return decorator # 使用装饰器注册技能 register_skill(“get_weather”) class WeatherQuerySkill(Skill): # ... 实现同上 ...这样做的好处解耦Agent核心代码与具体技能实现完全分离。新增一个技能只需要写一个新的Skill类并用装饰器注册核心调度代码一行都不用改。动态配置你可以从配置文件、数据库甚至远程API加载技能列表然后动态注册到工厂中实现技能的“热插拔”。集中管理工厂成为了所有技能的单一访问点便于进行统一的日志、监控、权限校验等横切关注点Aspect的管理。2.3 责任链模式构建复杂的技能工作流用户的一个复杂请求往往需要多个技能协作完成。例如“查一下北京天气如果下雨就提醒我带伞并把提醒加到日历里”。这涉及到天气查询-条件判断-日历创建三个步骤。责任链模式非常适合处理这种管道式或工作流式的技能执行。责任链模式的核心使多个对象技能都有机会处理请求从而避免请求发送者与接收者之间的耦合。将这些对象连成一条链并沿着这条链传递请求直到有一个对象处理它为止。在Agent中我们可以让一个技能执行完毕后主动将结果和上下文传递给下一个合适的技能。工作流引擎的简化实现class WorkflowSkill(Skill): 一个特殊的技能它本身是一个由多个子技能构成的工作流 def __init__(self): self.skill_chain [] # 技能执行链 def add_skill(self, skill: Skill, conditionNone): 向工作流中添加一个技能及其触发条件 self.skill_chain.append({“skill”: skill, “condition”: condition}) def execute(self, context: Dict): 顺序执行工作流中的技能 result context for item in self.skill_chain: skill item[“skill”] condition item[“condition”] # 检查执行条件可以由一个专门的“条件判断技能”或简单lambda实现 if condition and not condition(result): continue # 执行技能并将结果更新到上下文中 skill_result skill.execute(**result) result.update(skill_result) return result # 使用示例构建一个“天气依赖型日程安排”工作流 weather_workflow WorkflowSkill() weather_workflow.add_skill(WeatherQuerySkill(), conditionlambda ctx: “city” in ctx) # 下一个“创建提醒”技能只在天气为雨雪时才执行 def need_reminder(ctx): weather_data ctx.get(“weather_data”, “”) return “雨” in weather_data or “雪” in weather_data weather_workflow.add_skill(CreateReminderSkill(), conditionneed_reminder)模式价值流程可视化工作流Skill本身也是一个Skill可以被Agent平等调度。这使得复杂流程得以模块化。灵活性你可以轻松调整技能链的顺序或基于中间结果动态跳过某些技能。错误隔离可以在工作流中设置错误处理技能专门捕获和处理链中其他技能抛出的异常避免整个Agent崩溃。踩坑记录初期设计工作流时我曾让每个技能都返回一个“下一个要执行的技能名”这导致了复杂的控制流和难以调试的循环。后来改为由一个中央工作流引擎或一个专用的Orchestrator Skill来基于预定义规则或LLM决策驱动流程清晰度和可控性大大提升。2.4 适配器模式与外观模式集成遗留系统与复杂服务在真实企业环境中Agent经常需要与现有的老旧系统如某个古老的CRM接口或复杂的第三方服务如SAP、Salesforce交互。这些系统的接口往往与Agent期望的简洁Skill接口不匹配。这时适配器模式和外观模式就派上用场了。适配器模式将一个类的接口转换成客户期望的另一个接口。比如一个老旧天气服务返回的是XML而你的Skill标准输出是JSON。class LegacyWeatherService: def get_weather_xml(self, city_code: int) - str: # 返回 weathercity101010100/cityinfosunny/info/weather pass class LegacyWeatherAdapter(Skill): def __init__(self): self._legacy_service LegacyWeatherService() property def name(self): return “get_weather_v2” def execute(self, **kwargs): city_name kwargs[“city”] # 1. 将城市名转换为老系统需要的城市代码可能需要查表 city_code self._city_name_to_code(city_name) # 2. 调用老服务 xml_result self._legacy_service.get_weather_xml(city_code) # 3. 将XML解析并转换为标准JSON格式 json_result self._parse_xml_to_json(xml_result) return json_result这个LegacyWeatherAdapter就是一个适配器它“伪装”成一个标准的Skill内部却处理了所有不兼容的细节。外观模式为子系统中的一组接口提供一个一致的简化接口。当需要集成一个极其复杂的系统如整个ERP系统时为其创建一个“门面Skill”。class ERPFacadeSkill(Skill): ERP系统门面技能封装了数十个复杂的底层API调用 property def description(self): return “处理与ERP系统相关的综合请求如查询订单、创建客户、生成报表等。” def execute(self, **kwargs): action kwargs.get(“action”) if action “query_order”: return self._complex_order_query_flow(kwargs) elif action “create_customer”: return self._multi_step_customer_creation(kwargs) # ... 其他动作 ... else: return {“error”: “Unsupported ERP action”} def _complex_order_query_flow(self, params): # 内部可能调用5-6个不同的ERP API处理认证、分页、数据拼接等 pass这个ERPFacadeSkill对Agent核心和其他Skill隐藏了ERP系统的复杂性提供了一个统一、简单的入口。模式选择建议适配器模式主要用于接口转换解决“接口不匹配”问题。当你需要复用一个已经存在但接口不符合要求的类时使用。外观模式主要用于简化接口解决“系统过于复杂”问题。当你需要为一个复杂子系统提供一个更易于使用的入口时使用。在实践中一个外观Skill内部可能会使用多个适配器。3. 从理论到实践构建一个可运营的Agent Skill系统理解了设计模式我们还需要一套工程化的实践让Skill系统真正健壮、可运维。这部分是很多教程里不会细说的“脏活累活”但恰恰决定了项目成败。3.1 Skill的标准化定义与描述规范一个混乱的Skill描述会导致LLM频繁误判。我们必须建立规范。一个完整的Skill描述应包含功能名称简洁动词开头如calculate_quote,fetch_user_profile。自然语言描述用一句话说明技能做什么。关键描述使用场景而非实现。例如“当用户需要将金额从一种货币转换为另一种货币时使用此技能。”输入参数明确每个参数的名称、类型、是否必填、描述和示例。坏例子amount, from_currency, to_currency好例子amount: (float, 必填) 需要转换的金额例如 100.0from_currency: (string, 必填) 原始货币代码ISO 4217例如 ‘USD’to_currency: (string, 必填) 目标货币代码例如 ‘CNY’输出说明说明成功和失败情况下的返回数据结构。错误码预定义的错误类型便于Agent进行后续决策如重试、转人工。实现示例我们可以用Pydantic模型来强制规范。from pydantic import BaseModel, Field from typing import List, Optional class SkillParameter(BaseModel): name: str type: str # “string”, “number”, “boolean”, “object” description: str required: bool True example: Optional[str] None class SkillDefinition(BaseModel): name: str description: str parameters: List[SkillParameter] output_schema: dict # 可以用JSON Schema描述 class CurrencyConversionSkill(Skill): property def definition(self) - SkillDefinition: # 新增一个definition属性 return SkillDefinition( name“convert_currency”, description“将指定金额从一种货币转换为另一种货币。”, parameters[ SkillParameter(name“amount”, type“number”, description“需要转换的金额”, requiredTrue, example“100”), SkillParameter(name“from_currency”, type“string”, description“原始货币的ISO 4217代码”, requiredTrue, example“USD”), SkillParameter(name“to_currency”, type“string”, description“目标货币的ISO 4217代码”, requiredTrue, example“CNY”), ], output_schema{ “type”: “object”, “properties”: { “converted_amount”: {“type”: “number”}, “rate”: {“type”: “number”}, “currency”: {“type”: “string”} } } ) # ... execute 方法 ...这样Agent的“大脑”LLM在决定调用技能前可以获得一份结构清晰、机器可读的“技能说明书”极大提高了路由准确性。3.2 技能路由与编排LLM作为决策核心有了标准化的技能定义下一步是如何让LLM如GPT-4、Claude在对话中智能地选择并调用正确的技能。这个过程称为“技能路由”或“工具调用”。主流实现方式目前OpenAI的Function Calling、Anthropic的Tool Use以及LangChain的Tools本质都是同一模式将技能定义以特定格式JSON Schema放入提示词LLM在理解用户意图后输出一个结构化的调用请求包含要调用的技能名和参数。一个简化的路由流程实现class AgentOrchestrator: def __init__(self, llm_client, skill_factory): self.llm llm_client self.skill_factory skill_factory self.conversation_history [] def _build_tools_prompt(self): 构建包含所有可用工具技能定义的提示词部分 skills self.skill_factory.list_skills() # 获取{name: description} definitions [] for name in skills: skill_obj self.skill_factory.create_skill(name) definitions.append(skill_obj.definition.model_dump_json()) # 使用Pydantic模型的JSON return “\n”.join(definitions) def process_query(self, user_input: str): # 1. 构建包含历史、工具定义和当前问题的完整提示词 full_prompt f””” 你是一个智能助手可以调用以下工具 {self._build_tools_prompt()} 历史对话 {self.conversation_history} 用户最新请求{user_input} 请分析用户请求。如果需要调用工具请严格按以下JSON格式回复 {{“action”: “call_tool”, “tool_name”: “技能名”, “parameters”: {{“参数1”: “值1”, …}}}} 如果不需要调用工具直接回复答案。 “”” # 2. 调用LLM获取决策 llm_response self.llm.generate(full_prompt) # 3. 解析LLM的响应 if self._is_tool_call(llm_response): tool_call json.loads(llm_response) skill_name tool_call[“tool_name”] params tool_call[“parameters”] # 4. 执行技能 skill self.skill_factory.create_skill(skill_name) result skill.execute(**params) # 5. 将结果反馈给LLM生成最终回复给用户 follow_up_prompt f”工具调用结果{result}。请根据此结果回复用户。” final_reply self.llm.generate(follow_up_prompt) self.conversation_history.append((user_input, final_reply)) return final_reply else: # LLM认为无需调用工具直接回复 self.conversation_history.append((user_input, llm_response)) return llm_response编排的进阶思考多技能顺序调用对于复杂请求LLM可能规划一个技能序列。这需要更复杂的Orchestrator来管理状态和中间结果。技能组合Skill Chaining可以设计一个特殊的SequentialSkill它内部按顺序执行多个子技能对外则表现为一个原子技能。这适用于那些固定且高频的流程组合。路由优化当技能数量庞大50时将所有定义塞进提示词会消耗大量Token且可能影响精度。此时可以考虑分层路由或使用Embedding进行技能检索先筛选出最相关的几个技能再让LLM做精细选择。3.3 错误处理、重试与技能熔断在分布式系统中服务会出错在Agent中技能执行也会失败。一个健壮的Skill系统必须有完善的错误处理机制。1. 技能内部的错误处理每个Skill的execute方法都应该捕获其领域内的已知异常并转化为标准错误格式。class DatabaseQuerySkill(Skill): def execute(self, **kwargs): try: # 数据库操作 result db.query(kwargs[“sql”]) return {“status”: “success”, “data”: result} except DatabaseConnectionError as e: # 捕获特定异常 logger.error(f”数据库连接失败: {e}”) return {“status”: “error”, “code”: “DB_CONNECTION_FAILED”, “message”: “无法连接数据库请稍后重试”} except InvalidQueryError as e: return {“status”: “error”, “code”: “INVALID_QUERY”, “message”: str(e)} except Exception as e: # 兜底捕获避免技能崩溃导致整个Agent挂掉 logger.exception(f”技能执行未知错误: {e}”) return {“status”: “error”, “code”: “INTERNAL_ERROR”, “message”: “技能执行内部错误”}2. 编排层的重试策略对于网络超时、临时性失败错误码为5xx编排器可以自动重试。def execute_with_retry(skill, params, max_retries2, backoff_factor1): for attempt in range(max_retries 1): try: return skill.execute(**params) except TemporaryError as e: # 自定义的临时错误异常 if attempt max_retries: raise wait_time backoff_factor * (2 ** attempt) # 指数退避 time.sleep(wait_time) logger.info(f”技能 {skill.name} 执行失败第{attempt1}次重试...”)3. 技能熔断Circuit Breaker如果一个技能连续失败多次很可能其依赖的下游服务已不可用。此时应快速失败避免资源浪费和请求堆积并给下游服务恢复的时间。这可以借鉴微服务中的熔断器模式如Hystrix。from circuitbreaker import circuit_breaker class ExternalAPISkill(Skill): circuit_breaker(failure_threshold5, recovery_timeout60) def execute(self, **kwargs): # 调用外部API response requests.post(‘https://api.example.com, jsonkwargs, timeout5) response.raise_for_status() return response.json()上面的circuit_breaker装饰器会在5次连续失败后“熔断”该技能60秒在此期间直接抛出CircuitBreakerError而不再真正调用API60秒后再进入“半开”状态试探。血泪教训早期没有加熔断一个调用缓慢的外部天气API拖垮了整个Agent的响应速度。引入熔断和超时控制后系统稳定性提升了一个数量级。给所有涉及外部调用的Skill都加上超时和熔断是上线前的必做项。3.4 技能的测试、监控与版本管理技能测试每个Skill都应该有独立的单元测试和集成测试。单元测试Mock所有外部依赖数据库、API测试技能的内部逻辑和错误处理。集成测试在测试环境中连接真实依赖测试端到端功能。契约测试确保技能的输入输出符合定义好的Schema如Pydantic模型防止接口变更导致上游调用方失败。技能监控在Skill.execute()方法入口和出口添加监控点收集关键指标执行耗时P95 P99延迟。调用次数QPS。成功率/错误率按错误码分类。Token消耗如果技能内调用LLM监控成本。可以使用装饰器或AOP面向切面编程统一实现避免污染业务代码。def monitor_skill(func): wraps(func) def wrapper(self, **kwargs): start_time time.time() skill_name self.name metrics.incr(f”skill.{skill_name}.calls”) try: result func(self, **kwargs) metrics.incr(f”skill.{skill_name}.success”) return result except Exception as e: metrics.incr(f”skill.{skill_name}.errors.{type(e).__name__}”) raise finally: duration time.time() - start_time metrics.timing(f”skill.{skill_name}.duration”, duration) return wrapper class MySkill(Skill): monitor_skill def execute(self, **kwargs): # ... 业务逻辑 ...技能版本管理当技能需要升级如修改参数、改变行为时如何平滑过渡技能名带版本号如send_email_v1,send_email_v2。Agent可以同时注册多个版本由路由逻辑决定调用哪个。向后兼容新版本技能应尽可能兼容旧版本的输入参数。无法兼容时通过版本号区分。灰度发布可以通过配置将一定比例的用户请求路由到新版本技能观察监控指标无误后再全量切换。4. 高级模式与最佳实践4.1 组合模式构建技能树与层次化技能对于大型系统技能可能会有层次结构。例如一个数据可视化技能下面可能包含生成折线图、生成柱状图、生成饼图等子技能。组合模式允许你将技能组织成树形结构使客户端可以统一对待单个技能和技能组合。class CompositeSkill(Skill): 组合技能可以包含子技能 def __init__(self, name: str): self._name name self._children [] def add(self, skill: Skill): self._children.append(skill) def remove(self, skill: Skill): self._children.remove(skill) property def name(self): return self._name def execute(self, **kwargs): results [] for child in self._children: # 可以设计不同的执行策略顺序、并行、条件执行等 result child.execute(**kwargs) results.append(result) # 组合子技能的结果 return {“status”: “success”, “sub_results”: results} # 使用 data_viz CompositeSkill(“advanced_data_visualization”) data_viz.add(LineChartSkill()) data_viz.add(BarChartSkill()) # data_viz 本身也是一个Skill可以被Agent调用4.2 技能上下文与状态管理有些技能需要共享上下文或维持状态。例如一个多轮对话收集信息的技能需要记住用户之前提供的信息。显式上下文传递将上下文作为参数在技能间传递。适合简单场景但会使接口变得臃肿。共享上下文对象创建一个全局或会话级的上下文对象Context Object所有技能都可以从中读取或写入数据。这更灵活但需要管理好上下文的生命周期和清理。状态技能设计专门的GetContextSkill和UpdateContextSkill来管理状态使状态操作也成为一种显式的、可被LLM理解和调用的能力。4.3 技能的安全与权限控制企业级应用中技能必须考虑安全。输入验证与净化所有技能入口必须对参数进行严格验证类型、范围、SQL注入/脚本注入检查。权限校验在执行技能前检查当前用户/会话是否有权调用此技能。可以将权限校验做成一个装饰器或放在Skill基类的execute方法开头。敏感操作确认对于删除、支付等高危操作技能应返回一个“需确认”的状态由Agent向用户二次确认后再执行最终动作。审计日志所有技能的调用无论成功失败都应记录详尽的审计日志谁、何时、调用什么、参数是什么、结果如何以满足合规要求。5. 常见问题与避坑指南Q1: LLM总是错误地调用技能或者该调用时不调用怎么办优化技能描述这是最常见的原因。确保描述清晰、无歧义并使用示例。可以尝试用少量示例Few-shot来教LLM如何选择。调整温度参数在技能路由决策时使用较低的温度如0.1或0以减少随机性。后处理与校验LLM输出的调用请求在执行前可以用一套规则进行校验如必填参数是否缺失如果校验失败可以要求LLM重新思考。技能检索技能太多时先用Embedding做一次粗筛只把最相关的几个技能描述喂给LLM做精细选择。Q2: 技能执行慢拖累了整个Agent的响应速度。异步执行对于I/O密集型技能网络请求、数据库查询使用异步模式asyncio。设置超时为每个技能设置合理的超时时间超时后立即失败避免阻塞。引入缓存对于结果变化不频繁的技能如查询静态信息可以引入缓存内存缓存如Redis并设置合适的TTL。熔断与降级如上文所述使用熔断器防止被故障下游拖垮并设计降级方案如返回缓存旧数据、返回简化结果。Q3: 技能间的数据依赖很复杂如何管理设计数据契约明确定义每个技能的输入输出Schema并作为接口文档。使用Pydantic等工具进行运行时校验。使用工作流引擎对于固定的复杂流程使用工作流如责任链模式来显式管理执行顺序和数据流。上下文管理器设计一个“上下文管理器”技能或模块专门负责在复杂多步对话中维护和提供共享数据。Q4: 如何调试一个不工作的技能结构化日志在技能的关键步骤打上带唯一请求ID的日志方便追踪整个调用链。隔离测试将技能单独拿出来用模拟输入进行测试排除Agent其他部分的影响。检查LLM输入输出记录下LLM做路由决策时的完整提示词和回复看看是否是描述理解有误。监控与告警建立针对技能错误率和延迟的监控看板并设置告警。设计模式不是银弹但它们是应对复杂软件问题的强大工具箱。在Agent Skill的设计中灵活运用策略、工厂、责任链等模式结合坚实的工程实践标准化、错误处理、监控你构建的将不再是一个脆弱的“脚本集合”而是一个真正可扩展、可维护、高可用的智能能力中台。这套体系能让你在面对层出不穷的新需求时从容地像搭积木一样组合出新的智能解决方案这才是Agent Skill设计模式的终极价值。
