feat: Add AdditionalPropertiesExtensions with ToAdditionalProperties and ToA2AMetadata methods (#260)

* Initial plan

* Add AdditionalPropertiesExtensions with ToAdditionalProperties and ToA2AMetadata methods

Co-authored-by: SergeyMenshykh <68852919+SergeyMenshykh@users.noreply.github.com>

* Move AdditionalPropertiesExtensions to Microsoft.Extensions.AI namespace

Co-authored-by: SergeyMenshykh <68852919+SergeyMenshykh@users.noreply.github.com>

---------

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

Author: Copilot

src/A2A/Extensions/AIContentExtensions.cs

@@ -25,7 +25,7 @@ public static ChatMessage ToChatMessage(this AgentMessage agentMessage)
 
         return new()
         {
-            AdditionalProperties = ToAdditionalProperties(agentMessage.Metadata),
+            AdditionalProperties = agentMessage.Metadata.ToAdditionalProperties(),
             Contents = agentMessage.Parts.ConvertAll(p => p.ToAIContent()),
             MessageId = agentMessage.MessageId,
             RawRepresentation = agentMessage,
@@ -106,7 +106,7 @@ public static AIContent ToAIContent(this Part part)
 
         content ??= new AIContent();
 
-        content.AdditionalProperties = ToAdditionalProperties(part.Metadata);
+        content.AdditionalProperties = part.Metadata.ToAdditionalProperties();
         content.RawRepresentation = part;
 
         return content;
@@ -171,20 +171,4 @@ public static AIContent ToAIContent(this Part part)
 
         return part;
     }
-
-    private static AdditionalPropertiesDictionary? ToAdditionalProperties(Dictionary<string, JsonElement>? metadata)
-    {
-        if (metadata is not { Count: > 0 })
-        {
-            return null;
-        }
-
-        AdditionalPropertiesDictionary props = [];
-        foreach (var kvp in metadata)
-        {
-            props[kvp.Key] = kvp.Value;
-        }
-
-        return props;
-    }
 }

src/A2A/Extensions/AdditionalPropertiesExtensions.cs

@@ -0,0 +1,53 @@
+using A2A;
+using System.Text.Json;
+
+namespace Microsoft.Extensions.AI;
+
+/// <summary>
+/// Provides extension methods for converting between <see cref="AdditionalPropertiesDictionary"/> and A2A metadata dictionaries.
+/// </summary>
+public static class AdditionalPropertiesExtensions
+{
+    /// <summary>
+    /// Creates an <see cref="AdditionalPropertiesDictionary"/> from A2A metadata.
+    /// </summary>
+    /// <param name="metadata">The A2A metadata dictionary to convert.</param>
+    /// <returns>An <see cref="AdditionalPropertiesDictionary"/> containing the metadata, or <see langword="null"/> if the metadata is empty.</returns>
+    public static AdditionalPropertiesDictionary? ToAdditionalProperties(this Dictionary<string, JsonElement>? metadata)
+    {
+        if (metadata is not { Count: > 0 })
+        {
+            return null;
+        }
+
+        AdditionalPropertiesDictionary props = [];
+        foreach (var kvp in metadata)
+        {
+            props[kvp.Key] = kvp.Value;
+        }
+
+        return props;
+    }
+
+    /// <summary>
+    /// Creates an A2A metadata dictionary from an <see cref="AdditionalPropertiesDictionary"/>.
+    /// </summary>
+    /// <param name="additionalProperties">The additional properties dictionary to convert.</param>
+    /// <returns>A dictionary of A2A metadata, or <see langword="null"/> if the additional properties dictionary is empty.</returns>
+    public static Dictionary<string, JsonElement>? ToA2AMetadata(this AdditionalPropertiesDictionary? additionalProperties)
+    {
+        if (additionalProperties is not { Count: > 0 })
+        {
+            return null;
+        }
+
+        var metadata = new Dictionary<string, JsonElement>();
+
+        foreach (var kvp in additionalProperties)
+        {
+            metadata[kvp.Key] = JsonSerializer.SerializeToElement(kvp.Value, A2AJsonUtilities.DefaultOptions.GetTypeInfo(typeof(object)));
+        }
+
+        return metadata;
+    }
+}

tests/A2A.UnitTests/Models/AdditionalPropertiesExtensionsTests.cs

