.NET [Breaking] Simplify and Refactor ChatclientAgentOptions Ctor + Instructions

[rogerbarreto]

Motivation and Context

• Fixes .NET; Setting tools in ChatClientAgentOptions constructor, while also providing a new ChatOptions override the given tools/instructions #1453

Duplicated "Instructions" options

Context

Before Microsoft.Extensions.AI.ChatOptions had the Instructions property we added this property into the AgentOptions.Instructions

In the past months the chatOptions.Instructions property was added

And now we have agentOptions.Instructions serving the same purpose of agentOptions.ChatOptions.Instructions when configuring the ChatClientAgent which is not ideal.

As a first step to simplify, the problem above this PR updates options.Instructions to pointing to a single reference: e.g: agentOptions.Instructions => agentOptions.ChatOptions.Instructions.

Note

We may consider the full removal of the options.Instructions in favor of the options.ChatOptions.Instructions as a next step, happy to get some input from community.

[Copilot]

Pull Request Overview

Refactors ChatClientAgentOptions to unify Instructions storage within ChatOptions and updates usages across tests and samples.

• Removes the parameterized constructor and introduces an Instructions proxy to ChatOptions.
• Adjusts instruction merging logic in ChatClientAgent and updates related tests and samples.
• Updates tests but introduces some mismatches between test names, assertions, and missing coverage of new instruction propagation behavior.

Reviewed Changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgentOptions.cs	Refactors options: removes ctor, proxies Instructions to internal ChatOptions, adds cloning and conditional preservation logic.
dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs	Adjusts request instruction merging, reorders initialization assignments.
dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgentOptionsTests.cs	Rewrites tests to use object initializers; adds new scenarios but leaves some assertions incomplete and one test name inconsistent with its setup.
dotnet/tests/Microsoft.Agents.AI.UnitTests/ChatClient/ChatClientAgentTests.cs	Updates expectation: ChatOptions now always present when instructions provided.
dotnet/samples/*/Program.cs	Replaces removed constructor overload usages with object initializer pattern for Instructions and ChatOptions.
dotnet/agent-framework-dotnet.slnx	Removes SemanticKernelMigration folder reference from solution.

[MithrilMan]

any chance this PR can help having custom options so that we can use gemini with the openai compatibility API
https://ai.google.dev/gemini-api/docs/openai

and use custom options like you see in the Thinking section of their guide
https://ai.google.dev/gemini-api/docs/openai#thinking

where it is even possible to disable thinking at all or even obtain thinking tokens?

curl "https://generativelanguage.googleapis.com/v1beta/openai/chat/completions" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer GEMINI_API_KEY" \
-d '{
    "model": "gemini-2.5-flash",
      "messages": [{"role": "user", "content": "Explain to me how AI works"}],
      "extra_body": {
        "google": {
           "thinking_config": {
             "include_thoughts": true
           }
        }
      }
    }'

[westey-m]

@MithrilMan, any options that are supported by the OpenAI SDK can be provided. ChatOptions allows you to provide the options for the underlying service via the RawRepresentationFactory property, whether that be chat completion, responses, or any other service.

See here for example where it is providing reasoning options for responses via ChatOptions.RawRepresentationFactory:
https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/GettingStarted/AgentWithOpenAI/Agent_OpenAI_Step02_Reasoning/Program.cs#L18
(Note that chat options can also be set on ChatClientAgentOptions.ChatOptions, it doesn't have to be via ChatClientBuilder.ConfigureOptions).

See e.g. for responses, this is the options object, and it does have some reasoning settings:
https://github.com/openai/openai-dotnet/blob/main/src/Custom/Responses/ResponseCreationOptions.cs#L46

[MithrilMan]

@westey-m Yeah I saw that but the problem is that google offers more control over thinking that OpenAI doesn't.
E.g. on google you can switch off thinking but OpenAI doesn't have an option for ResponseReasoningEffortLevel of none.

Also in the documentation I linked, they show how you can set specific thinking budget (something OpenAI doesn't) and how to receive thinking tokens to see the internal thinking process of the LLM.

I understand that you can't add explicit value on OpenAI options that the OpenAI doesn't handle, but you could allow custom values that the user can set manually

Of course would be better to have a specific gemini client with its option

[westey-m]

I understand that you can't add explicit value on OpenAI options that the OpenAI doesn't handle, but you could allow custom values that the user can set manually

@MithrilMan, definitely open an issue in the OpenAI SDK repo with your requirement: https://github.com/openai/openai-dotnet.
We are building on top of that, so even supporting the ability to pass unofficial values is something that needs to be supported in the OpenAI SDK.

[MithrilMan]

@westey-m I've the feeling it would be something they don't have the incentive in doing it, since it would mean supporting potentially competitors.

Anyway does your reply means you are not gonna support gemini as first citizen, with dedicated client api classes?

[markwallace-microsoft]

@westey-m I've the feeling it would be something they don't have the incentive in doing it, since it would mean supporting potentially competitors.

Anyway does your reply means you are not gonna support gemini as first citizen, with dedicated client api classes?

For Gemini you can reuse the Semantic Kernel GoogleAIGeminiChatCompletionService which can be converted to an IChatClient and used with ChatClientAgent.

We are working to push the IChatClient implementations into existing client SDK's or M.E.AI.