作者WangQiaomei版本1.02026/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_factorylist) # 关联技能 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] meta2. 装饰器一键注册零侵入式设计用装饰器封装注册逻辑只需给类 / 函数加一行装饰器自动完成元数据提取与注册。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(idid, namename, descriptiondescription, llmllm, clscls) 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(idid, namename, agents[agent] if isinstance(agent, str) else agent, funcfunc, toolstools 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(idid, namename, paramsparams, funcfunc) Registry.register_tool(meta) return func return decorator3. 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_pathstr(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(lifespanlifespan)实战示例3 步新增一个 Agent/Skill/Tool步骤 1定义 Agent只需加装饰器python运行# infrastructure/agents/app_expert.py from infrastructure.decorators import register_agent register_agent( idapp-expert, name应用专家智能体, description应用健康诊断、故障定位、性能分析专家, llmfdashscope:{settings.DASHSCOPE_LLM_MODEL} ) class AppExpertAgent: async def process(self, message: str, context: dict) - str: return f[{self.name}] 收到消息: {message}步骤 2定义 Skill绑定 Agent 依赖 Toolpython运行# infrastructure/skills/mysql/cpu_use.py from infrastructure.decorators import register_skill register_skill( idmysql-cpu-analysis, nameMySQL CPU分析, agentdb-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( idprometheus-query, namePrometheus查询, description执行PromQL查询获取监控数据 ) def query_prometheus(promql: str, start: str, end: str) - dict: # 工具实现逻辑 return {promql: promql, start: start, end: end, data: []}关系模型Agent→Skill→Tool 的联动逻辑plaintextAgent (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 文档 / 前端界面目录结构规范清晰一目了然plaintextbackend/ ├── 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 个全局字典搞定一切plaintextmain.py启动 → discover_all()扫描目录 → 动态导入模块 → 触发装饰器 → 填充Registry的3个全局字典 - Registry._agents存储所有Agent元数据 - Registry._skills存储所有Skill元数据 - Registry._tools存储所有Tool元数据后续任何地方都可以通过Registry._agents[app-expert]直接获取组件无需重复导入避坑指南新手必看目录结构要规范Agent/Skill/Tool 必须放到对应目录否则扫描不到ID 必须唯一每个 Agent/Skill/Tool 的 id 不能重复否则会覆盖装饰器参数要正确Skill 的agent参数要对应已注册的 Agent id动态导入路径确保base_path正确否则模块导入失败。最终总结这套自动注册机制的核心是装饰器 动态导入 全局注册表让 AI Agent 系统的扩展变得像搭积木一样简单新增功能创建文件→加装饰器→放到对应目录全程零配置管理组件通过全局字典统一管理随时调用、随时扩展系统解耦Agent/Skill/Tool 独立迭代互不影响。想要进阶玩法留言告诉我✅ 如何实现 Agent/Skill/Tool 的权限控制✅ 如何动态禁用 / 启用组件✅ 如何生成组件的 API 文档
AI Agent 架构封神技：自动注册机制，让你 10 分钟上线新功能
作者WangQiaomei版本1.02026/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_factorylist) # 关联技能 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] meta2. 装饰器一键注册零侵入式设计用装饰器封装注册逻辑只需给类 / 函数加一行装饰器自动完成元数据提取与注册。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(idid, namename, descriptiondescription, llmllm, clscls) 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(idid, namename, agents[agent] if isinstance(agent, str) else agent, funcfunc, toolstools 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(idid, namename, paramsparams, funcfunc) Registry.register_tool(meta) return func return decorator3. 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_pathstr(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(lifespanlifespan)实战示例3 步新增一个 Agent/Skill/Tool步骤 1定义 Agent只需加装饰器python运行# infrastructure/agents/app_expert.py from infrastructure.decorators import register_agent register_agent( idapp-expert, name应用专家智能体, description应用健康诊断、故障定位、性能分析专家, llmfdashscope:{settings.DASHSCOPE_LLM_MODEL} ) class AppExpertAgent: async def process(self, message: str, context: dict) - str: return f[{self.name}] 收到消息: {message}步骤 2定义 Skill绑定 Agent 依赖 Toolpython运行# infrastructure/skills/mysql/cpu_use.py from infrastructure.decorators import register_skill register_skill( idmysql-cpu-analysis, nameMySQL CPU分析, agentdb-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( idprometheus-query, namePrometheus查询, description执行PromQL查询获取监控数据 ) def query_prometheus(promql: str, start: str, end: str) - dict: # 工具实现逻辑 return {promql: promql, start: start, end: end, data: []}关系模型Agent→Skill→Tool 的联动逻辑plaintextAgent (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 文档 / 前端界面目录结构规范清晰一目了然plaintextbackend/ ├── 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 个全局字典搞定一切plaintextmain.py启动 → discover_all()扫描目录 → 动态导入模块 → 触发装饰器 → 填充Registry的3个全局字典 - Registry._agents存储所有Agent元数据 - Registry._skills存储所有Skill元数据 - Registry._tools存储所有Tool元数据后续任何地方都可以通过Registry._agents[app-expert]直接获取组件无需重复导入避坑指南新手必看目录结构要规范Agent/Skill/Tool 必须放到对应目录否则扫描不到ID 必须唯一每个 Agent/Skill/Tool 的 id 不能重复否则会覆盖装饰器参数要正确Skill 的agent参数要对应已注册的 Agent id动态导入路径确保base_path正确否则模块导入失败。最终总结这套自动注册机制的核心是装饰器 动态导入 全局注册表让 AI Agent 系统的扩展变得像搭积木一样简单新增功能创建文件→加装饰器→放到对应目录全程零配置管理组件通过全局字典统一管理随时调用、随时扩展系统解耦Agent/Skill/Tool 独立迭代互不影响。想要进阶玩法留言告诉我✅ 如何实现 Agent/Skill/Tool 的权限控制✅ 如何动态禁用 / 启用组件✅ 如何生成组件的 API 文档
