Add ReasoningOptions to ChatOptions

[Copilot]

• Create ReasoningEffort enum with None, Low, Medium, High, ExtraHigh values
• Create ReasoningOutput enum with None, Summary, Full values (renamed Detailed → Full)
• Create ReasoningOptions class with Effort and Output properties
• Add Reasoning property to ChatOptions class
• Update ChatOptions copy constructor to clone Reasoning
• Update OpenAI Chat implementation to map ReasoningOptions
• Update OpenAI Responses implementation to map ReasoningOptions
• Update tests for ChatOptions
• Address PR feedback:
  • Remove [Experimental] attribute and add to stable JSON file
  • Remove ExtraHigh-specific remarks
  • Make Clone() method internal
  • Simplify ToOpenAIChatReasoningEffortLevel method
  • Revert DiagnosticIds.cs changes
  • Remove remarks from ChatOptions.Reasoning property
  • Update ReasoningEffort documentation with suggested text
  • Simplify "No reasoning effort" comment
  • Update ReasoningOptions documentation with suggested text
  • Remove explicit enum numbering from both enums
  • Add dedicated ReasoningOptionsTests for serialization/roundtripping
  • Add OpenAI unit tests for ReasoningOptions producing expected JSON
  • Rename ReasoningOutput.Detailed → ReasoningOutput.Full for clarity

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[API Proposal]: ChatOptions Reasoning</issue_title>
<issue_description>### Background and motivation

While we can use ChatOptions.RawRepresentationFactory to set the reasoning configuration of a request, things get complicated when different providers are supported by the IChatClient. Reasoning seems to be supported by most providers so we should start thinking about how to expose it in ChatOptions.

Here is a summary of how it works for different providers:

Provider	Reasoning	Comment
Claude	output_config={ "effort": "medium" } "thinking": { "type": "enabled", "budget_tokens": 10000 }	Enum: low, medium, high. Also supports thinking budget. Effort seems to be the new thing. Default is high
Gemini	thinking_config=types.ThinkingConfig(thinking_level="low") thinking_config=types.ThinkingConfig(thinking_budget=1024)	Enum: low, high. Also supports budget but the level is "recommended for Gemini 3 models and onwards". Default is dynamic.
Mistral	"prompt_mode": "reasoning"	reasoning is the default value. Can be set to null to disable it.
OpenAI	reasoning={"effort": "medium"}	Enum: none, minimal, low, medium, high, xhigh
xAI	reasoning_effort="high"	Enum: low, high
Amazon	??

API Proposal

public class Reasoning
{
    public static Reasoning None { get; }
    public static Reasoning Low { get; }
    public static Reasoning Medium { get; }
    public static Reasoning High { get; }
}

public class ChatOptions
{
    public Reasoning? Reasoning { get; set; }
}

Low/Medium/High with bool-based providers (Mistral)

None => disable
Low/Medium/High => enable

Default Value

If ChatOptions.Reasoning is null, the provider's default is used:

• Claude: high
• Gemini: dynamic thinking
• Mistral: true
• OpenAI: medium

API Usage

ChatResponse response = await chatClient.GetResponseAsync("Hi", new ChatOptions
{
    Reasoning = Reasoning.Medium,
});

Alternative Designs

Reasoning.FromBudget(int budget)

Mapping a budget to an enum (for OpenAI) is tricky. With Claude and Gemini moving to enums, I don't think we need to deal with budgets. This greatly simplify things.

Additional Property

Use an additional property. Though, my goal is to be able to use reasoning with all providers so I would rather add it to ChatOptions.

Risks

No response</issue_description>

<agent_instructions>Create a design something like this:

public sealed class ReasoningOptions
{
public ReasoningEffort? Effort { get; set; }
public ReasoningOutput? Output { get; set; }
}

public enum ReasoningEffort
{
    None = 0,
    Low = 1,
    Medium = 2,
    High = 3,
    ExtraHigh = 4,
}

public enum ReasoningOutput
{
    None = 0,
    Summary = 1,
    Detailed = 2,
}

public sealed partial class ChatOptions
{
    public ReasoningOptions? Reasoning { get; set; }
}

Update the abstractions and tests and ensure it's fully implemted as much as possible in the openai implementations, ignoring anything that can't be mapped (it's best effort) </agent_instructions>

Comments on the Issue (you are @copilot in this section)

• Fixes [API Proposal]: ChatOptions Reasoning #7192

---

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

Microsoft Reviewers: Open in CodeFlow

[stephentoub]

@copilot

[stephentoub]

cc: @PederHP

[Copilot]

Pull request overview

This PR adds reasoning configuration options to the ChatOptions class, enabling developers to control how much computational effort AI models should apply when generating responses and how reasoning content should be included.

Changes:

• Introduced ReasoningEffort enum (None, Low, Medium, High, ExtraHigh) and ReasoningOutput enum (None, Summary, Detailed) to the abstractions layer
• Added ReasoningOptions class with Effort and Output properties, plus internal Clone() method for copy semantics
• Integrated reasoning options into ChatOptions with proper cloning support in the copy constructor
• Implemented OpenAI-specific mappings in both OpenAIChatClient (reasoning effort only) and OpenAIResponsesChatClient (both effort and output)
• Added comprehensive test coverage including unit tests, JSON serialization tests, and integration tests that verify expected JSON output

Reviewed changes

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

Show a summary per file

File	Description
src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ReasoningEffort.cs	New enum defining reasoning effort levels (None, Low, Medium, High, ExtraHigh)
src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ReasoningOutput.cs	New enum defining reasoning output modes (None, Summary, Detailed)
src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ReasoningOptions.cs	New sealed class containing reasoning configuration with internal Clone() method
src/Libraries/Microsoft.Extensions.AI.Abstractions/ChatCompletion/ChatOptions.cs	Added Reasoning property and clone logic in copy constructor
src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIChatClient.cs	Maps ReasoningEffort to OpenAI ChatReasoningEffortLevel (ExtraHigh maps to High)
src/Libraries/Microsoft.Extensions.AI.OpenAI/OpenAIResponsesChatClient.cs	Maps both ReasoningEffort and ReasoningOutput to OpenAI Response API types
src/Libraries/Microsoft.Extensions.AI.Abstractions/Microsoft.Extensions.AI.Abstractions.json	API baseline manifest updated with new stable APIs
test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/ChatCompletion/ReasoningOptionsTests.cs	Comprehensive unit tests for ReasoningOptions including JSON serialization
test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/ChatCompletion/ChatOptionsTests.cs	Updated tests to verify Reasoning property and cloning behavior
test/Libraries/Microsoft.Extensions.AI.OpenAI.Tests/OpenAIChatClientTests.cs	Tests verifying correct JSON generation for reasoning effort in Chat API
test/Libraries/Microsoft.Extensions.AI.OpenAI.Tests/OpenAIResponseClientTests.cs	Tests verifying correct JSON generation for reasoning effort and output in Response API
test/Libraries/Microsoft.Extensions.AI.Abstractions.Tests/TestJsonSerializerContext.cs	Added JSON serialization support for new types