.NET: [Breaking] Migrate A2A agent and hosting to A2A SDK v1

[SergeyMenshykh]

Summary

Migrate the .NET A2A agent and hosting packages from A2A SDK 0.3.4-preview to 1.0.0-preview2. This is a comprehensive update that reworks the agent, hosting, and extension APIs to align with the v1 SDK, adds SSE stream reconnection support, and reorganizes samples.

What Changed

Core Agent (Microsoft.Agents.AI.A2A)

• Refactored A2AAgent for v1 SDK APIs — updated message/task handling and streaming logic.
• Added SSE stream reconnection support using continuation tokens, allowing recovery from stream interruptions without losing progress.
• Updated A2AAgentCardExtensions and A2ACardResolverExtensions to use A2AClientFactory.Create() for client creation and accept an optional A2AClientOptions for protocol binding preference.
• Updated A2AClientExtensions to operate on IA2AClient interface instead of concrete A2AClient.

Hosting (Microsoft.Agents.AI.Hosting.A2A / .AspNetCore)

• Added: A2AAgentHandler — new handler aligned with v1 SDK hosting model.
• Added: A2AServerRegistrationOptions — configuration for server registration.
• Added: A2AServerServiceCollectionExtensions — consolidated DI registration for A2A servers.
• Added: A2AEndpointRouteBuilderExtensions — protocol-specific endpoint mapping methods.
• Removed: EndpointRouteBuilderExtensions (replaced by A2AEndpointRouteBuilderExtensions).
• Removed: AIAgentExtensions (logic consolidated into A2AServerServiceCollectionExtensions).

Samples

• Moved A2A samples from samples/04-hosting/A2A/ to samples/02-agents/A2A/.
• New: A2AAgent_ProtocolSelection — demonstrates protocol selection.
• New: A2AAgent_StreamReconnection — demonstrates SSE stream reconnection.
• Updated A2AClientServer, AgentWebChat, and A2AAgent_PollingForTaskCompletion to use the new APIs.

Closes:

• .NET: [A2A] Support for JSON+HTTP #3915
• .NET: Migrate AF A2AAgent and A2A Hosting to the latest A2A SDK #4815

[Copilot]

Pull request overview

Migrates the .NET A2A agent + hosting layers to align with A2A SDK 1.0.0-preview2, including updated request/response models, hosting registration/mapping APIs, and refreshed samples/tests reflecting v1 behaviors (including stream reconnection patterns).

Changes:

• Update core A2A agent + extension APIs to v1 SDK types (IA2AClient, SendMessageRequest/Response, StreamResponse, SupportedInterfaces, etc.).
• Replace legacy hosting mapping/extensions with AddA2AServer(...) registration + protocol-specific endpoint mapping (MapA2AHttpJson, MapA2AJsonRpc) and a new A2AAgentHandler.
• Reorganize/extend samples and significantly expand/modernize unit tests for the new API surface.

Reviewed changes

