.NET: Allow extending agent run options via additional properties (#1872)

* Allow extending agent run options via additional properties

This mirrors the M.E.AI model in ChatOptions.AdditionalProperties which is very useful when building functionality pipelines.

Fixes https://github.com/microsoft/agent-framework/issues/1815

* Expand XML documentation

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Add AdditionalProperties tests to AgentRunOptions

Co-authored-by: kzu <169707+kzu@users.noreply.github.com>

---------

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: kzu <169707+kzu@users.noreply.github.com>

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

@@ -1,6 +1,7 @@
 // Copyright (c) Microsoft. All rights reserved.
 
 using System;
+using Microsoft.Extensions.AI;
 using Microsoft.Shared.Diagnostics;
 
 namespace Microsoft.Agents.AI;
@@ -32,6 +33,7 @@ public class AgentRunOptions
         _ = Throw.IfNull(options);
         this.ContinuationToken = options.ContinuationToken;
         this.AllowBackgroundResponses = options.AllowBackgroundResponses;
+        this.AdditionalProperties = options.AdditionalProperties?.Clone();
     }
 
     /// <summary>
@@ -74,4 +76,18 @@ public class AgentRunOptions
     /// </para>
     /// </remarks>
     public bool? AllowBackgroundResponses { get; set; }
+
+    /// <summary>
+    /// Gets or sets additional properties associated with these 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 provider-specific
+    /// information that doesn't fit into the standard options schema. This is useful for
+    /// preserving implementation-specific details or extending the options with custom data.
+    /// </remarks>
+    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
 }

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

@@ -18,7 +18,12 @@ public class AgentRunOptionsTests
         var options = new AgentRunOptions
         {
             ContinuationToken = new object(),
-            AllowBackgroundResponses = true
+            AllowBackgroundResponses = true,
+            AdditionalProperties = new AdditionalPropertiesDictionary
+            {
+                ["key1"] = "value1",
+                ["key2"] = 42
+            }
         };
 
         // Act
@@ -28,6 +33,10 @@ public class AgentRunOptionsTests
         Assert.NotNull(clone);
         Assert.Same(options.ContinuationToken, clone.ContinuationToken);
         Assert.Equal(options.AllowBackgroundResponses, clone.AllowBackgroundResponses);
+        Assert.NotNull(clone.AdditionalProperties);
+        Assert.NotSame(options.AdditionalProperties, clone.AdditionalProperties);
+        Assert.Equal("value1", clone.AdditionalProperties["key1"]);
+        Assert.Equal(42, clone.AdditionalProperties["key2"]);
     }
 
     [Fact]
@@ -42,7 +51,12 @@ public class AgentRunOptionsTests
         var options = new AgentRunOptions
         {
             ContinuationToken = ResponseContinuationToken.FromBytes(new byte[] { 1, 2, 3 }),
-            AllowBackgroundResponses = true
+            AllowBackgroundResponses = true,
+            AdditionalProperties = new AdditionalPropertiesDictionary
+            {
+                ["key1"] = "value1",
+                ["key2"] = 42
+            }
         };
 
         // Act
@@ -54,5 +68,13 @@ public class AgentRunOptionsTests
         Assert.NotNull(deserialized);
         Assert.Equivalent(ResponseContinuationToken.FromBytes(new byte[] { 1, 2, 3 }), deserialized!.ContinuationToken);
         Assert.Equal(options.AllowBackgroundResponses, deserialized.AllowBackgroundResponses);
+        Assert.NotNull(deserialized.AdditionalProperties);
+        Assert.Equal(2, deserialized.AdditionalProperties.Count);
+        Assert.True(deserialized.AdditionalProperties.TryGetValue("key1", out object? value1));
+        Assert.IsType<JsonElement>(value1);
+        Assert.Equal("value1", ((JsonElement)value1!).GetString());
+        Assert.True(deserialized.AdditionalProperties.TryGetValue("key2", out object? value2));
+        Assert.IsType<JsonElement>(value2);
+        Assert.Equal(42, ((JsonElement)value2!).GetInt32());
     }
 }