作者：WangQiaomei

版本：1.0（2026/3/23）

核心亮点：零配置自动注册、热插拔扩展、解耦式设计，让你的 AI Agent 系统像搭积木一样简单！

---

🔥痛点直击：你还在手动注册 Agent/Skill/Tool？太 Low 了！

是不是还在写这种 "垃圾代码" 管理 AI 组件？

python

运行

# ❌ 低效又僵化的手动注册
from agents.app_expert import AppExpertAgent
from skills.mysql_cpu import analyze_mysql_cpu
from tools.prometheus import query_prometheus

# 手动添加到全局字典
agents = {"app-expert": AppExpertAgent}
skills = {"mysql-cpu-analysis": analyze_mysql_cpu}
tools = {"prometheus-query": query_prometheus}

# 新增功能还要改这里，代码越堆越乱！

今天教你用装饰器 + 动态导入 + 全局注册表的组合拳，实现Agent/Skill/Tool 自动注册，

新增功能只需：

✅ 创建文件 → ✅ 加装饰器 → ✅ 放到对应目录全程零配置、零修改主代码，真正的 "即插即用"！

---

🎯架构概览：一张图看懂自动注册流程

plaintext

┌─────────────────────────────────────────────────────────────────┐
│                        应用启动 (main.py)                        │
│                              │                                   │
│                              ▼                                   │
│                     AutoDiscovery.discover_all()                │
│                              │                                   │
│              ┌───────────────┼───────────────┐                  │
│              ▼               ▼               ▼                  │
│          agents/         skills/         tools/                 │
│              │               │               │                  │
│              ▼               ▼               ▼                  │
│      importlib.import_module() 动态导入模块                      │
│              │               │               │                  │
│              ▼               ▼               ▼                  │
│       @register_agent  @register_skill  @register_tool          │
│              │               │               │                  │
│              └───────────────┼───────────────┘                  │
│                              ▼                                   │
│                     Registry (全局注册表)                        │
│                   _agents / _skills / _tools                    │
└─────────────────────────────────────────────────────────────────┘

---

🛠️核心组件拆解：四大模块实现自动注册

1. 全局注册表：统一管理元数据（单例设计）

用类变量实现全局单例，存储所有 Agent/Skill/Tool 的元数据，随时可查、随时可用。

python

运行

# app/core/registry.py
from dataclasses import dataclass, field
from typing import Dict, Type, Callable, List

@dataclass
class AgentMeta:
    id: str           # 唯一标识
    name: str         # 显示名称
    description: str  # 功能描述
    llm: str          # 绑定的大模型
    cls: Type         # Agent类引用
    skills: List[str] = field(default_factory=list)  # 关联技能

@dataclass
class SkillMeta:
    id: str
    name: str
    agents: List[str]  # 所属Agent
    func: Callable     # 技能函数
    tools: List[str]   # 依赖工具

@dataclass
class ToolMeta:
    id: str
    name: str
    params: Dict       # 参数定义（自动解析函数签名）
    func: Callable     # 工具函数

class Registry:
    """全局注册表 - 类变量实现单例，无需实例化"""
    _agents: Dict[str, AgentMeta] = {}
    _skills: Dict[str, SkillMeta] = {}
    _tools: Dict[str, ToolMeta] = {}

    @classmethod
    def register_agent(cls, meta: AgentMeta):
        cls._agents[meta.id] = meta

    @classmethod
    def register_skill(cls, meta: SkillMeta):
        cls._skills[meta.id] = meta
        # 自动关联到对应Agent
        for agent_id in meta.agents:
            if agent_id in cls._agents:
                cls._agents[agent_id].skills.append(meta.id)

    @classmethod
    def register_tool(cls, meta: ToolMeta):
        cls._tools[meta.id] = meta

2. 装饰器：一键注册，零侵入式设计

用装饰器封装注册逻辑，只需给类 / 函数加一行装饰器，自动完成元数据提取与注册。

python

运行

