Unity ML-Agentsとは？4.1の導入手順と強化学習の流れ・対応バージョン【2026年版】

Unity ML-Agents（ML-Agents Toolkit）は、Unityのシーンを学習環境にして、キャラクターやロボットの行動を強化学習・模倣学習で学ばせるUnity公式のオープンソースです。2026年9月時点の現行版はUnityパッケージ com.unity.ml-agents 4.1.0（2026年7月29日公開）で、Unity 6（6000.0）以上が必須になりました。

Python側の手順は、Python 3.10.12の仮想環境に mlagents==1.1.0 を入れて確認した結果です。公式手順でsetuptools 82以降が入る環境では、mlagents-learn が起動時にエラーになります。その回避策も載せています。

まとめ：Unity ML-Agentsの要点（2026年9月時点）

• 現行版：Unityパッケージは4.1.0（GitHub上の最新リリースはRelease 23＝4.0.0）。4.x系はUnity 6000.0以上に対応します。Unity 2022.3では2.x系に加え、Release 21の3.0.0-exp.1も使用できます。
• Python側：対応はPython 3.10.1〜3.10.12。PyPIの mlagents は1.1.0（2024年10月）が最新のままで、公式の導入手順も mlagents==1.1.0 を指定しています。setuptools<81 を併せて指定すると、setuptools 82以降による起動エラーを回避できます。
• 学習の流れ：Agentクラスに観測・行動・報酬を書く→設定YAMLを用意→mlagents-learn を起動してEditorで再生→results/<run-id>/ に出る.onnxをAgentに割り当てる、の4段階です。
• 推論：学習済みモデルはUnity内の推論ライブラリSentis（パッケージ名 com.unity.ai.inference）で動きます。2025年に一時Inference Engineと呼ばれ、2.4.0から再びSentisの名前に戻っています。
• トレーナー：trainer_type は ppo・sac・poca の3種。迷ったらPPO、協調する複数エージェントならMA-POCAです。
• 制約：学習はEditorとWindows・macOS・LinuxのMonoビルドに限られ、IL2CPPでは学習できません。ML-Agentsのニューラルネットワークによる行動では、公式トレーナーで作成したモデルがサポート対象です。

ML-Agentsの構成：Unityパッケージ・Pythonトレーナー・Sentis

ML-Agentsは3つの部品でできています。Unity側で環境とエージェントを書き、Python側がPyTorchでニューラルネットワークを学習させ、学習済みモデルはUnityに戻してSentisで推論します。UnityとPythonの間はgRPCで通信するため、Python側のパッケージには grpcio が含まれます。

学習のしかたは、ゲームの中で試行錯誤させて報酬を最大化する強化学習が中心です。ほかに、人間が操作した記録（.demoファイル）を手本にする模倣学習（Behavioral Cloning・GAIL）、易しい課題から順に難しくするカリキュラム学習も同じ mlagents-learn から使えます。強化学習そのものの仕組みは強化学習とは？報酬から学ぶ仕組みとQ学習・方策勾配・企業導入の判断を実装目線で解説で扱っています。

ライセンスはApache License 2.0で、商用のゲームやアプリに組み込めます。リポジトリ（Unity-Technologies/ml-agents）は2026年9月29日にも develop ブランチへコミットがあり、開発は続いています。

対応バージョンとリリース履歴：Release 20から4.1.0まで

ML-Agentsは「Release 番号」とパッケージの版番号が別々に付いています。古い解説記事の多くはRelease 18〜21時点のもので、Unityの対応版も推論ライブラリも今とは違います。Unity側とPython側の組み合わせは次のとおりです。

日付はGitHubのリリース一覧の公開日と、Unityパッケージレジストリの登録日です。4.0系は4.0.1（2026年1月）・4.0.2（2月）・4.0.3（4月）と小刻みに更新され、4.1.0ではPython側が gym から後継の gymnasium へ移り、IL2CPPビルドでの Google.Protobuf_Packed.dll の不具合などが直りました。Unity 6.3 LTSの変更点はUnity 6.3 LTS（6000.3）の新機能と6.2からの変更点｜サポート期限・対応OS・移行の注意点にまとめています。

