Communication protocol versioning (#3535)

com.unity.ml-agents/Runtime/Academy.cs

         "docs/Learning-Environment-Design.md")]
     public class Academy : IDisposable
     {
-        const string k_ApiVersion = "API-15-dev0";
+        /// <summary>
+        /// Communication protocol version.
+        /// When connecting to python, this must match UnityEnvironment.API_VERSION.
+        /// Currently we require strict equality between the communication protocol
+        /// on each side, although we may allow some flexibility in the future.
+        /// This should be incremented whenever a change is made to the communication protocol.
+        /// </summary>
+        const string k_ApiVersion = "0.15.0";
+
+        /// <summary>
+        /// Unity package version of com.unity.ml-agents.
+        /// This must match the version string in package.json and is checked in a unit test.
+        /// </summary>
+        internal const string k_PackageVersion = "0.14.1-preview";
+
-        internal const string k_portCommandLineFlag = "--mlagents-port";
+
+        const string k_portCommandLineFlag = "--mlagents-port";
 
         // Lazy initializer pattern, see https://csharpindepth.com/articles/singleton#lazy
         static Lazy<Academy> s_Lazy = new Lazy<Academy>(() => new Academy());
                     var unityRlInitParameters = Communicator.Initialize(
                         new CommunicatorInitParameters
                         {
-                            version = k_ApiVersion,
+                            unityCommunicationVersion = k_ApiVersion,
+                            unityPackageVersion = k_PackageVersion,
                             name = "AcademySingleton",
                         });
                     UnityEngine.Random.InitState(unityRlInitParameters.seed);
         public void Dispose()
         {
             DisableAutomaticStepping();
+
             // Signal to listeners that the academy is being destroyed now
             DestroyAction?.Invoke();
 
                 {
                     mr.Dispose();
                 }
+
                 m_ModelRunners = null;
             }
 

com.unity.ml-agents/Runtime/Communicator/GrpcExtensions.cs

         {
             return new UnityRLInitParameters
             {
-                seed = inputProto.Seed
+                seed = inputProto.Seed,
+                pythonLibraryVersion = inputProto.PackageVersion,
+                pythonCommunicationVersion = inputProto.CommunicationVersion,
             };
         }
 

com.unity.ml-agents/Runtime/Communicator/ICommunicator.cs

         /// Port to listen for connections on.
         /// </summary>
         public int port;
+
+
-        public string version;
+        public string unityPackageVersion;
+
+        /// <summary>
+        /// The version of the communication API.
+        /// </summary>
+        public string unityCommunicationVersion;
     }
     internal struct UnityRLInitParameters
     {
         public int seed;
+
+        /// <summary>
+        /// The library version of the python process.
+        /// </summary>
+        public string pythonLibraryVersion;
+
+        /// <summary>
+        /// The version of the communication API that python is using.
+        /// </summary>
+        public string pythonCommunicationVersion;
     }
     internal struct UnityRLInputParameters
     {

com.unity.ml-agents/Runtime/Communicator/RpcCommunicator.cs

             var academyParameters = new UnityRLInitializationOutputProto
             {
                 Name = initParameters.name,
-                Version = initParameters.version
+                PackageVersion = initParameters.unityPackageVersion,
+                CommunicationVersion = initParameters.unityCommunicationVersion
             };
 
             UnityInputProto input;
                         RlInitializationOutput = academyParameters
                     },
                     out input);