# infrastructure/decorators/__init__.py
import inspect
from app.core.registry import Registry, AgentMeta, SkillMeta, ToolMeta

def register_agent(id: str, name: str, description: str, llm: str = "dashscope:qwen3-max"):
    """Agent注册装饰器"""
    def decorator(cls):
        meta = AgentMeta(id=id, name=name, description=description, llm=llm, cls=cls)
        Registry.register_agent(meta)
        cls._meta = meta  # 元数据绑定到类属性
        return cls
    return decorator

def register_skill(id: str, name: str, agent: Union[str, List[str]], tools: List[str] = None):
    """Skill注册装饰器"""
    def decorator(func):
        meta = SkillMeta(id=id, name=name, agents=[agent] if isinstance(agent, str) else agent,
                         func=func, tools=tools or [])
        Registry.register_skill(meta)
        func._meta = meta
        return func
    return decorator

def register_tool(id: str, name: str, description: str = ""):
    """Tool注册装饰器 - 自动解析函数签名提取参数"""
    def decorator(func):
        sig = inspect.signature(func)
        params = {name: param.annotation for name, param in sig.parameters.items()}
        meta = ToolMeta(id=id, name=name, params=params, func=func)
        Registry.register_tool(meta)
        return func
    return decorator

3. AutoDiscovery：自动扫描 + 动态导入

启动时自动扫描指定目录，动态导入所有模块，触发装饰器执行，实现 "零配置注册"。

python

运行

# app/core/discovery.py
import importlib
from pathlib import Path
import sys

class AutoDiscovery:
    def __init__(self, base_path: str):
        self.base_path = Path(base_path).resolve()
        sys.path.insert(0, str(self.base_path))  # 添加到Python路径

    def discover_all(self, packages: List[str]):
        """扫描并加载所有模块"""
        for package in packages:
            self._discover(package)

    def _discover(self, package: str):
        # 递归扫描目录下所有.py文件（跳过下划线开头的文件）
        for py_file in (self.base_path / package).rglob("*.py"):
            if py_file.name.startswith("_"):
                continue
            # 转换路径为模块名：skills/mysql/cpu_use.py → skills.mysql.cpu_use
            module_path = ".".join(py_file.relative_to(self.base_path).with_suffix("").parts)
            importlib.import_module(module_path)  # 导入触发装饰器

4. 应用启动入口：一键触发自动注册

在 FastAPI 的lifespan中执行自动发现，启动时完成所有组件注册。

python

运行

# main.py
from fastapi import FastAPI
from contextlib import asynccontextmanager
from app.core.discovery import AutoDiscovery
from app.core.registry import Registry
import settings

@asynccontextmanager
async def lifespan(app: FastAPI):
    # 启动时自动扫描并注册
    discovery = AutoDiscovery(base_path=str(settings.INFRASTRUCTURE_DIR))
    discovery.discover_all(["agents", "skills", "tools"])
    
    # 验证注册结果
    logger.info(f"✅ 自动注册完成：{len(Registry._agents)}个Agent，{len(Registry._skills)}个Skill，{len(Registry._tools)}个Tool")
    yield

app = FastAPI(lifespan=lifespan)

---

🚀实战示例：3 步新增一个 Agent/Skill/Tool

步骤 1：定义 Agent（只需加装饰器）

python

运行

# infrastructure/agents/app_expert.py
from infrastructure.decorators import register_agent

@register_agent(
    id="app-expert",
    name="应用专家智能体",
    description="应用健康诊断、故障定位、性能分析专家",
    llm=f"dashscope:{settings.DASHSCOPE_LLM_MODEL}"
)
class AppExpertAgent:
    async def process(self, message: str, context: dict) -> str:
        return f"[{self.name}] 收到消息: {message}"

步骤 2：定义 Skill（绑定 Agent + 依赖 Tool）

python

运行

# infrastructure/skills/mysql/cpu_use.py
from infrastructure.decorators import register_skill