PyPIのmlagentsが1.1.0で止まっている点

Unityパッケージは4.1.0まで進んでいますが、PyPIに上がっている mlagents は2024年10月の1.1.0が最後です。リポジトリのPython側の版番号は 1.2.0.dev0 のままで、Release 23以降はPyPIに公開されていません。4.1のインストール手順もPyPIからは mlagents==1.1.0 を入れるよう書いています。

そのため、4.1.0で入ったgymnasium対応やSAC＋LSTMの修正をPython側でも使いたい場合は、PyPIではなくリポジトリをcloneしてソースから入れる必要があります。Gym／PettingZoo経由でPythonから環境を操作しないなら、PyPIの1.1.0で学習は回ります。

推論ライブラリの名前：Barracuda・Sentis・Inference Engine

学習済みモデルを動かす推論ライブラリは、名前が3回変わっています。Release 21でBarracudaからSentisへ移り、Sentisは2025年5月の2.2.0でInference Engineに改称、2025年10月の2.4.0で再びSentisという表示名に戻りました。パッケージ名は com.unity.ai.inference のままです。4.0.0の変更履歴には「Inference Engine 2.2.1」、4.0.3以降には「Sentis 2.6.1」と書かれていますが、同じライブラリの版違いです。

ML-Agentsのインストール手順：Unity 6とPython 3.10.12

インストールはUnity側とPython側を別々に行います。サンプル環境を使うかどうかで手順が分かれます。

Unity側：Package Managerによるcom.unity.ml-agentsの追加

1. Unity HubでUnity 6000.0以上のEditorを入れ、プロジェクトを作ります。
2. Window > Package Manager を開き、＋ > Add package by name を選びます。
3. com.unity.ml-agents と入力して Install を押します。版を固定したいときは、同じ画面の Version (optional) 欄に 4.1.0 と入力します。

依存関係としてSentis（com.unity.ai.inference 2.6.1）も入ります。4.0.0で拡張パッケージ com.unity.ml-agents.extensions が本体へ統合されたため、Release 22以前の記事にある「extensionsも追加する」手順は不要です。

Python側：condaによるPython 3.10.12とmlagentsの導入

Python側の対応範囲は >=3.10.1,<=3.10.12 です。Python 3.11の環境でpipを使うと No matching distribution found for mlagents==1.1.0 で止まるので、condaなどで3.10.12の環境を別に作ります。

conda create -n mlagents python=3.10.12
conda activate mlagents
python -m pip install mlagents==1.1.0 "setuptools<81"
mlagents-learn --help

setuptools の版指定は公式手順にはありませんが、82以降で発生する起動エラーの回避策として加えています。mlagents 1.1.0は起動時に pkg_resources を読み込みますが、setuptools は82.0.0（2026年2月8日）でこのモジュールを削除しました。指定せずに入れると依存として setuptools 84.0.0が入り、mlagents-learn が ModuleNotFoundError: No module named 'pkg_resources' で起動しません。81.0.0までは pkg_resources が残っていますが、非推奨の警告文が81未満への固定を勧めているので、ここでは <81 にしています。

Windowsでは、CUDA対応のPyTorchを先に入れるよう公式手順が指示しています（pip3 install torch~=2.2.1 --index-url https://download.pytorch.org/whl/cu121）。grpcio のホイールのビルドで失敗したときは、conda install "grpcio=1.48.2" -c conda-forge で先に入れてから mlagents を入れ直します。

Intel版macOSで、uvで作ったPython 3.10.12の仮想環境に mlagents==1.1.0 を入れると、依存44パッケージが解決され、torch 2.2.2・grpcio 1.48.2・numpy 1.23.5・onnx 1.15.0・protobuf 3.20.3・gym 0.26.2が入りました。setuptools を80.10.2に下げたあとは、mlagents-learn が Listening on port 5004. Start training by pressing the Play button in the Unity Editor. と表示して待ち受けます。