+
+                // Initialization succeeded part-way. The most likely cause is a mismatch between the communicator
+                // API strings, so log an explicit warning if that's the case.
+                if (initializationInput != null && input == null)
+                {
+                    var pythonCommunicationVersion = initializationInput.RlInitializationInput.CommunicationVersion;
+                    var pythonPackageVersion = initializationInput.RlInitializationInput.PackageVersion;
+                    if (pythonCommunicationVersion != initParameters.unityCommunicationVersion)
+                    {
+                        Debug.LogWarningFormat(
+                            "Communication protocol between python ({0}) and Unity ({1}) don't match. " +
+                            "Python library version: {2}.",
+                            pythonCommunicationVersion, initParameters.unityCommunicationVersion,
+                            pythonPackageVersion
+                            );
+                    }
+                    else
+                    {
+                        Debug.LogWarningFormat(
+                            "Unknown communication error between Python. Python communication protocol: {0}, " +
+                            "Python library version: {1}.",
+                            pythonCommunicationVersion,
+                            pythonPackageVersion
+                        );
+                    }
+
+                    throw new UnityAgentsException("ICommunicator.Initialize() failed.");
+                }
             }
             catch
             {

com.unity.ml-agents/Runtime/Grpc/CommunicatorObjects/UnityRlInitializationInput.cs

           string.Concat(
             "CkZtbGFnZW50c19lbnZzL2NvbW11bmljYXRvcl9vYmplY3RzL3VuaXR5X3Js",
             "X2luaXRpYWxpemF0aW9uX2lucHV0LnByb3RvEhRjb21tdW5pY2F0b3Jfb2Jq",
-            "ZWN0cyIvCh9Vbml0eVJMSW5pdGlhbGl6YXRpb25JbnB1dFByb3RvEgwKBHNl",
-            "ZWQYASABKAVCH6oCHE1MQWdlbnRzLkNvbW11bmljYXRvck9iamVjdHNiBnBy",
-            "b3RvMw=="));
+            "ZWN0cyJnCh9Vbml0eVJMSW5pdGlhbGl6YXRpb25JbnB1dFByb3RvEgwKBHNl",
+            "ZWQYASABKAUSHQoVY29tbXVuaWNhdGlvbl92ZXJzaW9uGAIgASgJEhcKD3Bh",
+            "Y2thZ2VfdmVyc2lvbhgDIAEoCUIfqgIcTUxBZ2VudHMuQ29tbXVuaWNhdG9y",
+            "T2JqZWN0c2IGcHJvdG8z"));
-            new pbr::GeneratedClrTypeInfo(typeof(global::MLAgents.CommunicatorObjects.UnityRLInitializationInputProto), global::MLAgents.CommunicatorObjects.UnityRLInitializationInputProto.Parser, new[]{ "Seed" }, null, null, null)
+            new pbr::GeneratedClrTypeInfo(typeof(global::MLAgents.CommunicatorObjects.UnityRLInitializationInputProto), global::MLAgents.CommunicatorObjects.UnityRLInitializationInputProto.Parser, new[]{ "Seed", "CommunicationVersion", "PackageVersion" }, null, null, null)
           }));
     }
     #endregion
+  /// <summary>
+  /// The initializaiton message - this is typically sent from the Python trainer to the C# environment.
+  /// </summary>
   internal sealed partial class UnityRLInitializationInputProto : pb::IMessage<UnityRLInitializationInputProto> {
     private static readonly pb::MessageParser<UnityRLInitializationInputProto> _parser = new pb::MessageParser<UnityRLInitializationInputProto>(() => new UnityRLInitializationInputProto());
     private pb::UnknownFieldSet _unknownFields;
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute]
     public UnityRLInitializationInputProto(UnityRLInitializationInputProto other) : this() {
       seed_ = other.seed_;
+      communicationVersion_ = other.communicationVersion_;
+      packageVersion_ = other.packageVersion_;
       _unknownFields = pb::UnknownFieldSet.Clone(other._unknownFields);
     }
 
       }
     }
 
+    /// <summary>Field number for the "communication_version" field.</summary>
+    public const int CommunicationVersionFieldNumber = 2;
+    private string communicationVersion_ = "";
+    /// <summary>
+    /// Communication protocol version that the initiating side (typically the Python trainer) is using.
+    /// </summary>
+    [global::System.Diagnostics.DebuggerNonUserCodeAttribute]
+    public string CommunicationVersion {
+      get { return communicationVersion_; }
+      set {
+        communicationVersion_ = pb::ProtoPreconditions.CheckNotNull(value, "value");
+      }
+    }
+
+    /// <summary>Field number for the "package_version" field.</summary>
+    public const int PackageVersionFieldNumber = 3;
+    private string packageVersion_ = "";
+    /// <summary>
+    /// Package/library version that the initiating side (typically the Python trainer) is using.
+    /// </summary>
+    [global::System.Diagnostics.DebuggerNonUserCodeAttribute]
+    public string PackageVersion {
+      get { return packageVersion_; }
+      set {
+        packageVersion_ = pb::ProtoPreconditions.CheckNotNull(value, "value");
+      }
+    }
+
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute]
     public override bool Equals(object other) {
       return Equals(other as UnityRLInitializationInputProto);
         return true;
       }
       if (Seed != other.Seed) return false;
+      if (CommunicationVersion != other.CommunicationVersion) return false;
+      if (PackageVersion != other.PackageVersion) return false;
       return Equals(_unknownFields, other._unknownFields);
     }
 
       if (Seed != 0) hash ^= Seed.GetHashCode();
+      if (CommunicationVersion.Length != 0) hash ^= CommunicationVersion.GetHashCode();
+      if (PackageVersion.Length != 0) hash ^= PackageVersion.GetHashCode();
       if (_unknownFields != null) {
         hash ^= _unknownFields.GetHashCode();
       }
         output.WriteRawTag(8);
         output.WriteInt32(Seed);
       }
+      if (CommunicationVersion.Length != 0) {
+        output.WriteRawTag(18);
+        output.WriteString(CommunicationVersion);
+      }
+      if (PackageVersion.Length != 0) {
+        output.WriteRawTag(26);
+        output.WriteString(PackageVersion);
+      }
       if (_unknownFields != null) {
         _unknownFields.WriteTo(output);
       }
       if (Seed != 0) {
         size += 1 + pb::CodedOutputStream.ComputeInt32Size(Seed);
       }
+      if (CommunicationVersion.Length != 0) {
+        size += 1 + pb::CodedOutputStream.ComputeStringSize(CommunicationVersion);
+      }
+      if (PackageVersion.Length != 0) {
+        size += 1 + pb::CodedOutputStream.ComputeStringSize(PackageVersion);
+      }
       if (_unknownFields != null) {
         size += _unknownFields.CalculateSize();
       }
       if (other.Seed != 0) {
         Seed = other.Seed;
       }
+      if (other.CommunicationVersion.Length != 0) {
+        CommunicationVersion = other.CommunicationVersion;
+      }
+      if (other.PackageVersion.Length != 0) {
+        PackageVersion = other.PackageVersion;
+      }
       _unknownFields = pb::UnknownFieldSet.MergeFrom(_unknownFields, other._unknownFields);
     }
 
             break;
           case 8: {
             Seed = input.ReadInt32();
+            break;
+          }
+          case 18: {
+            CommunicationVersion = input.ReadString();
+            break;
+          }
+          case 26: {
+            PackageVersion = input.ReadString();
             break;
           }
         }

com.unity.ml-agents/Runtime/Grpc/CommunicatorObjects/UnityRlInitializationOutput.cs

             "CkdtbGFnZW50c19lbnZzL2NvbW11bmljYXRvcl9vYmplY3RzL3VuaXR5X3Js",
             "X2luaXRpYWxpemF0aW9uX291dHB1dC5wcm90bxIUY29tbXVuaWNhdG9yX29i",
             "amVjdHMaOW1sYWdlbnRzX2VudnMvY29tbXVuaWNhdG9yX29iamVjdHMvYnJh",
-            "aW5fcGFyYW1ldGVycy5wcm90byKfAQogVW5pdHlSTEluaXRpYWxpemF0aW9u",
-            "T3V0cHV0UHJvdG8SDAoEbmFtZRgBIAEoCRIPCgd2ZXJzaW9uGAIgASgJEhAK",
-            "CGxvZ19wYXRoGAMgASgJEkQKEGJyYWluX3BhcmFtZXRlcnMYBSADKAsyKi5j",
-            "b21tdW5pY2F0b3Jfb2JqZWN0cy5CcmFpblBhcmFtZXRlcnNQcm90b0oECAYQ",
-            "B0IfqgIcTUxBZ2VudHMuQ29tbXVuaWNhdG9yT2JqZWN0c2IGcHJvdG8z"));
+            "aW5fcGFyYW1ldGVycy5wcm90byLGAQogVW5pdHlSTEluaXRpYWxpemF0aW9u",
+            "T3V0cHV0UHJvdG8SDAoEbmFtZRgBIAEoCRIdChVjb21tdW5pY2F0aW9uX3Zl",
+            "cnNpb24YAiABKAkSEAoIbG9nX3BhdGgYAyABKAkSRAoQYnJhaW5fcGFyYW1l",
+            "dGVycxgFIAMoCzIqLmNvbW11bmljYXRvcl9vYmplY3RzLkJyYWluUGFyYW1l",
+            "dGVyc1Byb3RvEhcKD3BhY2thZ2VfdmVyc2lvbhgHIAEoCUoECAYQB0IfqgIc",
+            "TUxBZ2VudHMuQ29tbXVuaWNhdG9yT2JqZWN0c2IGcHJvdG8z"));
-            new pbr::GeneratedClrTypeInfo(typeof(global::MLAgents.CommunicatorObjects.UnityRLInitializationOutputProto), global::MLAgents.CommunicatorObjects.UnityRLInitializationOutputProto.Parser, new[]{ "Name", "Version", "LogPath", "BrainParameters" }, null, null, null)
+            new pbr::GeneratedClrTypeInfo(typeof(global::MLAgents.CommunicatorObjects.UnityRLInitializationOutputProto), global::MLAgents.CommunicatorObjects.UnityRLInitializationOutputProto.Parser, new[]{ "Name", "CommunicationVersion", "LogPath", "BrainParameters", "PackageVersion" }, null, null, null)
           }));
     }
     #endregion
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute]
     public UnityRLInitializationOutputProto(UnityRLInitializationOutputProto other) : this() {
       name_ = other.name_;
-      version_ = other.version_;
+      communicationVersion_ = other.communicationVersion_;
+      packageVersion_ = other.packageVersion_;
       _unknownFields = pb::UnknownFieldSet.Clone(other._unknownFields);
     }
 
       }
     }
 
