base

agent

class xuance.tensorflow.agents.base.agent.Agent(config: Namespace, envs: DummyVecEnv | SubprocVecEnv | None = None, observation_space: gymnasium.spaces.Space | None = None, action_space: gymnasium.spaces.Space | None = None, callback: BaseCallback | None = None)

Bases: ABC

Base class for single-agent Deep Reinforcement Learning (DRL).

This class defines the common interface and shared infrastructure for single-agent DRL algorithms in XuanCe. An Agent encapsulates the policy, learner, and training/testing logic, while environments are managed externally by the runner or provided explicitly by the user.

The agent can be initialized either with training environments (envs) or, for inference/testing-only scenarios, without environments but with explicit observation and action spaces.

Parameters:

• config (Namespace) – Configuration object containing hyperparameters, runtime settings, and environment specifications.

• envs (Optional[DummyVecEnv | SubprocVecEnv]) – Vectorized environments used for training. If None, the agent will not initialize training environments and must be provided with observation_space and action_space to build networks.

• observation_space (Optional[gymnasium.spaces.Space]) – Observation space specification used to construct policy networks when envs is None. Typically obtained from test_envs.observation_space.

• action_space (Optional[gymnasium.spaces.Space]) – Action space specification used to construct policy networks when envs is None. Typically obtained from test_envs.action_space.

• callback (Optional[BaseCallback]) – Optional callback object for injecting custom logic during training or evaluation (e.g., logging, early stopping, or custom hooks).

Notes

• When envs is provided, the agent assumes a training context and derives observation/action spaces from the environments.

• When envs is None, the agent can still be used for evaluation or inference as long as the corresponding spaces are explicitly given.

• Environment creation and lifecycle management are intentionally decoupled from the agent and handled by the runner or user code.

finish()

abstractmethod get_actions(observations)

load_model(path, model=None)

log_infos(info: dict, x_index: int)

info: (dict) information to be visualized n_steps: current step

log_videos(info: dict, fps: int, x_index: int = 0)

save_model(model_name, model_path=None)

abstractmethod test(test_episodes: int, test_envs: DummyVecEnv | SubprocVecEnv | None = None, close_envs: bool = True)

abstractmethod train(train_steps: int) → dict

agents_marl

class xuance.tensorflow.agents.base.agents_marl.MARLAgents(config: Namespace, envs: DummyVecMultiAgentEnv | SubprocVecMultiAgentEnv | None = None, num_agents: int | None = None, agent_keys: List[str] | None = None, state_space: gymnasium.spaces.Space | None = None, observation_space: gymnasium.spaces.Space | None = None, action_space: gymnasium.spaces.Space | None = None, callback: MultiAgentBaseCallback | None = None)

Bases: ABC

Base class for Multi-Agent Reinforcement Learning (MARL) agents.

This class defines the common interface and shared functionalities for all MARL agent implementations in XuanCe. It handles environment interaction, logging, model saving/loading, distributed training setup, and representation construction, while leaving algorithm-specific logic to subclasses.

Subclasses should implement the abstract methods to define:

• how experiences are stored,

• how actions are selected,

• how training and evaluation are performed.

Parameters:

• config (Namespace) – A configuration object that contains hyperparameters and runtime settings, such as algorithm name, environment name, learning rates, device, seed, and logging options.

• envs (Optional[DummyVecMultiAgentEnv | SubprocVecMultiAgentEnv]) – Vectorized multi-agent environments for training. If not provided, environment-related attributes (e.g., observation/action spaces) must be specified explicitly.

• num_agents (Optional[int]) – Number of agents in the environment. Required if envs is None.

• agent_keys (Optional[List[str]]) – Unique identifiers for each agent. Required if envs is None.

• state_space (Optional[Space]) – Global state space used by centralized critics or state-based representations. Required when use_global_state is enabled and envs is None.

• observation_space (Optional[Space]) – Observation space for each agent. Required if envs is None.

• action_space (Optional[Space]) – Action space for each agent. Required if envs is None.

• callback (Optional[MultiAgentBaseCallback]) – A user-defined callback object for injecting custom logic during training and evaluation (e.g., logging, early stopping, debugging).

finish()

abstractmethod get_actions(**kwargs)

load_model(path, model=None)

log_infos(info: dict, x_index: int)

info: (dict) information to be visualized n_steps: current step

log_videos(info: dict, fps: int, x_index: int = 0)

save_model(model_name, model_path=None)

store_experience(*args, **kwargs)

abstractmethod test(**kwargs)

abstractmethod train(**kwargs)

abstractmethod train_epochs(*args, **kwargs)

class xuance.tensorflow.agents.base.agents_marl.RandomAgents(args, envs, device=None)

Bases: object

get_actions(obs_n, episode, test_mode, noise=False)

load_model(model_dir)