@@ -0,0 +1,129 @@
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+
+namespace A2A.UnitTests.Models
+{
+    public sealed class AdditionalPropertiesExtensionsTests
+    {
+        [Fact]
+        public void ToAdditionalProperties_ReturnsNullForNullMetadata()
+        {
+            Dictionary<string, JsonElement>? metadata = null;
+            var result = metadata.ToAdditionalProperties();
+            Assert.Null(result);
+        }
+
+        [Fact]
+        public void ToAdditionalProperties_ReturnsNullForEmptyMetadata()
+        {
+            var metadata = new Dictionary<string, JsonElement>();
+            var result = metadata.ToAdditionalProperties();
+            Assert.Null(result);
+        }
+
+        [Fact]
+        public void ToAdditionalProperties_ConvertsMetadataToAdditionalProperties()
+        {
+            var metadata = new Dictionary<string, JsonElement>
+            {
+                ["num"] = JsonSerializer.SerializeToElement(42),
+                ["str"] = JsonSerializer.SerializeToElement("value"),
+                ["bool"] = JsonSerializer.SerializeToElement(true)
+            };
+
+            var result = metadata.ToAdditionalProperties();
+
+            Assert.NotNull(result);
+            Assert.Equal(3, result!.Count);
+            Assert.True(result.TryGetValue("num", out var numObj));
+            Assert.True(result.TryGetValue("str", out var strObj));
+            Assert.True(result.TryGetValue("bool", out var boolObj));
+            var numJe = Assert.IsType<JsonElement>(numObj);
+            var strJe = Assert.IsType<JsonElement>(strObj);
+            var boolJe = Assert.IsType<JsonElement>(boolObj);
+            Assert.Equal(42, numJe.GetInt32());
+            Assert.Equal("value", strJe.GetString());
+            Assert.True(boolJe.GetBoolean());
+        }
+
+        [Fact]
+        public void ToA2AMetadata_ReturnsNullForNullAdditionalProperties()
+        {
+            AdditionalPropertiesDictionary? additionalProperties = null;
+            var result = additionalProperties.ToA2AMetadata();
+            Assert.Null(result);
+        }
+
+        [Fact]
+        public void ToA2AMetadata_ReturnsNullForEmptyAdditionalProperties()
+        {
+            var additionalProperties = new AdditionalPropertiesDictionary();
+            var result = additionalProperties.ToA2AMetadata();
+            Assert.Null(result);
+        }
+
+        [Fact]
+        public void ToA2AMetadata_ConvertsAdditionalPropertiesToMetadata()
+        {
+            var additionalProperties = new AdditionalPropertiesDictionary
+            {
+                ["num"] = 42,
+                ["str"] = "value",
+                ["bool"] = true
+            };
+
+            var result = additionalProperties.ToA2AMetadata();
+
+            Assert.NotNull(result);
+            Assert.Equal(3, result!.Count);
+            Assert.True(result.TryGetValue("num", out var numJe));
+            Assert.True(result.TryGetValue("str", out var strJe));
+            Assert.True(result.TryGetValue("bool", out var boolJe));
+            Assert.Equal(42, numJe.GetInt32());
+            Assert.Equal("value", strJe.GetString());
+            Assert.True(boolJe.GetBoolean());
+        }
+
+        [Fact]
+        public void ToA2AMetadata_HandlesJsonElementValues()
+        {
+            var additionalProperties = new AdditionalPropertiesDictionary
+            {
+                ["nested"] = JsonSerializer.SerializeToElement(new { key = "val" })
+            };
+
+            var result = additionalProperties.ToA2AMetadata();
+
+            Assert.NotNull(result);
+            Assert.Single(result!);
+            Assert.True(result.TryGetValue("nested", out var nestedJe));
+            Assert.Equal(JsonValueKind.Object, nestedJe.ValueKind);
+            Assert.Equal("val", nestedJe.GetProperty("key").GetString());
+        }
+
+        [Fact]
+        public void RoundTrip_ToA2AMetadata_And_ToAdditionalProperties()
+        {
+            var originalProps = new AdditionalPropertiesDictionary
+            {
+                ["number"] = 123,
+                ["text"] = "hello"
+            };
+
+            var metadata = originalProps.ToA2AMetadata();
+            Assert.NotNull(metadata);
+
+            var restoredProps = metadata.ToAdditionalProperties();
+            Assert.NotNull(restoredProps);
+            Assert.Equal(2, restoredProps!.Count);
+
+            // Values are now JsonElements after the round trip
+            Assert.True(restoredProps.TryGetValue("number", out var numObj));
+            Assert.True(restoredProps.TryGetValue("text", out var textObj));
+            var numJe = Assert.IsType<JsonElement>(numObj);
+            var textJe = Assert.IsType<JsonElement>(textObj);
+            Assert.Equal(123, numJe.GetInt32());
+            Assert.Equal("hello", textJe.GetString());
+        }
+    }
+}