-    /// <summary>Field number for the "version" field.</summary>
-    public const int VersionFieldNumber = 2;
-    private string version_ = "";
+    /// <summary>Field number for the "communication_version" field.</summary>
+    public const int CommunicationVersionFieldNumber = 2;
+    private string communicationVersion_ = "";
+    /// <summary>
+    /// Communication protocol version that the responding side (typically the C# environment) is using.
+    /// </summary>
-    public string Version {
-      get { return version_; }
+    public string CommunicationVersion {
+      get { return communicationVersion_; }
-        version_ = pb::ProtoPreconditions.CheckNotNull(value, "value");
+        communicationVersion_ = pb::ProtoPreconditions.CheckNotNull(value, "value");
       }
     }
 
       get { return brainParameters_; }
     }
 
+    /// <summary>Field number for the "package_version" field.</summary>
+    public const int PackageVersionFieldNumber = 7;
+    private string packageVersion_ = "";
+    /// <summary>
+    /// Package/library version that the responding side (typically the C# environment) is using.
+    /// </summary>
+    [global::System.Diagnostics.DebuggerNonUserCodeAttribute]
+    public string PackageVersion {
+      get { return packageVersion_; }
+      set {
+        packageVersion_ = pb::ProtoPreconditions.CheckNotNull(value, "value");
+      }
+    }
+
     [global::System.Diagnostics.DebuggerNonUserCodeAttribute]
     public override bool Equals(object other) {
       return Equals(other as UnityRLInitializationOutputProto);
         return true;
       }
       if (Name != other.Name) return false;
-      if (Version != other.Version) return false;
+      if (CommunicationVersion != other.CommunicationVersion) return false;
+      if (PackageVersion != other.PackageVersion) return false;
       return Equals(_unknownFields, other._unknownFields);
     }
 
       if (Name.Length != 0) hash ^= Name.GetHashCode();
-      if (Version.Length != 0) hash ^= Version.GetHashCode();
+      if (CommunicationVersion.Length != 0) hash ^= CommunicationVersion.GetHashCode();
+      if (PackageVersion.Length != 0) hash ^= PackageVersion.GetHashCode();
       if (_unknownFields != null) {
         hash ^= _unknownFields.GetHashCode();
       }
         output.WriteRawTag(10);
         output.WriteString(Name);
       }