uvを使う場合は、uv venv -p 3.10.12 のようにPythonの版を明示します。uvはPyPIの Requires-Python の上限を見ないため、Python 3.11の環境でも mlagents 1.1.0を入れてしまいます。また numpy は1.24未満に固定されているので、新しいnumpyを要求するライブラリと同じ環境に置くと衝突します。学習専用の環境を分けるのが安全です。

サンプル環境：release_23ブランチの取得

3DBallなどのサンプル環境はUnityパッケージに入っていません。使うときはリポジトリをcloneし、Unity Hubで Project フォルダを開きます。

git clone --branch release_23 https://github.com/Unity-Technologies/ml-agents.git
cd ml-agents
python -m pip install ./ml-agents-envs
python -m pip install ./ml-agents

ソースから入れるときは ml-agents-envs を先に入れます。順序を逆にすると、同じ開発版の mlagents_envs が未導入の場合、PyPIに必要な版がないため依存関係の解決に失敗します。4.1.0の変更まで取り込みたい場合は release/4.1.0 ブランチを指定します。

ML-Agentsで学習させる流れ：Agentスクリプトから.onnxまで

ここでは公式チュートリアルの「RollerBall」（球を転がして箱に届かせる課題）を例に、1体のエージェントを学習させる流れを示します。

Agentクラスで実装するメソッド

MonoBehaviour の代わりに Agent を継承し、エピソード開始時の初期化（OnEpisodeBegin）、観測（CollectObservations）、行動と報酬（OnActionReceived）を書きます。Heuristic はキーボードで動作確認するためのものです。

using UnityEngine;
using Unity.MLAgents;
using Unity.MLAgents.Actuators;
using Unity.MLAgents.Sensors;

public class RollerAgent : Agent
{
    public Transform target;
    public float forceMultiplier = 10f;
    Rigidbody rBody;

    public override void Initialize()
    {
        rBody = GetComponent<Rigidbody>();
    }

    public override void OnEpisodeBegin()
    {
        // 床から落ちていたら速度を消して中央へ戻す
        if (transform.localPosition.y < 0)
        {
            rBody.angularVelocity = Vector3.zero;
            rBody.linearVelocity = Vector3.zero;
            transform.localPosition = new Vector3(0, 0.5f, 0);
        }
        target.localPosition = new Vector3(Random.value * 8 - 4, 0.5f, Random.value * 8 - 4);
    }

    public override void CollectObservations(VectorSensor sensor)
    {
        sensor.AddObservation(target.localPosition);     // 3
        sensor.AddObservation(transform.localPosition);  // 3
        sensor.AddObservation(rBody.linearVelocity.x);   // 1
        sensor.AddObservation(rBody.linearVelocity.z);   // 1
    }

    public override void OnActionReceived(ActionBuffers actions)
    {
        var force = new Vector3(actions.ContinuousActions[0], 0, actions.ContinuousActions[1]);
        rBody.AddForce(force * forceMultiplier);

        float distance = Vector3.Distance(transform.localPosition, target.localPosition);
        if (distance < 1.42f)
        {
            SetReward(1.0f);
            EndEpisode();
        }
        else if (transform.localPosition.y < 0)
        {
            EndEpisode();
        }
    }

    public override void Heuristic(in ActionBuffers actionsOut)
    {
        var continuous = actionsOut.ContinuousActions;
        continuous[0] = Input.GetAxis("Horizontal");
        continuous[1] = Input.GetAxis("Vertical");
    }
}

公式チュートリアルのコードは rBody.velocity を使っていますが、Unity 6（6000.0）のスクリプトリファレンスに載っているのは Rigidbody.linearVelocity です。上のコードはこちらに合わせています。また Input.GetAxis は旧Input Managerの機能なので、Player設定の Active Input Handling が新しいInput Systemだけになっているプロジェクトでは例外になります。その場合は Both にするか、ML-Agentsの InputActuatorComponent を使います。

Behavior ParametersとDecision Requesterの設定

