Skip to content

Commit 08851e6

Browse files
SergeyMenshykhsemenshiCopilot
authored
.NET: Add gRPC protocol selection to the A2A sample (#9563)
Co-authored-by: SergeyMenshykh <[email protected]> Co-authored-by: Copilot App <[email protected]> Copilot-Session: 8c7bf38b-4be3-419a-b383-4ba1055fd003
1 parent 30bc5c1 commit 08851e6

8 files changed

Lines changed: 114 additions & 17 deletions

File tree

‎dotnet/Directory.Packages.props‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -122,6 +122,7 @@
122122
<!-- A2A -->
123123
<PackageVersion Include="A2A" Version="1.0.0-preview3" />
124124
<PackageVersion Include="A2A.AspNetCore" Version="1.0.0-preview3" />
125+
<PackageVersion Include="A2A.Grpc" Version="1.0.0-preview3" />
125126
<!-- MCP -->
126127
<PackageVersion Include="ModelContextProtocol" Version="2.2.0" />
127128
<PackageVersion Include="ModelContextProtocol.Extensions.Tasks" Version="2.2.0" />

‎dotnet/samples/02-agents/A2A/A2AAgent_ProtocolSelection/A2AAgent_ProtocolSelection.csproj‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010

1111
<ItemGroup>
1212
<PackageReference Include="A2A" />
13+
<PackageReference Include="A2A.Grpc" />
1314
</ItemGroup>
1415

1516
<ItemGroup>
Lines changed: 20 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,46 @@
11
// Copyright (c) Microsoft. All rights reserved.
22

3-
// This sample demonstrates how to select the A2A protocol binding (HTTP+JSON vs JSON-RPC) when
3+
// This sample demonstrates how to select the A2A protocol binding (HTTP+JSON, JSON-RPC, or gRPC) when
44
// creating an AIAgent from an A2A agent card using A2AClientOptions.PreferredBindings.
55

66
using A2A;
7+
using A2A.Grpc;
78
using Microsoft.Agents.AI;
89

910
var a2aAgentHost = Environment.GetEnvironmentVariable("A2A_AGENT_HOST") ?? throw new InvalidOperationException("A2A_AGENT_HOST is not set.");
1011

12+
// Possible values: "HTTP+JSON" (default), "JSONRPC", or "GRPC".
13+
var protocolBinding = Environment.GetEnvironmentVariable("A2A_PROTOCOL_BINDING") ?? ProtocolBindingNames.HttpJson;
14+
15+
// Register gRPC explicitly once during startup when using agent-card discovery.
16+
// Direct construction of an A2AGrpcClient does not require registration.
17+
if (string.Equals(protocolBinding, ProtocolBindingNames.Grpc, StringComparison.OrdinalIgnoreCase))
18+
{
19+
// Register A2AGrpcClient with the SDK factory so AsAIAgent() can use a card's gRPC interface.
20+
// The optional A2A.Grpc package does not register this binding automatically.
21+
A2AGrpcClientRegistration.Register();
22+
}
23+
1124
// Initialize an A2ACardResolver to get an A2A agent card.
1225
A2ACardResolver agentCardResolver = new(new Uri(a2aAgentHost));
1326

1427
// Get the agent card
1528
AgentCard agentCard = await agentCardResolver.GetAgentCardAsync();
1629

17-
// Use A2AClientOptions to explicitly select the HTTP+JSON protocol binding.
18-
// This tells the A2A client factory to prefer the HTTP+JSON interface when the agent card
30+
// Use A2AClientOptions to explicitly select the configured protocol binding.
31+
// This tells the A2A client factory to select only the configured interface when the agent card
1932
// advertises multiple supported interfaces.
2033
A2AClientOptions options = new()
2134
{
22-
PreferredBindings = [ProtocolBindingNames.HttpJson]
35+
PreferredBindings = [protocolBinding]
2336
};
2437

25-
// To prefer JSON-RPC instead, use:
26-
// A2AClientOptions options = new()
27-
// {
28-
// PreferredBindings = [ProtocolBindingNames.JsonRpc]
29-
// };
30-
3138
// Create an instance of the AIAgent for an existing A2A agent, using the specified protocol binding.
3239
AIAgent agent = agentCard.AsAIAgent(options: options);
3340

41+
// A gRPC client owns a channel; release it after the agent's final operation.
42+
using var clientLifetime = agent.GetService<IA2AClient>() as IDisposable;
43+
3444
// Invoke the agent and output the text result.
3545
AgentResponse response = await agent.RunAsync("Tell me a joke about a pirate.");
3646
Console.WriteLine(response);

‎dotnet/samples/02-agents/A2A/A2AAgent_ProtocolSelection/README.md‎

Lines changed: 67 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,15 @@
22

33
This sample demonstrates how to select the A2A protocol binding when creating an `AIAgent` from an A2A agent card.
44

5-
A2A agents can expose multiple interfaces with different protocol bindings (e.g., HTTP+JSON, JSON-RPC). By default, `AsAIAgent()` prefers HTTP+JSON with JSON-RPC as a fallback. This sample shows how to use `A2AClientOptions.PreferredBindings` to explicitly control which protocol binding is used.
5+
A2A agents can expose multiple interfaces with different protocol bindings (e.g., HTTP+JSON, JSON-RPC, gRPC). By default, `AsAIAgent()` selects the first HTTP+JSON or JSON-RPC interface listed in the agent card. This sample shows how to use `A2AClientOptions.PreferredBindings` to explicitly control which protocol binding is used.
6+
7+
The sample uses only the selected binding; it does not fall back to another protocol.
68

79
The sample:
810

911
- Connects to an A2A agent server specified in the `A2A_AGENT_HOST` environment variable
10-
- Configures `A2AClientOptions` to prefer the HTTP+JSON protocol binding
12+
- Selects the binding using `A2A_PROTOCOL_BINDING`, defaulting to HTTP+JSON
13+
- Explicitly registers the gRPC client factory when gRPC is selected
1114
- Creates an `AIAgent` from the resolved agent card using the specified binding
1215
- Sends a message to the agent and displays the response
1316

@@ -16,12 +19,73 @@ The sample:
1619
Before you begin, ensure you have the following prerequisites:
1720

1821
- .NET 10.0 SDK or later
19-
- An A2A agent server running and accessible via HTTP
22+
- An A2A agent server running and accessible via HTTP, with support for the selected binding
2023

2124
**Note**: These samples need to be run against a valid A2A server. If no A2A server is available, they can be run against the echo-agent that can be spun up locally by following the guidelines at: https://github.com/a2aproject/a2a-dotnet/blob/main/samples/AgentServer/README.md
2225

26+
The linked echo-agent does not expose gRPC. To select `GRPC`, use a server whose agent card lists a `GRPC` interface.
27+
2328
Set the following environment variable:
2429

2530
```powershell
2631
$env:A2A_AGENT_HOST="http://localhost:5000" # Replace with your A2A agent server host
2732
```
33+
34+
Optionally select a binding:
35+
36+
```powershell
37+
$env:A2A_PROTOCOL_BINDING="GRPC" # Or "HTTP+JSON" (default) or "JSONRPC"
38+
dotnet run
39+
```
40+
41+
## gRPC client setup
42+
43+
The sample already references `Microsoft.Agents.AI.A2A` and the SDK's `A2A.Grpc` package.
44+
The existing `A2AAgent` works with `A2AGrpcClient`; no additional framework package is needed.
45+
The base `Microsoft.Agents.AI.A2A` package does not bring in gRPC dependencies.
46+
47+
To add the same support to your own application:
48+
49+
```powershell
50+
dotnet add package Microsoft.Agents.AI.A2A --prerelease
51+
dotnet add package A2A.Grpc --prerelease
52+
```
53+
54+
For agent-card discovery, explicitly register the SDK's gRPC binding once during application startup:
55+
56+
```csharp
57+
using A2A;
58+
using A2A.Grpc;
59+
using Microsoft.Agents.AI;
60+
61+
A2AGrpcClientRegistration.Register();
62+
63+
var resolver = new A2ACardResolver(new Uri("https://agent.example.com/"));
64+
65+
AIAgent agent = await resolver.GetAIAgentAsync(
66+
options: new A2AClientOptions
67+
{
68+
PreferredBindings = [ProtocolBindingNames.Grpc]
69+
});
70+
71+
using var clientLifetime = agent.GetService<IA2AClient>() as IDisposable;
72+
73+
Console.WriteLine(await agent.RunAsync("Hello over gRPC!"));
74+
```
75+
76+
The agent card must list a `GRPC` interface. Discovery fetches the card over HTTP,
77+
then the client uses the gRPC endpoint listed in the card.
78+
79+
If you already know the gRPC endpoint, create the client directly. No registration is needed:
80+
81+
```csharp
82+
using var client = new A2AGrpcClient(new Uri("https://agent.example.com:5001"));
83+
84+
AIAgent agent = client.AsAIAgent(name: "Remote agent");
85+
86+
Console.WriteLine(await agent.RunAsync("Hello!"));
87+
```
88+
89+
Keep the client alive while using the agent and dispose it when finished; `A2AAgent` does not do this
90+
for you. Use `using var client` for a direct connection, or the `clientLifetime` pattern shown above
91+
for discovery.

‎dotnet/samples/02-agents/A2A/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@ See the README.md for each sample for the prerequisites for that sample.
1717
|[A2A Agent Skills](./A2AAgent_Skills/)|This sample demonstrates how to expose each skill advertised by an A2A agent as a separate function tool.|
1818
|[A2A Agent Polling For Task Completion](./A2AAgent_PollingForTaskCompletion/)|This sample demonstrates how to poll for long-running task completion using continuation tokens with an A2A agent.|
1919
|[A2A Agent Stream Reconnection](./A2AAgent_StreamReconnection/)|This sample demonstrates how to reconnect to an A2A agent's streaming response using continuation tokens, allowing recovery from stream interruptions.|
20-
|[A2A Agent Protocol Selection](./A2AAgent_ProtocolSelection/)|This sample demonstrates how to select the A2A protocol binding (HTTP+JSON vs JSON-RPC) when creating an AIAgent from an A2A agent card using A2AClientOptions.|
20+
|[A2A Agent Protocol Selection](./A2AAgent_ProtocolSelection/)|This sample demonstrates how to select HTTP+JSON, JSON-RPC, or gRPC when creating an AIAgent from an A2A agent card using A2AClientOptions.|
2121

2222
## Running the samples from the console
2323

‎dotnet/src/Microsoft.Agents.AI.A2A/A2AAgent.cs‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,9 +19,12 @@ namespace Microsoft.Agents.AI.A2A;
1919
/// Represents an <see cref="AIAgent"/> that can interact with remote agents that are exposed via the A2A protocol
2020
/// </summary>
2121
/// <remarks>
22-
/// This agent supports only messages as a response from A2A agents.
23-
/// Support for tasks will be added later as part of the long-running
24-
/// executions work.
22+
/// This agent supports messages, tasks, and streaming updates as responses from A2A agents.
23+
/// <para>
24+
/// For a direct gRPC connection, also reference the SDK's <c>A2A.Grpc</c> package
25+
/// and supply an <c>A2A.Grpc.A2AGrpcClient</c>.
26+
/// The caller owns the supplied client and must dispose it if it implements <see cref="IDisposable"/>.
27+
/// </para>
2528
/// </remarks>
2629
public sealed class A2AAgent : AIAgent
2730
{

‎dotnet/src/Microsoft.Agents.AI.A2A/Extensions/A2AAgentCardExtensions.cs‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
// Copyright (c) Microsoft. All rights reserved.
22

3+
using System;
34
using System.Net.Http;
45
using Microsoft.Agents.AI;
56
using Microsoft.Agents.AI.A2A;
@@ -13,6 +14,17 @@ namespace A2A;
1314
/// </summary>
1415
/// <remarks>
1516
/// These extensions bridge the gap between A2A SDK client <see cref="AgentCard"/> and <see cref="AIAgent"/>.
17+
/// <para>
18+
/// To select gRPC, also reference the SDK's <c>A2A.Grpc</c> package,
19+
/// call <c>A2A.Grpc.A2AGrpcClientRegistration.Register()</c> once during application startup,
20+
/// and include <see cref="ProtocolBindingNames.Grpc"/> in <see cref="A2AClientOptions.PreferredBindings"/>.
21+
/// gRPC is not registered automatically and is not included in the default bindings.
22+
/// </para>
23+
/// <para>
24+
/// The caller is responsible for disposing any disposable client created by these methods after the agent is no longer
25+
/// in use. Retrieve it through <see cref="AIAgent.GetService"/> with <see cref="IA2AClient"/> as the service type
26+
/// and dispose it as an <see cref="IDisposable"/>.
27+
/// </para>
1628
/// </remarks>
1729
public static class A2AAgentCardExtensions
1830
{

‎dotnet/src/Microsoft.Agents.AI.A2A/Extensions/A2ACardResolverExtensions.cs‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,12 @@ namespace A2A;
2222
/// with A2A agents by handling the conversion from A2A clients to
2323
/// <see cref="A2AAgent"/> instances that implement the <see cref="AIAgent"/> interface.
2424
/// </para>
25+
/// <para>
26+
/// To select gRPC, also reference the SDK's <c>A2A.Grpc</c> package,
27+
/// call <c>A2A.Grpc.A2AGrpcClientRegistration.Register()</c> once during application startup,
28+
/// and include <see cref="ProtocolBindingNames.Grpc"/> in <see cref="A2AClientOptions.PreferredBindings"/>.
29+
/// Agent card discovery still uses HTTP. Client ownership follows <see cref="A2AAgentCardExtensions"/>.
30+
/// </para>
2531
/// </remarks>
2632
public static class A2ACardResolverExtensions
2733
{

0 commit comments

Comments
 (0)