.NET: Add AdditionalProperties to AIAgent and surface in implementations

[kzu]

Motivation and Context

Implements the suggestion from #2131 to add AdditionalProperties to AIAgent for custom metadata annotations (e.g., authorization requirements, payment info, beta status, visibility controls, icons).

Description

This PR adds AdditionalProperties support to the AIAgent base class and surfaces it in the current implementations (ChatClientAgent, ChatClientAgentOptions, and AIAgentMetadata).

Changes

Core Implementation:

• AIAgent.cs: Added virtual AdditionalPropertiesDictionary? AdditionalProperties property
• AIAgentTests.cs: Added tests for default (null) and override behaviors

Implementation in ChatClientAgent:

• ChatClientAgentOptions.cs: Added AdditionalProperties property (get/set) and updated Clone() method to clone it
• ChatClientAgent.cs: Overrode AdditionalProperties property to return value from options
• AIAgentMetadata.cs: Added readonly AdditionalProperties property and updated constructor to receive it from options

Tests:

• ChatClientAgentOptionsTests.cs: Added 3 tests for AdditionalProperties functionality
• ChatClientAgentTests.cs: Added 3 tests verifying AdditionalProperties from options and metadata integration

Usage

// Custom agent with additional properties
public class CustomAgent : AIAgent
{
    public override AdditionalPropertiesDictionary? AdditionalProperties { get; } = new()
    {
        ["requiresAuth"] = true,
        ["beta"] = true,
        ["icon"] = "agent-icon.png"
    };
}

// ChatClientAgent with additional properties via options
var options = new ChatClientAgentOptions
{
    Name = "MyAgent",
    AdditionalProperties = new AdditionalPropertiesDictionary
    {
        ["beta"] = true,
        ["requiresAuth"] = true
    }
};
var agent = new ChatClientAgent(chatClient, options);
// agent.AdditionalProperties now returns the options' AdditionalProperties

Follows the same pattern as AgentRunOptions.AdditionalProperties and ChatOptions.AdditionalProperties.

Contribution Checklist

• The code builds clean without any errors or warnings
• The PR follows the Contribution Guidelines
• All unit tests pass, and I have added new tests where possible
• Is this a breaking change? No

Original prompt

Implement the suggestion from #2131

---

💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

[Copilot]

Pull Request Overview

This PR adds AdditionalProperties support to the AIAgent base class and its implementations, enabling custom metadata annotations on agents (e.g., authorization requirements, beta status, icons). The implementation follows the same pattern as existing AdditionalProperties in AgentRunOptions and ChatOptions.

• Added virtual AdditionalProperties property to AIAgent base class
• Surfaced the property through ChatClientAgent, ChatClientAgentOptions, and AIAgentMetadata
• Added comprehensive unit tests validating default null behavior, property assignment, cloning, and metadata integration

Reviewed Changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgent.cs	Added virtual AdditionalProperties property to base class
dotnet/src/Microsoft.Agents.AI.Abstractions/AIAgentMetadata.cs	Added readonly AdditionalProperties property and constructor parameter
dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentOptions.cs	Added AdditionalProperties property with get/set and updated Clone() method
dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs	Overrode AdditionalProperties to return value from options and passed to metadata constructor
dotnet/tests/Microsoft.Agents.AI.Abstractions.UnitTests/AIAgentTests.cs	Added tests for default null and override behaviors with new mock class
dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgentOptionsTests.cs	Added tests for default value, setter, and cloning behavior
dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgentTests.cs	Added tests verifying property from options and metadata integration

[Vijay-Nirmal]

@kzu A sample app (Or modifying a existing one) showcasing this "AdditionalProperties" would be helpful to understand the use case of this property

[kzu]

@Vijay-Nirmal the scenarios are explained in #2131 (each bullet is a property in the dictionary).

I have all those scenarios implemented with an in-house agent thingy that I want to replace with the agent framework. I could try to cook a fake sample, but those are all my real-world use cases.

[Vijay-Nirmal]

@kzu Sorry for back and forth, I am just trying to understand. Is this purely to store some additional Metadata in the main AIAgent object so that it can avoid create a AIAgent wrapper or custom tupe or a record like (AIAgent, Dictonary<string, object>)? if yes, I get the vision, personally I like these things to be strongly typed instead of Dictonary<string, object>

[kzu]

This approach follows the existing approach of adding these kinds of annotations to ChatOptions, AgentRunOptions and others. Makes them easy to extend without having to inherit (which is not even possible for ChatClientAgent which is sealed).

[kzu]

@Vijay-Nirmal here's an example of how this property makes it easier to have a more dynamic client based on agent metadata: kzu#3

Also, see this concrete example where I drive agent-framework from configuration (including VSCode-compatible custom agent markdown) where the additional metadata can be expressed simply and drive the user experience seamlessly: https://github.com/devlooped/AI/blob/main/sample/Server/notes.agent.md