このコードは、空のGameObject（TrainingArea）の下に床・ターゲット・球をまとめる構成を前提にしています。床は位置(0, 0, 0)のPlane、ターゲットは位置(3, 0.5, 3)のCube、エージェントは位置(0, 0.5, 0)のSphereです。球にRigidbodyとRollerAgentを付け、target 欄にCubeを割り当てます。

さらに同じ球に Behavior Parameters と Decision Requester を追加します。RollerBallの設定値は次のとおりです。

Space Sizeは CollectObservations で渡した数値の合計と一致させます。Vector3 は3要素なので、位置2つ（6）と速度2成分（2）で8です。渡した数が多ければ超えた分を切り捨て、少なければ0で埋めて、どちらもConsoleに警告を出します。学習は止まらないので、警告を見落とすと誤った観測のまま学習が進みます。学習の前に Behavior Type を Heuristic Only にして再生し、矢印キーで球が動くこと、箱に届くか落ちるとリセットされることを確かめます。

設定YAMLとmlagents-learnの実行

ハイパーパラメータは設定YAMLに書きます。以下の内容を、コマンドを実行するディレクトリ直下のconfigフォルダにrollerball_config.yamlという名前で保存してください。behaviors の直下のキーがBehavior Nameです。

behaviors:
  RollerBall:
    trainer_type: ppo
    hyperparameters:
      batch_size: 10
      buffer_size: 100
      learning_rate: 3.0e-4
      beta: 5.0e-4
      epsilon: 0.2
      lambd: 0.99
      num_epoch: 3
      learning_rate_schedule: linear
    network_settings:
      normalize: false
      hidden_units: 128
      num_layers: 2
    reward_signals:
      extrinsic:
        gamma: 0.99
        strength: 1.0
    max_steps: 500000
    time_horizon: 64
    summary_freq: 10000

ターミナルで mlagents-learn を起動し、待ち受けのメッセージが出たら、Behavior ParametersのBehavior TypeをHeuristic OnlyからDefaultへ戻し、Editorの再生ボタンを押します。

mlagents-learn config/rollerball_config.yaml --run-id=RollerBall
# 別のターミナルで同じ作業ディレクトリを開いて実行
conda activate mlagents
tensorboard --logdir results

成果物は results/RollerBall/ に出ます。主なオプションは次の4つです。

• --resume：同じrun-idの学習を途中から再開する
• --force：同じrun-idの成果物を上書きして最初からやり直す
• --num-envs=2：ビルドした環境を2つ並列に起動する（--env と併用）
• --no-graphics：画面を描画しない。サーバーでの学習向けで、カメラ観測は使えない

TensorBoardでは Cumulative Reward を見ます。RollerBallで得られる報酬の最大は1.0なので、この値が1.0に近づけば課題を解けています。1つのシーンに学習エリアを複数並べる（プレハブ化して複製する、または TrainingAreaReplicator を使う）と、同じ時間で集まる経験が増えて学習が速く進みます。

学習済みモデル（.onnx）で動かすときの確認点

学習を止めると results/RollerBall/RollerBall.onnx が書き出されます。これをProjectウィンドウに入れ、Behavior Parametersの Model 欄に割り当てれば、Sentisが推論してエージェントが動きます。モデルを割り当てたのに学習前と同じ動きになるときは、次の3点を確認します。

• Behavior TypeがDefaultのまま mlagents-learn が動いている：Defaultは、Pythonと接続していれば学習側の指示を優先し、接続が無ければモデル、モデルも無ければHeuristicを使います。モデルの動作を見るときは mlagents-learn を止めるか、Inference Only にします。
• Unityのウィンドウを閉じて学習を終えた：公式手順は、Saved Model と表示されたあと、学習プロセスがウィンドウを閉じるのを待つか、ターミナルで Ctrl+C を押して止めるよう求めています。ウィンドウを手で閉じると.onnxが書き出されません。
• 観測や行動の数を学習後に変えた：Space SizeやContinuous Actionsの数を変えると、学習済みモデルの入出力と合わなくなります。変えたら学習し直します。