-      if (Version.Length != 0) {
+      if (CommunicationVersion.Length != 0) {
-        output.WriteString(Version);
+        output.WriteString(CommunicationVersion);
       }
       if (LogPath.Length != 0) {
         output.WriteRawTag(26);
+      if (PackageVersion.Length != 0) {
+        output.WriteRawTag(58);
+        output.WriteString(PackageVersion);
+      }
       if (_unknownFields != null) {
         _unknownFields.WriteTo(output);
       }
       if (Name.Length != 0) {
         size += 1 + pb::CodedOutputStream.ComputeStringSize(Name);
       }
-      if (Version.Length != 0) {
-        size += 1 + pb::CodedOutputStream.ComputeStringSize(Version);
+      if (CommunicationVersion.Length != 0) {
+        size += 1 + pb::CodedOutputStream.ComputeStringSize(CommunicationVersion);
+      if (PackageVersion.Length != 0) {
+        size += 1 + pb::CodedOutputStream.ComputeStringSize(PackageVersion);
+      }
       if (_unknownFields != null) {
         size += _unknownFields.CalculateSize();
       }
       if (other.Name.Length != 0) {
         Name = other.Name;
       }
-      if (other.Version.Length != 0) {
-        Version = other.Version;
+      if (other.CommunicationVersion.Length != 0) {
+        CommunicationVersion = other.CommunicationVersion;
+      if (other.PackageVersion.Length != 0) {
+        PackageVersion = other.PackageVersion;
+      }
       _unknownFields = pb::UnknownFieldSet.MergeFrom(_unknownFields, other._unknownFields);
     }
 
             break;
           }
           case 18: {
-            Version = input.ReadString();
+            CommunicationVersion = input.ReadString();
             break;
           }
           case 26: {
           case 42: {
             brainParameters_.AddEntriesFrom(input, _repeated_brainParameters_codec);
+            break;
+          }
+          case 58: {
+            PackageVersion = input.ReadString();
             break;
           }
         }

ml-agents-envs/mlagents_envs/communicator_objects/unity_rl_initialization_input_pb2.py

   name='mlagents_envs/communicator_objects/unity_rl_initialization_input.proto',
   package='communicator_objects',
   syntax='proto3',
-  serialized_pb=_b('\nFmlagents_envs/communicator_objects/unity_rl_initialization_input.proto\x12\x14\x63ommunicator_objects\"/\n\x1fUnityRLInitializationInputProto\x12\x0c\n\x04seed\x18\x01 \x01(\x05\x42\x1f\xaa\x02\x1cMLAgents.CommunicatorObjectsb\x06proto3')
+  serialized_pb=_b('\nFmlagents_envs/communicator_objects/unity_rl_initialization_input.proto\x12\x14\x63ommunicator_objects\"g\n\x1fUnityRLInitializationInputProto\x12\x0c\n\x04seed\x18\x01 \x01(\x05\x12\x1d\n\x15\x63ommunication_version\x18\x02 \x01(\t\x12\x17\n\x0fpackage_version\x18\x03 \x01(\tB\x1f\xaa\x02\x1cMLAgents.CommunicatorObjectsb\x06proto3')
 )
 
 
       message_type=None, enum_type=None, containing_type=None,
       is_extension=False, extension_scope=None,
       options=None, file=DESCRIPTOR),
+    _descriptor.FieldDescriptor(
+      name='communication_version', full_name='communicator_objects.UnityRLInitializationInputProto.communication_version', index=1,
+      number=2, type=9, cpp_type=9, label=1,
+      has_default_value=False, default_value=_b("").decode('utf-8'),
+      message_type=None, enum_type=None, containing_type=None,
+      is_extension=False, extension_scope=None,
+      options=None, file=DESCRIPTOR),
+    _descriptor.FieldDescriptor(
+      name='package_version', full_name='communicator_objects.UnityRLInitializationInputProto.package_version', index=2,
+      number=3, type=9, cpp_type=9, label=1,
+      has_default_value=False, default_value=_b("").decode('utf-8'),
+      message_type=None, enum_type=None, containing_type=None,
+      is_extension=False, extension_scope=None,
+      options=None, file=DESCRIPTOR),
   ],
   extensions=[
   ],
   oneofs=[
   ],
   serialized_start=96,
-  serialized_end=143,
+  serialized_end=199,
 )
 
 DESCRIPTOR.message_types_by_name['UnityRLInitializationInputProto'] = _UNITYRLINITIALIZATIONINPUTPROTO

ml-agents-envs/mlagents_envs/communicator_objects/unity_rl_initialization_input_pb2.pyi

 
 from typing import (
     Optional as typing___Optional,
+    Text as typing___Text,
 )
 
 from typing_extensions import (
 class UnityRLInitializationInputProto(google___protobuf___message___Message):
     DESCRIPTOR: google___protobuf___descriptor___Descriptor = ...
     seed = ... # type: builtin___int
+    communication_version = ... # type: typing___Text
+    package_version = ... # type: typing___Text
+        communication_version : typing___Optional[typing___Text] = None,
+        package_version : typing___Optional[typing___Text] = None,
         ) -> None: ...
     @classmethod
     def FromString(cls, s: builtin___bytes) -> UnityRLInitializationInputProto: ...
