.NET: Add AdditionalProperties to AIAgent and surface in implementations

[Daniel Cazzulino (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 propertiespublicclassCustomAgent:AIAgent{publicoverrideAdditionalPropertiesDictionary?AdditionalProperties{get;}=new(){["requiresAuth"]=true,["beta"]=true,["icon"]="agent-icon.png"};}// ChatClientAgent with additional properties via optionsvaroptions=newChatClientAgentOptions{Name="MyAgent",AdditionalProperties=newAdditionalPropertiesDictionary{["beta"]=true,["requiresAuth"]=true}};varagent=newChatClientAgent(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 (Vijay-Nirmal)]

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

[Daniel Cazzulino (kzu)]

Vijay Nirmal (@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 (Vijay-Nirmal)]

Daniel Cazzulino (@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>

[Daniel Cazzulino (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).

[Daniel Cazzulino (kzu)]

Vijay Nirmal (@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

[Stephen Toub (stephentoub)]

westey (@westey-m), before proliferating AdditionalProperties further, I'd like to better understand how you see feature collections fitting in. Are you expecting to add Features to AIAgent, and if so, is there a reason to have both?

[Stephen Toub (stephentoub)]

We originally had AdditionalProperties on ChatClientMetadata, but removed it before it went stable because there wasn't an obvious need for it, and we've not had any requests for it since to my knowledge. It's unclear to me how/why someone consumes it. What's the use case for this here?

[Stephen Toub (stephentoub)]

westey (@westey-m), same question about features

[westey (westey-m)]

Closing, since we agreed that this can be done via a wrapper class if needed, and adding it to agent can cause confusion about how the properties will be used.