Inference Onlyにしてモデルを割り当てていないと「Can't use Behavior Type InferenceOnly without a model.」という例外になります。推論デバイスは Burst（CPU）・Compute Shader・Pixel Shader から選べます。公式ドキュメントは、ML-Agentsで作る一般的なモデルならCPUのBurstの方が速く、GPUが有利なのはResNetの画像エンコーダーを使う場合や、カメラ観測を持つエージェントが多い場合だとしています。

ML-Agentsのトレーナーの選び方：PPO・SAC・MA-POCAと模倣学習

設定YAMLの trainer_type に書けるのは ppo（既定）・sac・poca の3つです。模倣学習や好奇心による探索は、トレーナーではなく reward_signals や behavioral_cloning の設定として追加します。

PPOは集めた経験をnum_epochで指定した回数だけ学習に使い、更新後に破棄します。並列環境で経験を集めることで、次の更新に必要なデータを確保しやすくなります。SACは過去の経験をバッファに貯めて使い回すので、1ステップの計算が重く経験を集めにくい環境でサンプル効率が上がります。バッチサイズの目安も公式は分けていて、連続行動のPPOは512〜5120、連続行動のSACは128〜1024、離散行動は32〜512です。

サッカーのように味方と協力する課題では、各エージェントを独立にPPOで学習させると、チームへの貢献をうまく評価できません。MA-POCAはグループ全体を評価するcriticを1つ持ち、チームにまとめて報酬（SimpleMultiAgentGroup）を与えて学習します。エピソードの途中で退場したエージェントも、その後チームが勝ったかどうかから自分の行動の貢献を学ぶため、自分が倒れてでもチームを勝たせる行動を覚えられます。PPOの目的関数とLLMの選好最適化との違いはDPOとPPOの違いとは？RLHFの選好最適化を仕組み・性能・実装で比較で比べています。

同梱のサンプル環境17種と最初に動かすもの

リポジトリの Project には17のサンプル環境があり、それぞれ学習済みの.onnxと設定YAML（config/ppo/ など）が付いています。

• 単体・入門：Basic、3DBall、GridWorld、Push Block、Wall Jump、Hallway、Pyramids
• 身体制御：Crawler、Worm、Walker
• 複数エージェント：Food Collector、Soccer Twos、Strikers Vs. Goalie、Cooperative Push Block、Dungeon Escape
• その他：Match 3、Sorter

最初は3DBall（頭の上のボールを落とさないよう傾ける課題）から動かします。公式の手順も3DBallで、mlagents-learn config/ppo/3DBall.yaml --run-id=first3DBallRun で学習が始まります。1シーンに同じ設定のエージェントが12体並び、ボールが頭に乗っている間は1ステップごとに+0.1、落とすと-1.0の報酬なので、Python側とUnity側がつながって学習が進んでいるかをTensorBoardで確かめやすい課題です。Wall Jumpはカリキュラム学習（WallJump_curriculum.yaml）、Soccer TwosとStrikers Vs. Goalieはセルフプレイ、Cooperative Push BlockとDungeon EscapeはMA-POCAの例として読むと、設定の違いがわかります。

ML-Agentsが向かない場面と制約

ML-Agentsは「Unityで作ったゲームやシミュレーションの中でエージェントを学習させ、そのままゲームに組み込む」用途に絞った道具です。次の条件に当たるなら、別の手段を先に検討します。

学習環境：IL2CPPビルドとモバイル実機の制約

4.1のパッケージの制約によると、学習できるのはEditorと、Windows・macOS・LinuxのスタンドアロンビルドでスクリプトバックエンドがMonoの場合だけです。IL2CPPでは学習できず、学習が動いていない環境は推論モードになります。モバイルやコンソールで動かせるのは、学習済みモデルの推論だけです。

外部フレームワークの学習済みモデル：サポート範囲

ML-AgentsのAgentで公式にサポートされるのは、Unityのトレーナーで作ったモデルです。テンソル名や定数の約束事に従う必要があり、公式は「外部で学習したモデルを動かすならML-Agentsを通さずSentisを直接使う」よう案内しています。Unity外での推論もサポート対象外です。