@register_skill(
    id="mysql-cpu-analysis",
    name="MySQL CPU分析",
    agent="db-expert",           # 绑定到数据库专家Agent
    tools=["prometheus-query"]   # 依赖Prometheus查询工具
)
async def analyze_mysql_cpu(instance: str, time_range: str = "1h"):
    # 技能实现逻辑
    return {"instance": instance, "time_range": time_range, "result": "CPU使用率正常"}

步骤 3：定义 Tool（自动解析参数）

python

运行

# infrastructure/tools/prometheus.py
from infrastructure.decorators import register_tool

@register_tool(
    id="prometheus-query",
    name="Prometheus查询",
    description="执行PromQL查询获取监控数据"
)
def query_prometheus(promql: str, start: str, end: str) -> dict:
    # 工具实现逻辑
    return {"promql": promql, "start": start, "end": end, "data": []}

---

🎨关系模型：Agent→Skill→Tool 的联动逻辑

plaintext

Agent (1) ──────< (N) Skill (1) ──────< (N) Tool
   │                    │                   │
   │                    │                   │
   ▼                    ▼                   ▼
AppExpertAgent    mysql-cpu-analysis   prometheus-query
DbExpertAgent     memory-analysis      easyops-api
K8sExpertAgent    disk-io-check        kubectl-exec

---

✨设计优点：为什么这套架构值得用？

表格

特性	说明
零配置	无需手动修改主代码，放到对应目录自动生效
解耦	Agent/Skill/Tool 通过 ID 关联，互不依赖，独立迭代
可扩展	新增功能只需创建文件 + 加装饰器，10 分钟搞定
热插拔	删除文件即移除功能，无需重启服务
元数据驱动	自动提取参数信息，可快速生成 API 文档 / 前端界面

---

📁目录结构：规范清晰，一目了然

plaintext

backend/
├── infrastructure/
│   ├── agents/          # Agent目录：每个文件对应一个Agent
│   │   ├── app_expert.py
│   │   └── db_expert.py
│   ├── skills/          # Skill目录：按业务模块分类
│   │   ├── mysql/
│   │   │   └── cpu_use.py
│   │   └── k8s/
│   │       └── pod_status.py
│   ├── tools/           # Tool目录：每个文件对应一个工具
│   │   ├── prometheus.py
│   │   └── easyops.py
│   └── decorators/      # 装饰器定义
│       └── __init__.py
├── app/
│   ├── core/
│   │   ├── discovery.py # 自动发现模块
│   │   └── registry.py  # 全局注册表
│   └── main.py          # 启动入口
└── settings.py          # 配置文件

---

🎯核心原理总结：3 个全局字典搞定一切

plaintext

main.py启动 → discover_all()扫描目录 → 动态导入模块 → 触发装饰器 → 填充Registry的3个全局字典：
- Registry._agents：存储所有Agent元数据
- Registry._skills：存储所有Skill元数据
- Registry._tools：存储所有Tool元数据

后续任何地方都可以通过Registry._agents["app-expert"]直接获取组件，无需重复导入！

---

🚩避坑指南（新手必看）

1. 目录结构要规范：Agent/Skill/Tool 必须放到对应目录，否则扫描不到；
2. ID 必须唯一：每个 Agent/Skill/Tool 的 id 不能重复，否则会覆盖；
3. 装饰器参数要正确：Skill 的agent参数要对应已注册的 Agent id；
4. 动态导入路径：确保base_path正确，否则模块导入失败。

---

📝最终总结

这套自动注册机制的核心是装饰器 + 动态导入 + 全局注册表，让 AI Agent 系统的扩展变得像搭积木一样简单：

• 新增功能：创建文件→加装饰器→放到对应目录，全程零配置；
• 管理组件：通过全局字典统一管理，随时调用、随时扩展；
• 系统解耦：Agent/Skill/Tool 独立迭代，互不影响。

想要进阶玩法？留言告诉我

✅ 如何实现 Agent/Skill/Tool 的权限控制

✅ 如何动态禁用 / 启用组件

✅ 如何生成组件的 API 文档