Copilot reviewed 50 out of 54 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
dotnet/tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/Converters/MessageConverterTests.cs	Updates converter tests for v1 request/message types.
dotnet/tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/AgentRunModeTests.cs	Adds unit tests for the new/updated AgentRunMode behavior.
dotnet/tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/AIAgentExtensionsTests.cs	Removes tests tied to deleted legacy hosting extensions.
dotnet/tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/A2AIntegrationTests.cs	Removes integration tests tied to the old hosting surface.
dotnet/tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/A2AEndpointRouteBuilderExtensionsTests.cs	Updates tests for new endpoint mapping + server registration APIs.
dotnet/tests/Microsoft.Agents.AI.Hosting.A2A.UnitTests/A2AAgentHandlerTests.cs	Adds coverage for the new A2AAgentHandler execution/cancel flows.
dotnet/tests/Microsoft.Agents.AI.A2A.UnitTests/Microsoft.Agents.AI.A2A.UnitTests.csproj	Adjusts test TFMs to match updated dependencies/compatibility.
dotnet/tests/Microsoft.Agents.AI.A2A.UnitTests/Extensions/ChatMessageExtensionsTests.cs	Updates message conversion tests for v1 Part model.
dotnet/tests/Microsoft.Agents.AI.A2A.UnitTests/Extensions/A2AClientExtensionsTests.cs	Adds tests ensuring extensions work on IA2AClient.
dotnet/tests/Microsoft.Agents.AI.A2A.UnitTests/Extensions/A2ACardResolverExtensionsTests.cs	Updates card resolver tests for SupportedInterfaces + protocol selection options.
dotnet/tests/Microsoft.Agents.AI.A2A.UnitTests/Extensions/A2AArtifactExtensionsTests.cs	Updates artifact conversion tests for new Part creation APIs.
dotnet/tests/Microsoft.Agents.AI.A2A.UnitTests/Extensions/A2AAgentTaskExtensionsTests.cs	Updates task conversion tests for v1 status/task types.
dotnet/tests/Microsoft.Agents.AI.A2A.UnitTests/Extensions/A2AAgentCardExtensionsTests.cs	Expands tests for protocol binding selection and error cases.
dotnet/tests/Microsoft.Agents.AI.A2A.UnitTests/Extensions/A2AAIContentExtensionsTests.cs	Updates AIContent→A2A part conversion tests for v1 part model.
dotnet/src/Microsoft.Agents.AI.Hosting.A2A/Converters/MessageConverter.cs	Switches message conversion to v1 SendMessageRequest model.
dotnet/src/Microsoft.Agents.AI.Hosting.A2A/AgentRunMode.cs	Fixes default/dynamic run-mode decision semantics and docs.
dotnet/src/Microsoft.Agents.AI.Hosting.A2A/AIAgentExtensions.cs	Removes legacy hosting extension entrypoints.
dotnet/src/Microsoft.Agents.AI.Hosting.A2A/A2AServerServiceCollectionExtensions.cs	Introduces AddA2AServer DI registration keyed by agent name.
dotnet/src/Microsoft.Agents.AI.Hosting.A2A/A2AServerRegistrationOptions.cs	Adds options object for A2A server registration configuration.
dotnet/src/Microsoft.Agents.AI.Hosting.A2A/A2ARunDecisionContext.cs	Updates run-decision context to v1 RequestContext input.
dotnet/src/Microsoft.Agents.AI.Hosting.A2A/A2AAgentHandler.cs	Adds new handler bridging AIAgent to A2A v1 hosting model.
dotnet/src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/Microsoft.Agents.AI.Hosting.A2A.AspNetCore.csproj	Adjusts packaging/warnings to keep Hosting.A2A transitively referenced.
dotnet/src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/EndpointRouteBuilderExtensions.cs	Removes old monolithic MapA2A endpoint mapping extensions.
dotnet/src/Microsoft.Agents.AI.Hosting.A2A.AspNetCore/A2AEndpointRouteBuilderExtensions.cs	Adds protocol-specific endpoint mapping (HTTP+JSON vs JSON-RPC).
dotnet/src/Microsoft.Agents.AI.A2A/Microsoft.Agents.AI.A2A.csproj	Updates TFMs to align with the repo’s core target frameworks.
dotnet/src/Microsoft.Agents.AI.A2A/Extensions/ChatMessageExtensions.cs	Updates chat message conversion to v1 Message/Role.
dotnet/src/Microsoft.Agents.AI.A2A/Extensions/A2AClientExtensions.cs	Moves extension surface from A2AClient to IA2AClient.
dotnet/src/Microsoft.Agents.AI.A2A/Extensions/A2ACardResolverExtensions.cs	Adds A2AClientOptions support for protocol binding preference.
dotnet/src/Microsoft.Agents.AI.A2A/Extensions/A2AAgentCardExtensions.cs	Switches client creation to A2AClientFactory.Create with options.
dotnet/src/Microsoft.Agents.AI.A2A/A2AAgentLogMessages.cs	Adds log message for SubscribeToTask→GetTask fallback path.
dotnet/src/Microsoft.Agents.AI.A2A/A2AAgent.cs	Migrates to v1 SDK APIs, adds SubscribeToTask fallback handling, updates streaming event handling.
dotnet/samples/README.md	Updates sample category descriptions after A2A sample move.
dotnet/samples/05-end-to-end/AgentWebChat/AgentWebChat.Web/A2AAgentClient.cs	Updates web chat client for v1 SendMessageResponse union model.
dotnet/samples/05-end-to-end/AgentWebChat/AgentWebChat.AgentHost/Program.cs	Switches hosting to AddA2AServer + MapA2AHttpJson endpoint mapping.
dotnet/samples/05-end-to-end/A2AClientServer/A2AServer/Program.cs	Updates server sample to new registration + mapping model and well-known card mapping.
dotnet/samples/05-end-to-end/A2AClientServer/A2AServer/HostAgentFactory.cs	Updates agent card creation for SupportedInterfaces and multi-url support.
dotnet/samples/05-end-to-end/A2AClientServer/A2AClient/Program.cs	Simplifies output handling using AgentResponse.Text.
dotnet/samples/02-agents/README.md	Adds A2A section entry under 02-agents.
dotnet/samples/02-agents/A2A/README.md	Fixes links and lists new A2A samples.
dotnet/samples/02-agents/A2A/A2AAgent_StreamReconnection/README.md	Adds documentation for stream reconnection sample.
dotnet/samples/02-agents/A2A/A2AAgent_StreamReconnection/Program.cs	Adds sample demonstrating continuation-token-based stream reconnection.
dotnet/samples/02-agents/A2A/A2AAgent_StreamReconnection/A2AAgent_StreamReconnection.csproj	Adds project for the new stream reconnection sample.
dotnet/samples/02-agents/A2A/A2AAgent_ProtocolSelection/README.md	Adds documentation for protocol selection sample.
dotnet/samples/02-agents/A2A/A2AAgent_ProtocolSelection/Program.cs	Adds sample demonstrating A2AClientOptions.PreferredBindings usage.
dotnet/samples/02-agents/A2A/A2AAgent_ProtocolSelection/A2AAgent_ProtocolSelection.csproj	Adds project for the protocol selection sample.
dotnet/samples/02-agents/A2A/A2AAgent_PollingForTaskCompletion/README.md	Adds documentation for polling-for-completion sample.
dotnet/samples/02-agents/A2A/A2AAgent_PollingForTaskCompletion/Program.cs	Updates polling sample to explicitly enable background responses.
dotnet/samples/02-agents/A2A/A2AAgent_PollingForTaskCompletion/A2AAgent_PollingForTaskCompletion.csproj	Normalizes TFM property name and removes unnecessary package reference.
dotnet/samples/02-agents/A2A/A2AAgent_AsFunctionTools/README.md	Adds documentation for A2A-as-tools sample under new location.
dotnet/samples/02-agents/A2A/A2AAgent_AsFunctionTools/Program.cs	Adds sample wiring A2A agent skills into function tools for another agent.
dotnet/samples/02-agents/A2A/A2AAgent_AsFunctionTools/A2AAgent_AsFunctionTools.csproj	Adds project for A2A-as-tools sample under new location.
dotnet/agent-framework-dotnet.slnx	Moves A2A samples folder and adds new sample projects to the solution.
dotnet/Directory.Packages.props	Bumps A2A + related dependency versions to match SDK v1 requirements.

