Registry 模块

本模块提供智能体和环境模块的集中注册中心，支持延迟加载。

ModuleRegistry

class agentsociety2.registry.ModuleRegistry

基类：object

agent 与环境模块的集中注册中心（单例）。

支持两类来源：

• 内置模块：来自 agentsociety2.contrib 与内置 agent（例如 PersonAgent）

• 自定义模块：来自 workspace 的 custom/ 目录

默认启用惰性加载：只有在第一次访问 registry 内容时才触发发现与注册。

__init__()

property env_modules: Dict[str, Type[EnvBase]]

返回已注册环境模块映射，并在访问时触发惰性加载。

property agent_modules: Dict[str, Type[AgentBase]]

返回已注册 agent 映射，并在访问时触发惰性加载。

register_env_module(module_type, module_class, is_custom=False)

注册环境模块。

参数:

• module_type (str) -- type identifier（例如 simple_social_space）。

• module_class (Type[EnvBase]) -- 环境模块类。

• is_custom (bool) -- 是否为自定义模块。

register_agent_module(agent_type, agent_class, is_custom=False)

注册 agent。

参数:

• agent_type (str) -- type identifier（例如 person_agent）。

• agent_class (Type[AgentBase]) -- agent 类。

• is_custom (bool) -- 是否为自定义 agent。

get_env_module(module_type)

按 type 获取环境模块类（会触发惰性加载）。

参数:

module_type (str) -- type identifier。

返回:

环境模块类；未找到返回 None。

返回类型:

Type[EnvBase] | None

get_agent_module(agent_type)

按 type 获取 agent 类（会触发惰性加载）。

参数:

agent_type (str) -- type identifier。

返回:

agent 类；未找到返回 None。

返回类型:

Type[AgentBase] | None

list_env_modules()

返回已注册环境模块列表，并在访问时触发惰性加载。

list_agent_modules()

返回已注册 agent 列表，并在访问时触发惰性加载。

set_workspace(workspace_path)

设置 workspace 路径（用于 custom 模块发现）。

参数:

workspace_path (Path) -- workspace 目录。

load_builtin_modules()

主动加载内置模块（禁用惰性等待）。

load_custom_modules()

主动加载自定义模块（禁用惰性等待）。

load_all_modules()

主动加载全部模块（内置 + 自定义）。

clear_custom_modules()

清除 registry 中所有 custom 模块。

get_module_info(module_type, kind)

获取模块信息（会触发惰性加载）。

参数:

• module_type (str) -- type identifier。

• kind (str) -- env_module 或 agent。

返回:

模块信息字典（含参数签名、描述、是否 custom 等）。

返回类型:

Dict[str, Any]

工具函数

agentsociety2.registry.get_registry()

返回:

全局 ModuleRegistry 单例。

返回类型:

ModuleRegistry

注册函数

agentsociety2.registry.get_registered_env_modules()

返回:

已注册环境模块列表 [(module_type, module_class), ...]。

返回类型:

List[Tuple[str, Type[EnvBase]]]

agentsociety2.registry.get_registered_agent_modules()

返回:

已注册 agent 列表 [(agent_type, agent_class), ...]。

返回类型:

List[Tuple[str, Type[AgentBase]]]

agentsociety2.registry.get_env_module_class(module_type)

按 type 获取环境模块类。

参数:

module_type (str) -- type identifier。

返回:

环境模块 class；未找到返回 None。

返回类型:

Type[EnvBase] | None

agentsociety2.registry.get_agent_module_class(agent_type)

按 type 获取 agent 类。

参数:

agent_type (str) -- type identifier。

返回:

agent class；未找到返回 None。

返回类型:

Type[AgentBase] | None

agentsociety2.registry.list_all_modules()

列出所有已注册模块（含描述与是否 custom 标记）。

agentsociety2.registry.reload_modules(workspace_path=None)

清空并重新发现模块（按需加载）。

参数:

workspace_path (Path | None) -- 可选 workspace 路径（用于 custom 模块）。

agentsociety2.registry.scan_and_register_custom_modules(workspace_path, registry=None)

扫描并注册 custom/ 下的自定义模块。

参数:

• workspace_path (Path) -- workspace 路径。

• registry (ModuleRegistry | None) -- 可选注册中心；为空则使用全局 registry。

返回:

scan 结果（包含 envs/agents/errors）。

返回类型:

Dict[str, Any]

agentsociety2.registry.discover_and_register_builtin_modules(registry=None)

发现并注册所有内置模块（contrib + 内置 agent）。

参数:

registry (ModuleRegistry | None) -- 可选注册中心；为空则使用全局 registry。

请求/响应模型

class agentsociety2.registry.EnvModuleInitConfig(*, module_type, args=<factory>)

环境模块初始化配置。

module_type: str

args: Dict[str, Any]

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.registry.AgentInitConfig(*, agent_type, agent_id, args=<factory>)

agent 初始化配置。

agent_type: str

agent_id: int

args: Dict[str, Any]

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.registry.CreateInstanceRequest(*, instance_id, env_modules, agents, start_t, tick=1)

创建 AgentSociety 实例的请求体。

instance_id: str

env_modules: List[EnvModuleInitConfig]

agents: List[AgentInitConfig]

start_t: datetime

tick: int

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.registry.AskRequest(*, instance_id, question)

对实例进行 ask 的请求体。

instance_id: str

question: str

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class agentsociety2.registry.InterventionRequest(*, instance_id, instruction)

对实例进行 intervene 的请求体。

instance_id: str

instruction: str

model_config = {}

Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].