Surface AdditionalProperties in ChatClientAgentOptions, ChatClientAgent, and AIAgentMetadata

Co-authored-by: kzu <[email protected]>

Author: Copilot

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

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System.Diagnostics;
+using Microsoft.Extensions.AI;
 
 namespace Microsoft.Agents.AI;
 
@@ -21,9 +22,13 @@ public class AIAgentMetadata
     /// The name of the agent provider, if applicable. Where possible, this should map to the
     /// appropriate name defined in the OpenTelemetry Semantic Conventions for Generative AI systems.
     /// </param>
-    public AIAgentMetadata(string? providerName = null)
+    /// <param name="additionalProperties">
+    /// Additional properties associated with the agent metadata.
+    /// </param>
+    public AIAgentMetadata(string? providerName = null, AdditionalPropertiesDictionary? additionalProperties = null)
     {
         this.ProviderName = providerName;
+        this.AdditionalProperties = additionalProperties;
     }
 
     /// <summary>
@@ -37,4 +42,17 @@ public AIAgentMetadata(string? providerName = null)
     /// OpenTelemetry Semantic Conventions for Generative AI systems.
     /// </remarks>
     public string? ProviderName { get; }
+
+    /// <summary>
+    /// Gets additional properties associated with the agent metadata.
+    /// </summary>
+    /// <value>
+    /// An <see cref="AdditionalPropertiesDictionary"/> containing custom properties,
+    /// or <see langword="null"/> if no additional properties are present.
+    /// </value>
+    /// <remarks>
+    /// Additional properties provide a way to include custom metadata or agent-specific
+    /// information that doesn't fit into the standard agent schema.
+    /// </remarks>
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; }
 }

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

@@ -97,7 +97,7 @@ public ChatClientAgent(IChatClient chatClient, ChatClientAgentOptions? options,
         // Options must be cloned since ChatClientAgentOptions is mutable.
         this._agentOptions = options?.Clone();
 
-        this._agentMetadata = new AIAgentMetadata(chatClient.GetService<ChatClientMetadata>()?.ProviderName);
+        this._agentMetadata = new AIAgentMetadata(chatClient.GetService<ChatClientMetadata>()?.ProviderName, this._agentOptions?.AdditionalProperties);
 
         // Get the type of the chat client before wrapping it as an agent invoking chat client.
         this._chatClientType = chatClient.GetType();
@@ -129,6 +129,9 @@ public ChatClientAgent(IChatClient chatClient, ChatClientAgentOptions? options,
     /// <inheritdoc/>
     public override string? Description => this._agentOptions?.Description;
 
+    /// <inheritdoc/>
+    public override AdditionalPropertiesDictionary? AdditionalProperties => this._agentOptions?.AdditionalProperties;
+
     /// <summary>
     /// Gets the system instructions that guide the agent's behavior during conversations.
     /// </summary>

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

@@ -98,6 +98,19 @@ public ChatClientAgentOptions(string? instructions, string? name = null, string?
     /// </remarks>
     public bool UseProvidedChatClientAsIs { get; set; }
 
+    /// <summary>
+    /// Gets or sets additional properties associated with the agent options.
+    /// </summary>
+    /// <value>
+    /// An <see cref="AdditionalPropertiesDictionary"/> containing custom properties,
+    /// or <see langword="null"/> if no additional properties are present.
+    /// </value>
+    /// <remarks>
+    /// Additional properties provide a way to include custom metadata or agent-specific
+    /// information that doesn't fit into the standard agent schema.
+    /// </remarks>
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
+
     /// <summary>
     /// Creates a new instance of <see cref="ChatClientAgentOptions"/> with the same values as this instance.
     /// </summary>
@@ -111,6 +124,7 @@ public ChatClientAgentOptions Clone()
             ChatOptions = this.ChatOptions?.Clone(),
             ChatMessageStoreFactory = this.ChatMessageStoreFactory,
             AIContextProviderFactory = this.AIContextProviderFactory,
+            AdditionalProperties = this.AdditionalProperties?.Clone(),
         };
 
     /// <summary>

dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgentOptionsTests.cs

@@ -221,4 +221,61 @@ public void Clone_WithNullChatOptions_ClonesCorrectly()
         Assert.Null(clone.ChatMessageStoreFactory);
         Assert.Null(clone.AIContextProviderFactory);
     }
+
+    [Fact]
+    public void AdditionalProperties_DefaultValue_ReturnsNull()
+    {
+        // Arrange
+        var options = new ChatClientAgentOptions();
+
+        // Act
+        var result = options.AdditionalProperties;
+
+        // Assert
+        Assert.Null(result);
+    }
+
+    [Fact]
+    public void AdditionalProperties_CanBeSet_ReturnsSetValue()
+    {
+        // Arrange
+        var options = new ChatClientAgentOptions();
+        var additionalProperties = new AdditionalPropertiesDictionary
+        {
+            ["beta"] = true,
+            ["icon"] = "agent-icon.png"
+        };
+
+        // Act
+        options.AdditionalProperties = additionalProperties;
+
+        // Assert
+        Assert.Same(additionalProperties, options.AdditionalProperties);
+    }
+
+    [Fact]
+    public void Clone_WithAdditionalProperties_ClonesAdditionalProperties()
+    {
+        // Arrange
+        var original = new ChatClientAgentOptions
+        {
+            Id = "test-id",
+            Name = "Test name",
+            AdditionalProperties = new AdditionalPropertiesDictionary
+            {
+                ["beta"] = true,
+                ["icon"] = "agent-icon.png"
+            }
+        };
+
+        // Act
+        var clone = original.Clone();
+
+        // Assert
+        Assert.NotSame(original, clone);
+        Assert.NotSame(original.AdditionalProperties, clone.AdditionalProperties);
+        Assert.Equal(original.AdditionalProperties?.Count, clone.AdditionalProperties?.Count);
+        Assert.Equal(true, clone.AdditionalProperties?["beta"]);
+        Assert.Equal("agent-icon.png", clone.AdditionalProperties?["icon"]);
+    }
 }

dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgentTests.cs

@@ -2598,6 +2598,77 @@ await Assert.ThrowsAsync<InvalidOperationException>(async () =>
 
     #endregion
 
+    #region AdditionalProperties Tests
+
+    [Fact]
+    public void AdditionalProperties_DefaultValue_ReturnsNull()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var agent = new ChatClientAgent(chatClient);
+
+        // Act
+        var result = agent.AdditionalProperties;
+
+        // Assert
+        Assert.Null(result);
+    }
+
+    [Fact]
+    public void AdditionalProperties_FromOptions_ReturnsOptionsValue()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var additionalProperties = new AdditionalPropertiesDictionary
+        {
+            ["beta"] = true,
+            ["icon"] = "agent-icon.png",
+            ["requiresAuth"] = true
+        };
+        var options = new ChatClientAgentOptions
+        {
+            AdditionalProperties = additionalProperties
+        };
+        var agent = new ChatClientAgent(chatClient, options);
+
+        // Act
+        var result = agent.AdditionalProperties;
+
+        // Assert
+        Assert.NotNull(result);
+        Assert.Equal(3, result.Count);
+        Assert.Equal(true, result["beta"]);
+        Assert.Equal("agent-icon.png", result["icon"]);
+        Assert.Equal(true, result["requiresAuth"]);
+    }
+
+    [Fact]
+    public void GetService_AIAgentMetadata_ReturnsMetadataWithAdditionalProperties()
+    {
+        // Arrange
+        var chatClient = new Mock<IChatClient>().Object;
+        var additionalProperties = new AdditionalPropertiesDictionary
+        {
+            ["beta"] = true
+        };
+        var options = new ChatClientAgentOptions
+        {
+            AdditionalProperties = additionalProperties
+        };
+        var agent = new ChatClientAgent(chatClient, options);
+
+        // Act
+        var metadata = agent.GetService<AIAgentMetadata>();
+
+        // Assert
+        Assert.NotNull(metadata);
+        Assert.NotNull(metadata.AdditionalProperties);
+        Assert.Single(metadata.AdditionalProperties);
+        Assert.Equal(true, metadata.AdditionalProperties["beta"]);
+    }
+
+    #endregion
+
     private static async IAsyncEnumerable<T> ToAsyncEnumerableAsync<T>(IEnumerable<T> values)
     {
         await Task.Yield();