[github-actions]

Automated Code Review

Reviewers: 4 | Confidence: 86%

✓ Correctness

No actionable issues found in this dimension.

✓ Security Reliability

The changes are well-structured with proper input validation, async patterns, resource management, and cancellation support. No blocking security or reliability issues were found. Minor suggestions relate to defensive error handling edge cases in the new A2AgentHandler and continuation token deserialization.

✓ Test Coverage

Existing tests (on the base branch) reference old APIs (MapA2A, typeof(A2AClient), MessageSendParams) that are changed or removed by this PR. The AllowBackgroundResponses → ReturnImmediately mapping and ContinuationToken on streaming task updates are new behaviors without test coverage. Test files may appear in later review chunks, but the gaps are noted here for tracking. The new tests are well-structured and cover important new behaviors: IA2AClient constructor, streaming with continuation tokens (SubscribeToTask with fallback to GetTask), ReturnImmediately/blocking configuration, preferred protocol bindings, and GetService for IA2AClient vs concrete A2AClient. Test assertions are meaningful (not just no-exception checks) and the mock stub was properly extended to support new error simulation scenarios. The only minor gap is that the AgentRunMode fallback path (line 82) changed from true to false but remains unreachable through the public API and thus untestable without reflection. However, several test scenarios from the deleted AIAgentExtensionsTests.cs were not carried forward into the new files. Notably: (1) no test verifies that non-null RequestContext.Metadata is forwarded as AdditionalProperties to the agent — only the null-metadata path is tested; (2) the AIAgent overloads of MapA2AHttpJson/MapA2AJsonRpc and AddA2AServer(IServiceCollection, AIAgent) lost all argument-validation tests when AIAgentExtensionsTests was deleted; (3) MessageConverter.ToParts has no test coverage despite being exercised in production paths. The new A2AAgentHandlerTests are well-structured with meaningful assertions and proper mock setup, and AgentRunModeTests provides thorough equality/hashing/toString coverage.

