ml-agents Documentation

The Unity Machine Learning Agents Toolkit (ML-Agents) is an open-source project that enables games and simulations to serve as environments for training...

19,622 stars C# C# 1 file · ~5,591 tokens #deep-learning#deep-reinforcement-learning#machine-learning#neural-networks#reinforcement-learning#unity#unity3d
RAW Doc

Docker & Self-Hosted Deployment Verified OCI

Deploy ml-agents on any server, homelab, or cloud container platform.

1-Click Terminal Command
bash (docker run) 
docker run -d --name ml-agents --restart always unity-technologies/ml-agents:latest

File: Readme.md

Unity ML-Agents Toolkit

(latest release) (all releases)

The Unity Machine Learning Agents Toolkit (ML-Agents) is an open-source project that enables games and simulations to serve as environments for training intelligent agents. We provide implementations (based on PyTorch) of state-of-the-art algorithms to enable game developers and hobbyists to easily train intelligent agents for 2D, 3D and VR/AR games. Researchers can also use the provided simple-to-use Python API to train Agents using reinforcement learning, imitation learning, neuroevolution, or any other methods. These trained agents can be used for multiple purposes, including controlling NPC behavior (in a variety of settings such as multi-agent and adversarial), automated testing of game builds and evaluating different game design decisions pre-release. The ML-Agents Toolkit is mutually beneficial for both game developers and AI researchers as it provides a central platform where advances in AI can be evaluated on Unity’s rich environments and then made accessible to the wider research and game developer communities.

Features

  • 17+ example Unity environments
  • Support for multiple environment configurations and training scenarios
  • Flexible Unity SDK that can be integrated into your game or custom Unity scene
  • Support for training single-agent, multi-agent cooperative, and multi-agent competitive scenarios via several Deep Reinforcement Learning algorithms (PPO, SAC, MA-POCA, self-play).
  • Support for learning from demonstrations through two Imitation Learning algorithms (BC and GAIL).
  • Quickly and easily add your own custom training algorithm and/or components.
  • Easily definable Curriculum Learning scenarios for complex tasks
  • Train robust agents using environment randomization
  • Flexible agent control with On Demand Decision Making
  • Train using multiple concurrent Unity environment instances
  • Utilizes the Inference Engine to provide native cross-platform support
  • Unity environment control from Python
  • Wrap Unity learning environments as a gym environment
  • Wrap Unity learning environments as a PettingZoo environment

Releases & Documentation

⚠️ Documentation Migration Notice
We have moved to Unity Package documentation as the primary developer documentation and have deprecated the maintenance of web docs. Please use the Unity Package documentation for the most up-to-date information.

The table below shows our latest release, including our develop branch which is under active development and may be unstable. A few helpful guidelines:

  • The Versioning page overviews how we manage our GitHub releases and the versioning process for each of the ML-Agents components.
  • The Releases page contains details of the changes between releases.
  • The Migration page contains details on how to upgrade from earlier releases of the ML-Agents Toolkit.
  • The com.unity.ml-agents package is verified for Unity 2020.1 and later. Verified packages releases are numbered 1.0.x.
Version Release Date Source Documentation Download Python Package Unity Package
Release 23 August 28, 2025 source docs download 1.1.0 4.0.0
develop (unstable) -- source docs download -- --

If you are a researcher interested in a discussion of Unity as an AI platform, see a pre-print of our reference paper on Unity and the ML-Agents Toolkit.

If you use Unity or the ML-Agents Toolkit to conduct research, we ask that you cite the following paper as a reference:

text
@article{juliani2020,
  title={Unity: A general platform for intelligent agents},
  author={Juliani, Arthur and Berges, Vincent-Pierre and Teng, Ervin and Cohen, Andrew and Harper, Jonathan and Elion, Chris and Goy, Chris and Gao, Yuan and Henry, Hunter and Mattar, Marwan and Lange, Danny},
  journal={arXiv preprint arXiv:1809.02627},
  url={https://arxiv.org/pdf/1809.02627.pdf},
  year={2020}
}

Additionally, if you use the MA-POCA trainer in your research, we ask that you cite the following paper as a reference:

text
@article{cohen2022,
  title={On the Use and Misuse of Absorbing States in Multi-agent Reinforcement Learning},
  author={Cohen, Andrew and Teng, Ervin and Berges, Vincent-Pierre and Dong, Ruo-Ping and Henry, Hunter and Mattar, Marwan and Zook, Alexander and Ganguly, Sujoy},
  journal={RL in Games Workshop AAAI 2022},
  url={http://aaai-rlg.mlanctot.info/papers/AAAI22-RLG_paper_32.pdf},
  year={2022}
}

Additional Resources

Community and Feedback

The ML-Agents Toolkit is an open-source project and we encourage and welcome contributions. If you wish to contribute, be sure to review our contribution guidelines and code of conduct.

For problems with the installation and setup of the ML-Agents Toolkit, or discussions about how to best setup or train your agents, please create a new thread on the Unity ML-Agents discussion forum. Be sure to include as many details as possible to help others assist you effectively. If you run into any other problems using the ML-Agents Toolkit or have a specific feature request, please submit a GitHub issue.

Please tell us which samples you would like to see shipped with the ML-Agents Unity package by replying to this discussion thread.

Privacy

In order to improve the developer experience for Unity ML-Agents Toolkit, we have added in-editor analytics. Please refer to "Information that is passively collected by Unity" in the Unity Privacy Policy.

File: docs/Readme.md

Unity ML-Agents Toolkit

(latest release)
(all releases)

The Unity Machine Learning Agents Toolkit (ML-Agents) is an open-source
project that enables games and simulations to serve as environments for
training intelligent agents. We provide implementations (based on PyTorch)
of state-of-the-art algorithms to enable game developers and hobbyists to easily
train intelligent agents for 2D, 3D and VR/AR games. Researchers can also use the
provided simple-to-use Python API to train Agents using reinforcement learning,
imitation learning, neuroevolution, or any other methods. These trained agents can be
used for multiple purposes, including controlling NPC behavior (in a variety of
settings such as multi-agent and adversarial), automated testing of game builds
and evaluating different game design decisions pre-release. The ML-Agents
Toolkit is mutually beneficial for both game developers and AI researchers as it
provides a central platform where advances in AI can be evaluated on Unity’s
rich environments and then made accessible to the wider research and game
developer communities.

Features

  • 17+ example Unity environments
  • Support for multiple environment configurations and training scenarios
  • Flexible Unity SDK that can be integrated into your game or custom Unity scene
  • Support for training single-agent, multi-agent cooperative, and multi-agent
    competitive scenarios via several Deep Reinforcement Learning algorithms (PPO, SAC, MA-POCA, self-play).
  • Support for learning from demonstrations through two Imitation Learning algorithms (BC and GAIL).
  • Quickly and easily add your own custom training algorithm and/or components.
  • Easily definable Curriculum Learning scenarios for complex tasks
  • Train robust agents using environment randomization
  • Flexible agent control with On Demand Decision Making
  • Train using multiple concurrent Unity environment instances
  • Utilizes the Unity Inference Engine to
    provide native cross-platform support
  • Unity environment control from Python
  • Wrap Unity learning environments as a gym environment
  • Wrap Unity learning environments as a PettingZoo environment

See our ML-Agents Overview page for detailed
descriptions of all these features. Or go straight to our web docs.

Releases & Documentation

Our latest, stable release is Release 20. Click
here
to get started with the latest release of ML-Agents.

You can also check out our new web docs!

The table below lists all our releases, including our main branch which is
under active development and may be unstable. A few helpful guidelines:

  • The Versioning page overviews how we manage our GitHub
    releases and the versioning process for each of the ML-Agents components.
  • The Releases page
    contains details of the changes between releases.
  • The Migration page contains details on how to upgrade
    from earlier releases of the ML-Agents Toolkit.
  • The Documentation links in the table below include installation and usage
    instructions specific to each release. Remember to always use the
    documentation that corresponds to the release version you're using.
  • The com.unity.ml-agents package is verified
    for Unity 2020.1 and later. Verified packages releases are numbered 1.0.x.
Version Release Date Source Documentation Download Python Package Unity Package
develop (unstable) -- source docs download -- --
Release 21 October 9, 2023 source docs download 1.0.0 3.0.0

If you are a researcher interested in a discussion of Unity as an AI platform,
see a pre-print of our
reference paper on Unity and the ML-Agents Toolkit.

If you use Unity or the ML-Agents Toolkit to conduct research, we ask that you
cite the following paper as a reference:

text
@article{juliani2020,
  title={Unity: A general platform for intelligent agents},
  author={Juliani, Arthur and Berges, Vincent-Pierre and Teng, Ervin and Cohen, Andrew and Harper, Jonathan and Elion, Chris and Goy, Chris and Gao, Yuan and Henry, Hunter and Mattar, Marwan and Lange, Danny},
  journal={arXiv preprint arXiv:1809.02627},
  url={https://arxiv.org/pdf/1809.02627.pdf},
  year={2020}
}

Additionally, if you use the MA-POCA trainer in your research, we ask that you
cite the following paper as a reference:

text
@article{cohen2022,
  title={On the Use and Misuse of Absorbing States in Multi-agent Reinforcement Learning},
  author={Cohen, Andrew and Teng, Ervin and Berges, Vincent-Pierre and Dong, Ruo-Ping and Henry, Hunter and Mattar, Marwan and Zook, Alexander and Ganguly, Sujoy},
  journal={RL in Games Workshop AAAI 2022},
  url={http://aaai-rlg.mlanctot.info/papers/AAAI22-RLG_paper_32.pdf},
  year={2022}
}

Additional Resources

We have a Unity Learn course,
ML-Agents: Hummingbirds,
that provides a gentle introduction to Unity and the ML-Agents Toolkit.

We've also partnered with
CodeMonkeyUnity to create a
series of tutorial videos
on how to implement and use the ML-Agents Toolkit.

We have also published a series of blog posts that are relevant for ML-Agents:

More from Unity

Community and Feedback

The ML-Agents Toolkit is an open-source project and we encourage and welcome
contributions. If you wish to contribute, be sure to review our
contribution guidelines and
code of conduct.

For problems with the installation and setup of the ML-Agents Toolkit, or
discussions about how to best setup or train your agents, please create a new
thread on the
Unity ML-Agents forum and make
sure to include as much detail as possible. If you run into any other problems
using the ML-Agents Toolkit or have a specific feature request, please
submit a GitHub issue.

Please tell us which samples you would like to see shipped with the ML-Agents Unity
package by replying to
this forum thread.

Your opinion matters a great deal to us. Only by hearing your thoughts on the
Unity ML-Agents Toolkit can we continue to improve and grow. Please take a few
minutes to
let us know about it.

For any other questions or feedback, connect directly with the ML-Agents team at
[email protected].

Privacy

In order to improve the developer experience for Unity ML-Agents Toolkit, we have added in-editor analytics.
Please refer to "Information that is passively collected by Unity" in the
Unity Privacy Policy.

Explore Related Technologies & Topics

View All 9,111+ Repositories →

Discover similar high-velocity repositories, agent skills, and OpenAPI specifications across the ecosystem.

#deep-learning Browse deep-learning catalog → #deep-reinforcement-learning Browse deep-reinforcement-learning catalog → #machine-learning Browse machine-learning catalog → #neural-networks Browse neural-networks catalog → #reinforcement-learning Browse reinforcement-learning catalog → #unity Browse unity catalog → ⚡ MCP Servers Model Context Protocol → 🧠 Agent Skills Prompt & rule files → 🔌 OpenAPI Specs REST & Swagger schemas →