.NET: [Breaking] Change AgentRunOptions.AllowBackgroundResponses from bool? to bool

[Copilot]

Motivation and Context

Nullable types typically signal "not set, use implementation default." For background responses, this semantic is undesirable -consumers must explicitly opt-in to handle asynchronous operations.

Contributes to: #2542

Description

Changed AgentRunOptions.AllowBackgroundResponses from bool? to bool. Default value is now false, requiring explicit opt-in.

Core Changes:

• AgentRunOptions.cs: Property type changed from bool? to bool
• ChatClientAgent.cs: Updated null-check logic from is not null to == true

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? If yes, add "[BREAKING]" prefix to the title of the PR.

Original prompt

Change type of AgentRunOptions.AllowBackgroundResponses property from bool? to bool to address this feedback - "Typically we use null to mean "not set, use impl's default"... but that's not desirable here, as a consumer shouldn't have to be prepared to handle background responses unless they opt in. So just having bool rather than bool? here might be warranted."

---

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

[Copilot]

Pull request overview

This PR changes the AgentRunOptions.AllowBackgroundResponses property from bool? to bool, eliminating the ambiguous null state and requiring explicit opt-in for background responses functionality.

Key Changes:

• Property type changed from nullable to non-nullable boolean with false as the default
• Updated condition logic to check for explicit true value instead of null checking

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
dotnet/src/Microsoft.Agents.AI.Abstractions/AgentRunOptions.cs	Changed AllowBackgroundResponses property type from bool? to bool
dotnet/src/Microsoft.Agents.AI/ChatClient/ChatClientAgent.cs	Updated condition from is not null to == true to check if background responses are enabled

[Copilot]

The condition logic doesn't properly handle the case where AllowBackgroundResponses is explicitly set to false in AgentRunOptions.

With the change from bool? to bool, there's no way to distinguish between "not set" (default false) and "explicitly set to false". The current condition agentRunOptions?.AllowBackgroundResponses == true only enters the block when the value is true, meaning that an explicit false value won't be propagated to chatOptions unless ContinuationToken is also set.

This creates an inconsistency: if a user wants to override a true value from ChatOptions by setting AllowBackgroundResponses = false in AgentRunOptions, it will only work if they also provide a ContinuationToken. Without the ContinuationToken, the override won't take effect.

The test RunAsyncPrioritizesBackgroundResponsesPropertiesFromAgentRunOptionsOverOnesFromChatOptionsAsync validates that false should override true, but it only passes because it also sets ContinuationToken.

Consider either: (1) Always apply background response properties when agentRunOptions is not null, or (2) Revert to bool? to maintain the ability to distinguish "not set" from "explicitly false", or (3) Add a separate flag to indicate whether the property was explicitly set.

[SergeyMenshykh]

This change breaks the override functionality that allows providing the property via chat options and being able to override it via agent run options if the property is provided in the run options. This change makes it impossible because whatever is specified in the chat options will always be overridden by the value from the agent run options. So, for this scenario, having a third state (null) for the property is beneficial.

static ChatOptions? ApplyBackgroundResponsesProperties(ChatOptions? chatOptions, AgentRunOptions? agentRunOptions)
{
    //if (agentRunOptions?.AllowBackgroundResponses is not null || agentRunOptions?.ContinuationToken is not null)
    if (agentRunOptions is not null)
    {
        chatOptions ??= new ChatOptions();
        chatOptions.AllowBackgroundResponses = agentRunOptions.AllowBackgroundResponses;
        chatOptions.ContinuationToken = agentRunOptions.ContinuationToken;
    }
    return chatOptions;
}