✗ Design Approach

There is also a weaker API-design concern in the new ASP.NET mapping surface: it hard-codes a stub AgentCard, which pushes agent-card wiring out to separate manual setup and makes discovery behavior depend on implementation details of the hosting split. The other visible changes here look like API-shape and test updates rather than approach problems. I also see a smaller API-contract concern where the new AgentRunMode tests lock in value equality for dynamic modes even when their callbacks do opposite things.

Flagged Issues

• MapA2AHttpJson hard-codes a stub AgentCard, so the {path}/card endpoint loses the meaningful metadata and URL population that the previous MapA2A(..., AgentCard) flow provided. Wire the real AgentCard through the AddA2AServer/mapping API instead.

Suggestions

• In A2AAgentHandler.HandleTaskUpdateAsync, the catch(Exception) block calls failUpdater.FailAsync with the same cancellationToken. If the token is already cancelled, FailAsync could throw and mask the original exception. Consider using CancellationToken.None for the FailAsync call.
• In A2AContinuationToken.FromToken (line 55), reader.GetString()! uses the null-forgiving operator for the taskId value. If the JSON contains a null taskId, this silently becomes null and is only caught later by the constructor's Throw.IfNullOrEmpty. Add an explicit null check with a descriptive JsonException for better diagnostics.
• The new production classes A2AAgentHandler, SubscribeToTaskWithFallbackAsync, A2AServerServiceCollectionExtensions, and A2AEndpointRouteBuilderExtensions all lack test coverage. Each has significant branching or DI wiring logic that would only surface failures at runtime. See inline comments for per-class test scenarios.
• The AgentRunMode fallback at line 82 (changed from true to false) is unreachable through the public API. While the fix correctly aligns with the comment ('fall back to message behavior'), consider adding a code comment noting this is a defensive fallback.
• Add argument-validation tests for the AIAgent overloads of MapA2AHttpJson and MapA2AJsonRpc (null agent, null/whitespace agent.Name). The old AIAgentExtensionsTests covered these scenarios but was deleted without replacement.
• Add argument-validation tests for AddA2AServer(IServiceCollection, AIAgent, ...) — the overload at A2AServerServiceCollectionExtensions line 117 has null checks for services, agent, and agent.Name with no test coverage.
• Consider adding at least one test for MessageConverter.ToParts, which is used in A2AAgentHandler (lines 148, 170) to produce artifact and message parts. Currently only the reverse direction (ToChatMessages) is tested.

---

