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-else ：

if “总结销售数据” 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”: “邮件已发送”}

关键设计考量：

  1. 统一的执行接口 ： execute 方法让Agent的核心调度器可以用同一套方式调用任何技能，大大简化了调度逻辑。
  2. 自描述性 ： name 和 description 属性至关重要。在基于LLM的Agent中，我们通常会把所有技能的描述拼接成提示词（Prompt），让LLM自己决定在什么情况下调用哪个技能。这就是所谓的“技能路由”。
  3. 输入输出标准化 ： 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):
    # ... 实现同上 ...

这样做的好处：

  1. 解耦 ：Agent核心代码与具体技能实现完全分离。新增一个技能，只需要写一个新的Skill类并用装饰器注册，核心调度代码一行都不用改。
  2. 动态配置 ：你可以从配置文件、数据库甚至远程API加载技能列表，然后动态注册到工厂中，实现技能的“热插拔”。
  3. 集中管理 ：工厂成为了所有技能的单一访问点，便于进行统一的日志、监控、权限校验等横切关注点（Aspect）的管理。

2.3 责任链模式：构建复杂的技能工作流

用户的一个复杂请求，往往需要多个技能协作完成。例如，“查一下北京天气，如果下雨就提醒我带伞，并把提醒加到日历里”。这涉及到 天气查询 -> 条件判断 -> 日历创建 三个步骤。责任链模式非常适合处理这种 管道式 或 工作流式 的技能执行。

责任链模式的核心： 使多个对象（技能）都有机会处理请求，从而避免请求发送者与接收者之间的耦合。将这些对象连成一条链，并沿着这条链传递请求，直到有一个对象处理它为止。在Agent中，我们可以让一个技能执行完毕后，主动将结果和上下文传递给下一个合适的技能。

工作流引擎的简化实现： 

class WorkflowSkill(Skill):
    """一个特殊的技能，它本身是一个由多个子技能构成的工作流"""
    def __init__(self):
        self.skill_chain = []  # 技能执行链

    def add_skill(self, skill: Skill, condition=None):
        """向工作流中添加一个技能及其触发条件"""
        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(), condition=lambda 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(), condition=need_reminder)

模式价值：

  1. 流程可视化 ：工作流Skill本身也是一个Skill，可以被Agent平等调度。这使得复杂流程得以模块化。
  2. 灵活性 ：你可以轻松调整技能链的顺序，或基于中间结果动态跳过某些技能。
  3. 错误隔离 ：可以在工作流中设置错误处理技能，专门捕获和处理链中其他技能抛出的异常，避免整个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:
        # 返回 <weather><city>101010100</city><info>sunny</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描述应包含：

  1. 功能名称 ：简洁动词开头，如 calculate_quote , fetch_user_profile 。
  2. 自然语言描述 ：用一句话说明技能做什么。 关键：描述使用场景而非实现 。例如：“当用户需要将金额从一种货币转换为另一种货币时使用此技能。”
  3. 输入参数 ：明确每个参数的名称、类型、是否必填、描述和示例。
    • 坏例子 ： amount, from_currency, to_currency
    • 好例子 ：
      • amount: (float, 必填) 需要转换的金额，例如 100.0
      • from_currency: (string, 必填) 原始货币代码（ISO 4217），例如 ‘USD’
      • to_currency: (string, 必填) 目标货币代码，例如 ‘CNY’
  4. 输出说明 ：说明成功和失败情况下的返回数据结构。
  5. 错误码 ：预定义的错误类型，便于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=“需要转换的金额”, required=True, example=“100”),
                SkillParameter(name=“from_currency”, type=“string”, description=“原始货币的ISO 4217代码”, required=True, example=“USD”),
                SkillParameter(name=“to_currency”, type=“string”, description=“目标货币的ISO 4217代码”, required=True, 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_retries=2, backoff_factor=1):
    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} 执行失败，第{attempt+1}次重试...”)

3. 技能熔断（Circuit Breaker）： 如果一个技能连续失败多次，很可能其依赖的下游服务已不可用。此时应快速失败，避免资源浪费和请求堆积，并给下游服务恢复的时间。这可以借鉴微服务中的熔断器模式（如Hystrix）。

from circuitbreaker import circuit_breaker

class ExternalAPISkill(Skill):
    @circuit_breaker(failure_threshold=5, recovery_timeout=60)
    def execute(self, **kwargs):
        # 调用外部API
        response = requests.post(‘https://api.example.com', json=kwargs, timeout=5)
        response.raise_for_status()
        return response.json()

上面的 @circuit_breaker 装饰器会在5次连续失败后“熔断”该技能60秒，在此期间直接抛出 CircuitBreakerError 而不再真正调用API，60秒后再进入“半开”状态试探。

血泪教训 ：早期没有加熔断，一个调用缓慢的外部天气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):
        # ... 业务逻辑 ...

技能版本管理： 当技能需要升级（如修改参数、改变行为）时，如何平滑过渡？

  1. 技能名带版本号 ：如 send_email_v1 , send_email_v2 。Agent可以同时注册多个版本，由路由逻辑决定调用哪个。
  2. 向后兼容 ：新版本技能应尽可能兼容旧版本的输入参数。无法兼容时，通过版本号区分。
  3. 灰度发布 ：可以通过配置，将一定比例的用户请求路由到新版本技能，观察监控指标无误后再全量切换。

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 技能的安全与权限控制

企业级应用中，技能必须考虑安全。

  1. 输入验证与净化 ：所有技能入口必须对参数进行严格验证（类型、范围、SQL注入/脚本注入检查）。
  2. 权限校验 ：在执行技能前，检查当前用户/会话是否有权调用此技能。可以将权限校验做成一个装饰器或放在Skill基类的 execute 方法开头。
  3. 敏感操作确认 ：对于删除、支付等高危操作，技能应返回一个“需确认”的状态，由Agent向用户二次确认后再执行最终动作。
  4. 审计日志 ：所有技能的调用，无论成功失败，都应记录详尽的审计日志（谁、何时、调用什么、参数是什么、结果如何），以满足合规要求。

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设计模式的终极价值。

# AI Agent # 设计模式 # 策略模式
Logo
码道开发者社区

码道开发者社区，聚焦华为云码道 CodeArts 代码智能体，沉淀 Agent、Skill、鸿蒙开发实战内容，供开发者查阅资料、交流技术、分享工程实践

更多推荐

Manim 数学动画完全指南：五分钟从零到成片

Manim 是用 Python 驱动的数学动画引擎，把抽象的公式与曲线转成逐帧可控的动态可视化。适合想制作 Python 数学可视化视频的编程新手、数学学生和科普创作者。## 数学为什么需要"动"起来你试过用一张静态图讲清导数的概念吗？切线、割线、极限位置都能画出来，但"割线逼近切线"发生的那一下，观众只能靠脑补。课本插图大多是"结论截图"：只留下最终状态，过程被压缩成一句"易见"。函

avatar 码道开发者社区
cover

Claude API + Python实战：结构化输出后，如何拦住“看起来正确”的JSON

avatar 码道开发者社区
cover

GLM-5.3-Flash深度解析：3200亿参数只卖Opus四十分之一，国产算力首次跑通前沿模型

avatar 码道开发者社区