.NET: [BREAKING] Prevent nulls in AIAgent.Id property

dotnet/src/Microsoft.Agents.AI.A2A/A2AAgent.cs

@@ -198,7 +198,7 @@ public override async IAsyncEnumerable<AgentRunResponseUpdate> RunStreamingAsync
     }
 
     /// <inheritdoc/>
-    public override string Id => this._id ?? base.Id;
+    protected override string? IdCore => this._id;
 
     /// <inheritdoc/>
     public override string? Name => this._name ?? base.Name;

dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgent.cs

@@ -22,9 +22,6 @@ namespace Microsoft.Agents.AI;
 [DebuggerDisplay("{DisplayName,nq}")]
 public abstract class AIAgent
 {
-    /// <summary>Default ID of this agent instance.</summary>
-    private readonly string _id = Guid.NewGuid().ToString("N");
-
     /// <summary>
     /// Gets the unique identifier for this agent instance.
     /// </summary>
@@ -37,7 +34,19 @@ public abstract class AIAgent
     /// agent instances in multi-agent scenarios. They should remain stable for the lifetime
     /// of the agent instance.
     /// </remarks>
-    public virtual string Id => this._id;
+    public string Id { get => this.IdCore ?? field; } = Guid.NewGuid().ToString("N");
+
+    /// <summary>
+    /// Gets a custom identifier for the agent, which can be overridden by derived classes.
+    /// </summary>
+    /// <value>
+    /// A string representing the agent's identifier, or <see langword="null"/> if the default ID should be used.
+    /// </value>
+    /// <remarks>
+    /// Derived classes can override this property to provide a custom identifier.
+    /// When <see langword="null"/> is returned, the <see cref="Id"/> property will use the default randomly-generated identifier.
+    /// </remarks>
+    protected virtual string? IdCore => null;
 
     /// <summary>
     /// Gets the human-readable name of the agent.
@@ -61,7 +70,7 @@ public abstract class AIAgent
     /// This property provides a guaranteed non-null string suitable for display in user interfaces,
     /// logs, or other contexts where a readable identifier is needed.
     /// </remarks>
-    public virtual string DisplayName => this.Name ?? this.Id ?? this._id; // final fallback to _id in case Id override returns null
+    public virtual string DisplayName => this.Name ?? this.Id;
 
     /// <summary>
     /// Gets a description of the agent's purpose, capabilities, or behavior.

dotnet/src/Microsoft.Agents.AI.Abstractions/DelegatingAIAgent.cs

@@ -54,7 +54,7 @@ protected DelegatingAIAgent(AIAgent innerAgent)
     protected AIAgent InnerAgent { get; }
 
     /// <inheritdoc />
-    public override string Id => this.InnerAgent.Id;
+    protected override string? IdCore => this.InnerAgent.Id;
 
     /// <inheritdoc />
     public override string? Name => this.InnerAgent.Name;

dotnet/src/Microsoft.Agents.AI.DurableTask/EntityAgentWrapper.cs

@@ -19,7 +19,7 @@ internal sealed class EntityAgentWrapper(
     private readonly IServiceProvider? _entityScopedServices = entityScopedServices;
 
     // The ID of the agent is always the entity ID.
-    public override string Id => this._entityContext.Id.ToString();
+    protected override string? IdCore => this._entityContext.Id.ToString();
 
     public override async Task<AgentRunResponse> RunAsync(
         IEnumerable<ChatMessage> messages,

dotnet/src/Microsoft.Agents.AI.Workflows/WorkflowHostAgent.cs

@@ -39,7 +39,7 @@ public WorkflowHostAgent(Workflow workflow, string? id = null, string? name = nu
         this._describeTask = this._workflow.DescribeProtocolAsync().AsTask();
     }
 
-    public override string Id => this._id ?? base.Id;
+    protected override string? IdCore => this._id;
     public override string? Name { get; }
     public override string? Description { get; }
 

dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs

@@ -121,7 +121,7 @@ public ChatClientAgent(IChatClient chatClient, ChatClientAgentOptions? options,
     public IChatClient ChatClient { get; }
 
     /// <inheritdoc/>
-    public override string Id => this._agentOptions?.Id ?? base.Id;
+    protected override string? IdCore => this._agentOptions?.Id;
 
     /// <inheritdoc/>
     public override string? Name => this._agentOptions?.Name;

dotnet/tests/Microsoft.Agents.AI.Abstractions.UnitTests/AIAgentTests.cs

@@ -214,13 +214,31 @@ public async Task InvokeStreamingWithSingleMessageCallsMockedInvokeWithMessageIn
     [Fact]
     public void ValidateAgentIDIsIdempotent()
     {
+        // Arrange
         var agent = new MockAgent();
 
+        // Act
         string id = agent.Id;
+
+        // Assert
         Assert.NotNull(id);
         Assert.Equal(id, agent.Id);
     }
 
+    [Fact]
+    public void ValidateAgentIDCanBeProvidedByDerivedAgentClass()
+    {
+        // Arrange
+        var agent = new MockAgent(id: "test-agent-id");
+
+        // Act
+        string id = agent.Id;
+
+        // Assert
+        Assert.NotNull(id);
+        Assert.Equal("test-agent-id", id);
+    }
+
     #region GetService Method Tests
 
     /// <summary>
@@ -344,6 +362,13 @@ public abstract class TestAgentThread : AgentThread;
 
     private sealed class MockAgent : AIAgent
     {
+        public MockAgent(string? id = null)
+        {
+            this.IdCore = id;
+        }
+
+        protected override string? IdCore { get; }
+
         public override AgentThread GetNewThread()
             => throw new NotImplementedException();
 

dotnet/tests/Microsoft.Agents.AI.Abstractions.UnitTests/DelegatingAIAgentTests.cs

@@ -6,6 +6,7 @@
 using System.Threading.Tasks;
 using Microsoft.Extensions.AI;
 using Moq;
+using Moq.Protected;
 
 namespace Microsoft.Agents.AI.Abstractions.UnitTests;
 
@@ -31,7 +32,7 @@ public DelegatingAIAgentTests()
         this._testThread = new TestAgentThread();
 
         // Setup inner agent mock
-        this._innerAgentMock.Setup(x => x.Id).Returns("test-agent-id");
+        this._innerAgentMock.Protected().SetupGet<string>("IdCore").Returns("test-agent-id");
         this._innerAgentMock.Setup(x => x.Name).Returns("Test Agent");
         this._innerAgentMock.Setup(x => x.Description).Returns("Test Description");
         this._innerAgentMock.Setup(x => x.GetNewThread()).Returns(this._testThread);
@@ -93,7 +94,7 @@ public void Id_DelegatesToInnerAgent()
 
         // Assert
         Assert.Equal("test-agent-id", id);
-        this._innerAgentMock.Verify(x => x.Id, Times.Once);
+        this._innerAgentMock.Protected().VerifyGet<string>("IdCore", Times.Once());
     }
 
     /// <summary>

dotnet/tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.IntegrationTests/BasicStreamingTests.cs

@@ -276,15 +276,9 @@ public async ValueTask DisposeAsync()
 [SuppressMessage("Performance", "CA1812:Avoid uninstantiated internal classes", Justification = "Instantiated via dependency injection")]
 internal sealed class FakeChatClientAgent : AIAgent
 {
-    public FakeChatClientAgent()
-    {
-        this.Id = "fake-agent";
-        this.Description = "A fake agent for testing";
-    }
-
-    public override string Id { get; }
+    protected override string? IdCore => "fake-agent";
 
-    public override string? Description { get; }
+    public override string? Description => "A fake agent for testing";
 
     public override AgentThread GetNewThread()
     {
@@ -350,15 +344,9 @@ public FakeInMemoryAgentThread(JsonElement serializedThread, JsonSerializerOptio
 [SuppressMessage("Performance", "CA1812:Avoid uninstantiated internal classes", Justification = "Instantiated via dependency injection")]
 internal sealed class FakeMultiMessageAgent : AIAgent
 {
-    public FakeMultiMessageAgent()
-    {
-        this.Id = "fake-multi-message-agent";
-        this.Description = "A fake agent that sends multiple messages for testing";
-    }
-
-    public override string Id { get; }
+    protected override string? IdCore => "fake-multi-message-agent";
 
-    public override string? Description { get; }
+    public override string? Description => "A fake agent that sends multiple messages for testing";
 
     public override AgentThread GetNewThread()
     {

dotnet/tests/Microsoft.Agents.AI.Hosting.AGUI.AspNetCore.UnitTests/AGUIEndpointRouteBuilderExtensionsTests.cs

@@ -421,7 +421,7 @@ private static List<JsonElement> ParseSseEvents(string responseContent)
 
     private sealed class MultiResponseAgent : AIAgent
     {
-        public override string Id => "multi-response-agent";
+        protected override string? IdCore => "multi-response-agent";
 
         public override string? Description => "Agent that produces multiple text chunks";
 
@@ -510,7 +510,7 @@ public TestInMemoryAgentThread(JsonElement serializedThreadState, JsonSerializer
 
     private sealed class TestAgent : AIAgent
     {
-        public override string Id => "test-agent";
+        protected override string? IdCore => "test-agent";
 
         public override string? Description => "Test agent";
 

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/Sample/06_GroupChat_Workflow.cs

@@ -57,7 +57,7 @@ internal sealed class HelloAgent(string id = nameof(HelloAgent)) : AIAgent
     public const string Greeting = "Hello World!";
     public const string DefaultId = nameof(HelloAgent);
 
-    public override string Id => id;
+    protected override string? IdCore => id;
     public override string? Name => id;
 
     public override AgentThread GetNewThread()

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/SpecializedExecutorSmokeTests.cs

@@ -19,7 +19,7 @@ public class SpecializedExecutorSmokeTests
 {
     public class TestAIAgent(List<ChatMessage>? messages = null, string? id = null, string? name = null) : AIAgent
     {
-        public override string Id => id ?? base.Id;
+        protected override string? IdCore => id;
         public override string? Name => name;
 
         public static List<ChatMessage> ToChatMessages(params string[] messages)

dotnet/tests/Microsoft.Agents.AI.Workflows.UnitTests/TestEchoAgent.cs

@@ -13,7 +13,7 @@ namespace Microsoft.Agents.AI.Workflows.UnitTests;
 
 internal class TestEchoAgent(string? id = null, string? name = null, string? prefix = null) : AIAgent
 {
-    public override string Id => id ?? base.Id;
+    protected override string? IdCore => id;
     public override string? Name => name ?? base.Name;
 
     public override AgentThread DeserializeThread(JsonElement serializedThread, JsonSerializerOptions? jsonSerializerOptions = null)