Automated review by SergeyMenshykh's agents

[github-actions]

Automated Code Review

Reviewers: 2 | Confidence: 89%

✗ Security Reliability

The new AgentRunModeTests.cs contains a test (Equals_AllowBackgroundWhen_DifferentDelegates_AreNotEqual) that will fail at runtime: it asserts two AllowBackgroundWhen instances with different delegates are not equal, but AgentRunMode.Equals (AgentRunMode.cs:86-87) only compares the internal _value string (both are "dynamic"), ignoring delegate identity. Either the implementation must be updated to compare delegates, or the test expectation is wrong. The MessageConverterTests updates (type renames to SendMessageRequest, Message, Role, Part) and new ToParts tests look sound. The deletion of EndpointRouteA2ABuilderExtensionsTests.cs removes 21 unit tests covering the 23 MapA2A production overloads with no replacement tests.

✗ Design Approach

The new endpoint/server split drops agent-card metadata from the A2A hosting abstraction and replaces it with a hard-coded stub, which makes discovery an opt-in side path instead of part of server registration. Separately, the IA2AClient refactor narows an existing compatibility surface by stopping A2Agent.GetService(typeof(A2AClient)) from resolving the client, even though the current public extension/tests still treat the concrete A2AClient as the contract. Moving A2Agent to work with IA2AClient is a reasonable direction, but the new tests explicitly codify that GetService(typeof(A2AClient)) now returns null. That changes an existing retrieval contract without a strong reason: callers that previously obtained the concrete client from A2Agent will break even when the underlying instance is still an A2AClient. The rest of the changes here mostly look like a straightforward SDK-shape migration and added coverage. The test split is headed in a better direction, but two parts of the new approach still miss the contract they claim to protect. The handler tests route null session-store cases through a helper that eagerly substitutes InMemoryAgentSessionStore, so those tests never exercise the production defaulting path at all. And the new AddA2AServer DI tests only prove that A2AServer can be resolved, not that keyed custom stores/handlers are actually wired through, so the main registration risk could still slip by. I also think dropping the only end-to-end agent-card URL test leaves an important cross-layer behavior unguarded. The added AgentRunMode and MessageConverter tests improve coverage of the new behavior, but deleting EndpointRouteA2ABuilderExtensionsTests leaves the ASP.NET entry-point layer largely unverified. The remaining coverage I found only exercises one happy-path card endpoint (A2AIntegrationTests.cs:22-83) plus lower-level AIAgentExtensions behavior, so the public MapA2A(...) overloads, their null-guard contracts, keyed-agent resolution, and configureTaskManager delegation in EndpointRouteBuilderExtensions.cs:36-377 are no longer directly protected.

Flagged Issues

• AgentRunModeTests.Equals_AllowBackgroundWhen_DifferentDelegates_AreNotEqual will fail: AgentRunMode.Equals (AgentRunMode.cs:86-87) only compares the _value string field, not the delegate. Both AllowBackgroundWhen instances have _value="dynamic", so Equals returns true, causing Assert.False(true) to throw. Either update AgentRunMode.Equals to include delegate identity or fix the test expectation.
• Removing EndpointRouteA2ABuilderExtensionsTests leaves the ASP.NET entry-point layer largely unverified. The public MapA2A(...) overloads in EndpointRouteBuilderExtensions.cs:36-377 perform distinct outer-layer work (keyed DI lookup, callback delegation, null guards), but the only remaining route-level coverage is a single integration happy path. Keep a slim set of focused unit tests for the route-builder layer alongside the integration test.

Suggestions

• Keep the internal field/constructor typed as IA2AClient if desired, but preserve GetService(typeof(A2AClient)) compatibility (or support both service types when the underlying instance is concrete).
• Keep one black-box HTTP test for agent-card URL population. That behavior spans endpoint mapping and AIAgentExtensions mutating agentCard.Url in OnAgentCardQuery, and deleting it removes the only end-to-end check of that contract.

---

Automated review by SergeyMenshykh's agents