物理シミュレーション：100倍速の上限とUpdateとの同期制約

ゲーム物理の加速は実時間の100倍までです。また、エージェントの意思決定は FixedUpdate() に同期して進むため、Update() に書いたゲームの処理とはずれることがあります。自分で進めたい場合は Academy.Instance.DisableAutomaticStepping() を呼び、Academy.Instance.EnvironmentStep() を手動で呼びます。

ゲームではなくロボットの制御則を、物理の再現度を重視して学習させたいなら、ロボティクス向けに作られたNVIDIAのシミュレーターも比較対象になります。概要はIsaac Simの基本概要とNVIDIAロボティクス開発で果たす役割で説明しています。Unity内のNPCや敵AIを報酬に基づいて学習させたい場合は、Agent APIとPythonトレーナーを備えるML-Agentsが候補になります。ChatGPT APIやNavMeshAgentも含めたゲーム内AIの作り方の比較はUnityでAIを実装する方法｜ChatGPT API連携・NavMeshAgent・ML-Agentsで作るゲーム内AIにあります。

ML-Agentsの導入・学習時のエラーと対処

公式FAQと4.x系の変更履歴に載っている、導入直後によく出るエラーです。

• The Communicator was unable to connect：シーンにAgentが無い、macOSのファイアウォールが通信を止めている、環境変数 HTTP_PROXY・HTTPS_PROXY が設定されている、のいずれかが多い原因です。画面の無いサーバーでは --no-graphics を付けます。
• Couldn't launch new environment because communication port ... is still in use：前の学習プロセスがポートを握っています。プロセスを終了するか、Pythonから起動する場合は UnityEnvironment(file_name=..., worker_id=1) のように worker_id を変えます。
• Mean reward : nan：エピソードが1回も終わっていないため平均が計算できていません。EndEpisode() を呼ぶ条件か、Agentの Max Step を設定します。
• Play modeを抜けるとEditorが落ちる：4.0.1と4.1.0で修正された既知の不具合です。4.0.0を使っているなら4.1.0へ上げます。

よくある質問

ML-Agentsは無料ですか？商用のゲームに使えますか？

無料です。ライセンスはApache License 2.0で、商用のゲームやアプリに組み込めます。学習に使うPyTorchなどの依存ライブラリも、それぞれのオープンソースライセンスで配布されています。

ML-AgentsはUnity 2022で使えますか？

4.x系はUnity 6000.0以上、正式版3.0.0はUnity 2023.2以上が必要です。Unity 2022.3ではRelease 21の3.0.0-exp.1も使用できます。2.x系（Release 20以前）を選ぶと、推論ライブラリが旧Barracudaになり、以後の修正も入りません。新しく始めるならUnity 6にそろえる方が手間は少なくて済みます。

Python 3.11や3.12で動きますか？

対応していません。mlagents 1.1.0の対応範囲は3.10.1〜3.10.12です。3.10.12の環境を別に作ってください（uvは版の上限を見ずに入れてしまう点に注意）。

ML-Agentsは開発が終わったのですか？

終わっていません。Unityパッケージは2026年7月に4.1.0が出ており、GitHubのリポジトリにも2026年9月までコミットがあります。止まっているのはPyPIのPythonパッケージ（1.1.0）の公開だけです。

学習にGPUは必要ですか？

必須ではありません。RollerBallや3DBallのように観測が数値だけの環境はCPUで学習できます。GPUの効果が大きいのは、カメラ画像を観測に使う場合です。

関連記事

• 強化学習とは？報酬から学ぶ仕組みとQ学習・方策勾配・企業導入の判断を実装目線で解説
• UnityでAIを実装する方法｜ChatGPT API連携・NavMeshAgent・ML-Agentsで作るゲーム内AI
• Unity 6.3 LTS（6000.3）の新機能と6.2からの変更点｜サポート期限・対応OS・移行の注意点
• DPOとPPOの違いとは？RLHFの選好最適化を仕組み・性能・実装で比較
• Isaac Simの基本概要とNVIDIAロボティクス開発で果たす役割