---

name: environment-integration description: "Route skrl environment construction through the correct framework wrapper, vectorization and multi-agent boundary, and optional simulator loader without inventing unavailable dependencies." disable-model-invocation: true metadata: disco-role: operating license: MIT

Environment integration

Use this sub-skill when a task starts with an environment name, a Gym/Gymnasium/PettingZoo object, wrap_env, vectorization, observation/state/action spaces, env.device, num_envs, or an external simulator. It produces the common environment interface expected by skrl agents and trainers; it does not choose algorithms, model classes, trainer configuration, IPPO/MAPPO settings, or install/run a simulator.

Route first

1. Identify the environment API and whether it is single-agent or multi-agent. Do not infer from the task name alone.
2. Select the framework that will own tensors/arrays and import its wrapper:
   • PyTorch: from skrl.envs.wrappers.torch import wrap_env
   • JAX: from skrl.envs.wrappers.jax import wrap_env
   • Warp: from skrl.envs.wrappers.warp import wrap_env
3. For Gymnasium, Gym, or a supported registered external environment, create the original environment first, then call wrap_env(original, wrapper=...). Prefer an explicit tag while diagnosing; use "auto" only when the environment's class hierarchy is known to expose the expected package base class.
4. For PettingZoo parallel environments, use wrapper="pettingzoo" and hand the returned multi-agent interface to multi-agent-and-runner. Shimmy compatibility environments follow the API they expose: single-agent Gymnasium-compatible objects use "gymnasium"; multi-agent compatibility objects use "pettingzoo".
5. For Isaac Lab, ManiSkill, or MuJoCo Playground, read external-integrations.md before writing a launcher. These are prerequisite-heavy reference routes, not CPU smoke routes.

The exact public signature in skrl 2.1.0 is:

wrap_env(env, wrapper="auto", verbose=True)

It returns a framework-specific Wrapper or MultiAgentEnvWrapper; an unknown wrapper tag raises ValueError. The accepted tags are auto, gym, gymnasium, isaaclab, isaaclab-single-agent, isaaclab-multi-agent, mani-skill, pettingzoo, and playground in the three public signatures. See the framework caveat for Warp in standard-environments.md.

Minimal single-agent contract

import gymnasium as gym
from skrl.envs.wrappers.torch import wrap_env

env = wrap_env(gym.make("Pendulum-v1"), wrapper="gymnasium")
observation, info = env.reset()
# action must be a framework array/tensor with the flattened batch shape expected by the wrapper
action = ...
observation, reward, terminated, truncated, info = env.step(action)
env.close()

The wrapper normalizes reset() to (observation, info) and step() to (observation, reward, terminated, truncated, info). It converts observations, rewards, and flags to the selected framework and forwards render() and close(). state() returns a converted state when the original environment provides a state/state space; otherwise it returns None (and agents should use observation_space). Do not expect a bare Gym/Gymnasium object to have skrl's tensor/array outputs or device, num_envs, and state behavior.

Inspect before routing downstream

After wrapping, check env.observation_space, env.state_space, env.action_space, env.device, env.num_envs, and (for multi-agent) env.agents, env.possible_agents, env.observation_spaces, and env.action_spaces. Spaces are Gymnasium space objects; the conversion utilities support Box, Discrete, MultiDiscrete, Tuple, and Dict compositions and flatten composite values into a batch-by-feature representation. Unsupported space kinds or values fail during conversion rather than being silently coerced. Use these spaces to configure models, then hand framework details to one of:

• torch-agent-training
• jax-agent-training
• warp-agent-training
• multi-agent-and-runner

For a bounded public CPU check, run scripts/wrap_gymnasium_smoke.py with --help first and then the desired framework. It creates only a Gymnasium Pendulum instance, performs one reset and one step, and closes it; it does not train, download, or import an external simulator. For cross-cutting package, device, or checkpoint failures, also read ../../references/troubleshooting.md.

Non-negotiable limits

• Do not use the Gym wrapper tag for a Gymnasium object, or the Gymnasium tag for an old Gym object, merely because both environments are named similarly.
• Do not run the external loader without its simulator installation, task registration, assets, and (often) GPU/runtime process. No external simulator result is implied by this sub-skill.
• Do not route PettingZoo to a single-agent model/trainer: its reset/step values are per-agent dictionaries and its active agent set can change.
• Do not claim CUDA, simulator, real-world, or asset-backed support from a CPU wrapper smoke.
• Always close the original/wrapped environment, including after a failed one-step check.