-        def ClearField(self, field_name: typing_extensions___Literal[u"seed"]) -> None: ...
+        def ClearField(self, field_name: typing_extensions___Literal[u"communication_version",u"package_version",u"seed"]) -> None: ...
-        def ClearField(self, field_name: typing_extensions___Literal[u"seed",b"seed"]) -> None: ...
+        def ClearField(self, field_name: typing_extensions___Literal[u"communication_version",b"communication_version",u"package_version",b"package_version",u"seed",b"seed"]) -> None: ...

ml-agents-envs/mlagents_envs/communicator_objects/unity_rl_initialization_output_pb2.py

   name='mlagents_envs/communicator_objects/unity_rl_initialization_output.proto',
   package='communicator_objects',
   syntax='proto3',
-  serialized_pb=_b('\nGmlagents_envs/communicator_objects/unity_rl_initialization_output.proto\x12\x14\x63ommunicator_objects\x1a\x39mlagents_envs/communicator_objects/brain_parameters.proto\"\x9f\x01\n UnityRLInitializationOutputProto\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x0f\n\x07version\x18\x02 \x01(\t\x12\x10\n\x08log_path\x18\x03 \x01(\t\x12\x44\n\x10\x62rain_parameters\x18\x05 \x03(\x0b\x32*.communicator_objects.BrainParametersProtoJ\x04\x08\x06\x10\x07\x42\x1f\xaa\x02\x1cMLAgents.CommunicatorObjectsb\x06proto3')
+  serialized_pb=_b('\nGmlagents_envs/communicator_objects/unity_rl_initialization_output.proto\x12\x14\x63ommunicator_objects\x1a\x39mlagents_envs/communicator_objects/brain_parameters.proto\"\xc6\x01\n UnityRLInitializationOutputProto\x12\x0c\n\x04name\x18\x01 \x01(\t\x12\x1d\n\x15\x63ommunication_version\x18\x02 \x01(\t\x12\x10\n\x08log_path\x18\x03 \x01(\t\x12\x44\n\x10\x62rain_parameters\x18\x05 \x03(\x0b\x32*.communicator_objects.BrainParametersProto\x12\x17\n\x0fpackage_version\x18\x07 \x01(\tJ\x04\x08\x06\x10\x07\x42\x1f\xaa\x02\x1cMLAgents.CommunicatorObjectsb\x06proto3')
   ,
   dependencies=[mlagents__envs_dot_communicator__objects_dot_brain__parameters__pb2.DESCRIPTOR,])
 
       is_extension=False, extension_scope=None,
       options=None, file=DESCRIPTOR),
     _descriptor.FieldDescriptor(
-      name='version', full_name='communicator_objects.UnityRLInitializationOutputProto.version', index=1,
+      name='communication_version', full_name='communicator_objects.UnityRLInitializationOutputProto.communication_version', index=1,
       number=2, type=9, cpp_type=9, label=1,
       has_default_value=False, default_value=_b("").decode('utf-8'),
       message_type=None, enum_type=None, containing_type=None,
       message_type=None, enum_type=None, containing_type=None,
       is_extension=False, extension_scope=None,
       options=None, file=DESCRIPTOR),
+    _descriptor.FieldDescriptor(
+      name='package_version', full_name='communicator_objects.UnityRLInitializationOutputProto.package_version', index=4,
+      number=7, type=9, cpp_type=9, label=1,
+      has_default_value=False, default_value=_b("").decode('utf-8'),
+      message_type=None, enum_type=None, containing_type=None,
+      is_extension=False, extension_scope=None,
+      options=None, file=DESCRIPTOR),
   ],
   extensions=[
   ],
   oneofs=[
   ],
   serialized_start=157,
-  serialized_end=316,
+  serialized_end=355,
 )
 
 _UNITYRLINITIALIZATIONOUTPUTPROTO.fields_by_name['brain_parameters'].message_type = mlagents__envs_dot_communicator__objects_dot_brain__parameters__pb2._BRAINPARAMETERSPROTO

ml-agents-envs/mlagents_envs/communicator_objects/unity_rl_initialization_output_pb2.pyi

 class UnityRLInitializationOutputProto(google___protobuf___message___Message):
     DESCRIPTOR: google___protobuf___descriptor___Descriptor = ...
     name = ... # type: typing___Text
