.NET: Consider adding AdditionalProperties to AIAgent

Being able to annotate agents with additional metadata could be very helpful in driving an app powered by them. Some scenarios:

Agent requires user-authorized cloud storage (i.e. Google Drive or OneDrive): the app could detect this in a generic fashion by inspecting an agent's AdditionalProperties and trigger auth flow as needed.
Agent requires payment: the app could detect this, check user's balance and trigger payment workflows as needed.
Agent is in beta: app could hide these from lists, render them with a beta label in a catalog, etc.
Agent has icon: ditto, for improved display in apps
Agent is unlisted: agent should not be shown but it's available if users talk to it explicitly (i.e. via AGENT, Inc. (@agent) mention)
Agent is whitelist-only: agent requires an explicit opt-in by an admin for the current user

And so on.

Proposal is to just add AdditionalProperties like AgentRunOptions/ChatOptions have already, but at the agent level too.

While adding AdditionalProperties to AIAgent certainly has benefits it can also lead to confusion. E.g. there may be an expectation that these properties are passed down the stack where possible or users may expect the opposite. E.g. ChatClientAgent can pass AdditionalProperties to ChatClient. It does today for AgentRunOptions.AdditionalProperties, which makes sense since it is part of the run. Some users may expect any values on AIAgent.AdditionalProperties to also be used for each run and passed to ChatClient via ChatOptions.AdditionalProperties. On the other hand, some users may not want that behavior, since it may leak purely descriptive metadata to an underlying service.

Since we don't want to introduce confusion around this, our recommendation is to just use an agent wrapper object that also includes AdditionalProperties, e.g.:

public class AgentWithMetadata
{
    public required AIAgent Agent { get; init; }
    public AdditionalPropertiesDictionary? AdditionalProperties { get; set; }
}

Navigation Menu

Repository navigation

.NET: Consider adding AdditionalProperties to AIAgent #2131

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

.NET: Consider adding AdditionalProperties to AIAgent #2131

Description

Activity

westey-m commented on Feb 24, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions