.NET: [BREAKING] Clarify A2A agent run modes

[SergeyMenshykh]

Motivation & Context

A2A hosting exposes AgentRunMode to control what an agent returns to the caller: an AgentMessage or an AgentTask. The modes were named after a mechanism that no longer drives that decision.

The names — DisallowBackground, AllowBackgroundIfSupported, and AllowBackgroundWhen — imply that the mode controls how the underlying agent executes and that returning a task depends on agent capability. The handler no longer works that way: it consumes the agent through RunStreamingAsync and builds and manages the AgentTask itself. The response shape therefore depends only on the configured mode, never on whether the hosted agent supports background responses.

Since the handler works with any AIAgent, the old terminology is misleading: it suggests that some agents cannot be hosted in task mode and describes capability negotiation that does not occur. This change renames the modes to describe the A2A artifact returned by the hosting layer while leaving the underlying agent execution options unchanged.

Description & Review Guide

• What are the major changes?
  • Rename the run modes to ReturnMessage, ReturnTask, and ReturnTaskWhen.
  • Rename the internal decision method to ShouldReturnTaskAsync.
  • Update the corresponding tests and documentation to describe A2A response shape rather than background execution.
• What is the impact of these changes?
  • This is a breaking API rename for consumers configuring A2A hosting.
  • Message responses remain aggregated into a single A2A message, while task responses continue to use the A2A task lifecycle.
  • The mode no longer implies capability negotiation with the underlying AIAgent.
• What do you want reviewers to focus on?
  • Whether the renamed modes clearly communicate the A2A response behavior.
  • Whether the updated terminology consistently separates A2A response shape from underlying agent execution.

Related Issue

Fixes #

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[Copilot]

🟡 Changes recommended

Message-mode tests will fail, and the claimed interrupted-stream resumption behavior is not implemented.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Clarifies A2A run modes by naming them after the returned artifact and configuring task responses for background operation support.

Changes:

• Renames modes to ReturnMessage, ReturnTask, and ReturnTaskWhen.
• Enables AllowBackgroundResponses for task responses.
• Updates related tests and documentation.

File summaries

File	Summary
dotnet/tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/AgentRunModeTests.cs	Updates renamed-mode tests.
dotnet/tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/A2AServerServiceCollectionExtensionsTests.cs	Updates service registration tests.
dotnet/tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/A2AEndpointRouteBuilderExtensionsTests.cs	Updates endpoint configuration tests.
dotnet/tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/A2AAgentHandlerTests.cs	Updates handler expectations and terminology.
dotnet/src/Microsoft.Agents.AI.Hosting.A2A/AgentRunMode.cs	Renames and documents response modes.
dotnet/src/Microsoft.Agents.AI.Hosting.A2A/A2AServerServiceCollectionExtensions.cs	Updates the default run mode.
dotnet/src/Microsoft.Agents.AI.Hosting.A2A/A2AServerRegistrationOptions.cs	Documents the renamed default.
dotnet/src/Microsoft.Agents.AI.Hosting.A2A/A2AAgentHandler.cs	Configures response behavior, but incorrectly sets message mode to false instead of null and lacks continuation-token persistence and consumption required for stream resumption.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 2
• Review effort level: Balanced

---

💡 Add a code-review agent skill for context-aware, tailored reviews. Learn more in the docs.

[github-actions]

MAF Automated Review — Iteration 1

Result: Findings reported
Scope: full PR (2 commit(s)): c9c3c0c76ec8, 31d517a9ba79
Model: gpt-5.6-sol-fast

Overview

The rename makes the response-artifact contract clearer, keeps message mode as the default, and retains strong terminal-state and session-save handling around task execution. However, coupling every task response to provider background mode changes chat-history behavior, permits abandoned provider work, and leaves dynamic continuation responses inconsistent with the new public contract.

Reviewed the supplied pull-request change set across correctness, security/reliability, architecture, and failure behavior.
3 verified findings remained after source verification (3 medium) across 1 file. Details are attached to the affected lines below.

Affected areas: dotnet/src/Microsoft.Agents.AI.Hosting.A2A/A2AAgentHandler.cs