Registry Module

This module provides a centralized registration center for agents and environment modules, supporting lazy loading.

ModuleRegistry

class agentsociety2.registry.ModuleRegistry

Bases: object

Centralized registry (singleton) for agent and environment modules.

Two types of sources are supported:

• Built-in modules: from agentsociety2.contrib with built-in agents (e.g. PersonAgent)

• Custom module: custom/ directory from workspace

Lazy loading is enabled by default: discovery and registration are only triggered when registry content is accessed for the first time.

__init__()

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

Returns the registered environment module mapping and triggers lazy loading on access.

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

Returns the registered agent mapping and triggers lazy loading on access.

register_env_module(module_type, module_class, is_custom=False)

Register environment module.

Parameters:

• module_type (str) – type identifier (e.g. simple_social_space).

• module_class (Type[EnvBase]) – Environment module class.

• is_custom (bool) – Whether it is a custom module.

register_agent_module(agent_type, agent_class, is_custom=False)

Register agent.

Parameters:

• agent_type (str) – type identifier (e.g. person_agent).

• agent_class (Type[AgentBase]) – agent class.

• is_custom (bool) – Whether it is a custom agent.

get_env_module(module_type)

Get the environment module class by type (will trigger lazy loading).

Parameters:

module_type (str) – type identifier。

Returns:

Environment module class; not found returns None.

Return type:

Type[EnvBase] | None

get_agent_module(agent_type)

Get the agent class by type (will trigger lazy loading).

Parameters:

agent_type (str) – type identifier。

Returns:

Agent class; not found returns None.

Return type:

Type[AgentBase] | None

list_env_modules()

Returns the list of registered environment modules and triggers lazy loading on access.

list_agent_modules()

Returns the list of registered agents and triggers lazy loading on access.

set_workspace(workspace_path)

Set workspace path (for custom module discovery).

Parameters:

workspace_path (Path) – workspace directory.

load_builtin_modules()

Actively load built-in modules (disable lazy waiting).

load_custom_modules()

Actively load custom modules (disable lazy waiting).

load_all_modules()

Actively load all modules (built-in + custom).

clear_custom_modules()

Clear all custom modules in the registry.

get_module_info(module_type, kind)

Get module information (will trigger lazy loading).

Parameters:

• module_type (str) – type identifier。

• kind (str) – env_module or agent.

Returns:

Module information dictionary (including parameter signature, description, whether it is custom, etc.).

Return type:

Dict[str, Any]

Utility function

agentsociety2.registry.get_registry()

Returns:

Global ModuleRegistry Singleton.

Return type:

ModuleRegistry

Register function

agentsociety2.registry.get_registered_env_modules()

Returns:

List of registered environment modules [(module_type, module_class), ...].

Return type:

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

agentsociety2.registry.get_registered_agent_modules()

Returns:

Registered agent list [(agent_type, agent_class), ...].

Return type:

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

agentsociety2.registry.get_env_module_class(module_type)

Get the environment module class by type.

Parameters:

module_type (str) – type identifier。

Returns:

Environment module class; not found returns None.

Return type:

Type[EnvBase] | None

agentsociety2.registry.get_agent_module_class(agent_type)

Get the agent class by type.

Parameters:

agent_type (str) – type identifier。

Returns:

agent class; not found returns None.

Return type:

Type[AgentBase] | None

agentsociety2.registry.list_all_modules()

List all registered modules (including description and custom flag).

agentsociety2.registry.reload_modules(workspace_path=None)

Empty and rediscover modules (load on demand).

Parameters:

workspace_path (Path | None) – Optional workspace path (for custom modules).

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

Scan and register custom modules under custom/.

Parameters:

• workspace_path (Path) – workspace path.

• registry (ModuleRegistry | None) – Optional registry; empty to use the global registry.

Returns:

scan results (including envs/agents/errors).

Return type:

Dict[str, Any]

agentsociety2.registry.discover_and_register_builtin_modules(registry=None)

Discover and register all built-in modules (contrib + built-in agent).

Parameters:

registry (ModuleRegistry | None) – Optional registry; empty to use the global registry.

request/response model

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

Environment module initialization configuration.

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 initialization configuration.

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)

Create the request body of the AgentSociety instance.

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)

The request body for asking the instance.

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)

The request body to intervene on the instance.

instance_id: str

instruction: str

model_config = {}

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