-    version = ... # type: typing___Text
+    communication_version = ... # type: typing___Text
+    package_version = ... # type: typing___Text
 
     @property
     def brain_parameters(self) -> google___protobuf___internal___containers___RepeatedCompositeFieldContainer[mlagents_envs___communicator_objects___brain_parameters_pb2___BrainParametersProto]: ...
         name : typing___Optional[typing___Text] = None,
-        version : typing___Optional[typing___Text] = None,
+        communication_version : typing___Optional[typing___Text] = None,
+        package_version : typing___Optional[typing___Text] = None,
         ) -> None: ...
     @classmethod
     def FromString(cls, s: builtin___bytes) -> UnityRLInitializationOutputProto: ...
-        def ClearField(self, field_name: typing_extensions___Literal[u"brain_parameters",u"log_path",u"name",u"version"]) -> None: ...
+        def ClearField(self, field_name: typing_extensions___Literal[u"brain_parameters",u"communication_version",u"log_path",u"name",u"package_version"]) -> None: ...
-        def ClearField(self, field_name: typing_extensions___Literal[u"brain_parameters",b"brain_parameters",u"log_path",b"log_path",u"name",b"name",u"version",b"version"]) -> None: ...
+        def ClearField(self, field_name: typing_extensions___Literal[u"brain_parameters",b"brain_parameters",u"communication_version",b"communication_version",u"log_path",b"log_path",u"name",b"name",u"package_version",b"package_version"]) -> None: ...

ml-agents-envs/mlagents_envs/environment.py

 import subprocess
 from typing import Dict, List, Optional, Any
 
+import mlagents_envs
 from mlagents_envs.side_channel.side_channel import SideChannel
 
 from mlagents_envs.base_env import (
 class UnityEnvironment(BaseEnv):
     SCALAR_ACTION_TYPES = (int, np.int32, np.int64, float, np.float32, np.float64)
     SINGLE_BRAIN_ACTION_TYPES = SCALAR_ACTION_TYPES + (list, np.ndarray)
-    API_VERSION = "API-15-dev0"
+
+    # Communication protocol version.
+    # When connecting to C#, this must match Academy.k_ApiVersion
+    # Currently we require strict equality between the communication protocol
+    # on each side, although we may allow some flexibility in the future.
+    # This should be incremented whenever a change is made to the communication protocol.
+    API_VERSION = "0.15.0"
+
+    # Default port that the editor listens on. If an environment executable
+    # isn't specified, this port will be used.
+
+    # Command line argument used to pass the port to the executable environment.
     PORT_COMMAND_LINE_ARG = "--mlagents-port"
 
     def __init__(
         atexit.register(self._close)
         self.port = base_port + worker_id
         self._buffer_size = 12000
-        self._version_ = UnityEnvironment.API_VERSION
         # If true, this means the environment was successfully loaded
         self._loaded = False
         # The process that is started. If None, no process was started
             )
         self._loaded = True
 
-        rl_init_parameters_in = UnityRLInitializationInputProto(seed=seed)
+        rl_init_parameters_in = UnityRLInitializationInputProto(
+            seed=seed,
+            communication_version=self.API_VERSION,
+            package_version=mlagents_envs.__version__,
+        )
         try:
             aca_output = self.send_academy_parameters(rl_init_parameters_in)
             aca_params = aca_output.rl_initialization_output
-        # TODO : think of a better way to expose the academyParameters
-        self._unity_version = aca_params.version
-        if self._unity_version != self._version_:
+
+        unity_communicator_version = aca_params.communication_version
+        if unity_communicator_version != UnityEnvironment.API_VERSION:
-                f"The API number is not compatible between Unity and python. "
-                f"Python API: {self._version_}, Unity API: {self._unity_version}.\n"
-                f"Please go to https://github.com/Unity-Technologies/ml-agents/releases/tag/latest_release"
+                f"The communication API version is not compatible between Unity and python. "
+                f"Python API: {UnityEnvironment.API_VERSION}, Unity API: {unity_communicator_version}.\n "
+                f"Please go to https://github.com/Unity-Technologies/ml-agents/releases/tag/latest_release "
+            )
+        else:
+            logger.info(
+                f"Connected to Unity environment with package version {aca_params.package_version} "
+                f"and communication version {aca_params.communication_version}"
             )
         self._env_state: Dict[str, BatchedStepResult] = {}
         self._env_specs: Dict[str, AgentGroupSpec] = {}

ml-agents-envs/mlagents_envs/mock_communicator.py

         )
         rl_init = UnityRLInitializationOutputProto(
             name="RealFakeAcademy",
-            version=UnityEnvironment.API_VERSION,
+            communication_version=UnityEnvironment.API_VERSION,
+            package_version="mock_package_version",
             log_path="",
             brain_parameters=[bp],
         )

protobuf-definitions/proto/mlagents_envs/communicator_objects/unity_rl_initialization_input.proto

 option csharp_namespace = "MLAgents.CommunicatorObjects";
 package communicator_objects;
 
-
+// The initializaiton message - this is typically sent from the Python trainer to the C# environment.
+
+    // Communication protocol version that the initiating side (typically the Python trainer) is using.
+    string communication_version = 2;
+
+    // Package/library version that the initiating side (typically the Python trainer) is using.
+    string package_version = 3;
 }

protobuf-definitions/proto/mlagents_envs/communicator_objects/unity_rl_initialization_output.proto

 // The request message containing the academy's parameters.
 message UnityRLInitializationOutputProto {
     string name = 1;
-    string version = 2;
+
+    // Communication protocol version that the responding side (typically the C# environment) is using.
+    string communication_version = 2;
+
+
+
+
+    // Package/library version that the responding side (typically the C# environment) is using.
+    string package_version = 7;
 }

utils/validate_versions.py

 #!/usr/bin/env python3
 
 import os
+import json
 import sys
 from typing import Dict
 import argparse
     "ml-agents-envs/mlagents_envs",
     "gym-unity/gym_unity",
 ]
+
+UNITY_PACKAGE_JSON_PATH = "com.unity.ml-agents/package.json"
+ACADEMY_PATH = "com.unity.ml-agents/Runtime/Academy.cs"
 
 
 def extract_version_string(filename):
         print(f"Setting {path} to version {new_version}")
         with open(path, "w") as f:
             f.write(new_contents)
+    # Package version is a bit stricter - only set it if we're not a "dev" version.
+    if "dev" not in new_version:
+        package_version = new_version + "-preview"
+        print(
+            f"Setting package version to {package_version} in {UNITY_PACKAGE_JSON_PATH}"
+        )
+        set_package_version(package_version)
+        print(f"Setting package version to {package_version} in {ACADEMY_PATH}")
+        set_academy_version_string(package_version)
+
+
+def set_package_version(new_version: str) -> None:
+    with open(UNITY_PACKAGE_JSON_PATH, "r") as f:
+        package_json = json.load(f)
+    if "version" in package_json:
+        package_json["version"] = new_version
+    with open(UNITY_PACKAGE_JSON_PATH, "w") as f:
+        json.dump(package_json, f, indent=2)
+
+
+def set_academy_version_string(new_version):
+    needle = "internal const string k_PackageVersion"
+    found = 0
+    with open(ACADEMY_PATH) as f:
+        lines = f.readlines()
+    for i, l in enumerate(lines):
+        if needle in l:
+            left, right = l.split(" = ")
+            right = f' = "{new_version}";\n'
+            lines[i] = left + right
+            found += 1
+    if found != 1:
+        raise RuntimeError(
+            f'Expected to find search string "{needle}" exactly once, but found it {found} times'
+        )
+    with open(ACADEMY_PATH, "w") as f:
+        f.writelines(lines)
 
 
 if __name__ == "__main__":

com.unity.ml-agents/Tests/Editor/AcademyTests.cs

+using NUnit.Framework;
+using UnityEngine;
+using System.Reflection;
+using MLAgents;
+
+namespace MLAgents.Tests
+{
+    [TestFixture]
+    public class AcademyTests
+    {
+        [Test]
+        public void TestPackageVersion()
+        {
+            // Make sure that the version strings in the package and Academy don't get out of sync.
+            // Unfortunately, the PackageInfo methods don't exist in earlier versions of the editor.
+#if UNITY_2019_3_OR_NEWER
+            var packageInfo = UnityEditor.PackageManager.PackageInfo.FindForAssembly(typeof(Agent).Assembly);
+            Assert.AreEqual("com.unity.ml-agents", packageInfo.name);
+            Assert.AreEqual(Academy.k_PackageVersion, packageInfo.version);
+#endif
+        }
+
+
+    }
+}

com.unity.ml-agents/Tests/Editor/AcademyTests.cs.meta

+fileFormatVersion: 2
+guid: f434773fe0f1b41c5b3f446fa0adece4
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: