A2A .NET SDK

The A2A library provides the fundamental building blocks for the Agent2Agent protocol.

Client-side

• A2AClient: Primary client for making A2A requests. Supports streaming, task management, and push notifications.
• A2ACardResolver: Resolves AgentCard information from endpoints to discover capabilities.

Server-side

• A2AServer: Handles JSON-RPC requests, manages task lifecycles via TaskProjection, and coordinates responses.
• IAgentHandler: The interface you implement to define agent behavior. Requires ExecuteAsync() and CancelAsync().
• TaskUpdater: API for emitting lifecycle events: Submit, StartWork, AddArtifact, Complete, Fail, Cancel, RequireInput.
• MessageResponder: API for stateless, immediate message replies.
• RequestContext: Provides context to the agent, including the incoming Message, TaskId, ContextId, and properties like UserText and IsContinuation.
• AgentEventQueue: A channel-backed queue where agents write events for the SDK to process.
• ITaskStore: Interface for task persistence. Use InMemoryTaskStore for development/testing.

Core Models

• AgentTask: Represents task status, history, artifacts, and metadata.
• AgentCard: Contains agent metadata, capabilities, and endpoints.
• Message: The data format for messages exchanged between agents.

V0.3 used a single A2AResponse with a kind discriminator. V1 splits responses into specific types based on the operation.

SendMessage Responses

SendMessageAsync now returns a SendMessageResponse. Use PayloadCase to distinguish between a Task or a Message.

Streaming Responses

Streaming operations (like SendStreamingMessageAsync) return an IAsyncEnumerable<StreamResponse>. Use StreamResponseCase to handle different event types such as StatusUpdate, ArtifactUpdate, Task, or Message.

// V1: SendMessage returns SendMessageResponse with named fields
SendMessageResponse response = await client.SendMessageAsync(request);
switch (response.PayloadCase)
{
    case SendMessageResponseCase.Task:
        Console.WriteLine($"Task: {response.Task!.Id}, State: {response.Task.Status.State}");
        break;
    case SendMessageResponseCase.Message:
        Console.WriteLine($"Message from agent: {response.Message!.Parts[0].Text}");
        break;
}

// V1: Streaming returns IAsyncEnumerable<StreamResponse>
await foreach (StreamResponse evt in client.SendStreamingMessageAsync(request))
{
    switch (evt.PayloadCase)
    {
        case StreamResponseCase.StatusUpdate:
            Console.WriteLine(evt.StatusUpdate!.Status.State);
            break;
        case StreamResponseCase.ArtifactUpdate:
            Console.WriteLine(evt.ArtifactUpdate!.Artifact.ArtifactId);
            break;
        case StreamResponseCase.Task:
            Console.WriteLine(evt.Task!.Id);
            break;
        case StreamResponseCase.Message:
            Console.WriteLine(evt.Message!.Parts[0].Text);
            break;
    }
}

In V0.3, parts were represented by a hierarchy of subclasses (TextPart, FilePart, DataPart). In V1, these are unified into a single sealed Part class.

Creating Parts in V1

Use the factory methods provided by the Part class:

• Part.FromText(string text)
• Part.FromUrl(string url, string mediaType, string filename)
• Part.FromRaw(byte[] data)
• Part.FromData(JsonElement data)

Consuming Parts in V1

Instead of type casting, use the ContentCase computed enum to identify the part type:

foreach (Part part in message.Parts)
{
    switch (part.ContentCase)
    {
        case PartContentCase.Text:
            Console.WriteLine(part.Text);
            break;
        case PartContentCase.Url:
            Console.WriteLine(part.Url);
            break;
        case PartContentCase.Raw:
            // part.Raw is byte[]
            break;
        case PartContentCase.Data:
            Console.WriteLine(part.Data);
            break;
    }
}

// Creating parts — use factory methods
var textPart = Part.FromText("Hello, world!");
var filePart = Part.FromUrl("https://example.com/report.pdf",
    mediaType: "application/pdf", filename: "report.pdf");
var dataPart = Part.FromData(
    JsonDocument.Parse("{\"key\": \"value\"}").RootElement);

// Consuming parts — use ContentCase enum
foreach (Part part in message.Parts)
{
    switch (part.ContentCase)
    {
        case PartContentCase.Text:
            Console.WriteLine(part.Text);
            break;
        case PartContentCase.Url:
            Console.WriteLine(part.Url);
            break;
        case PartContentCase.Raw:
            // part.Raw is byte[] (base64 in JSON)
            break;
        case PartContentCase.Data:
            Console.WriteLine(part.Data);
            break;
    }
}

The SDK handles protocol mechanics (serialization, JSON-RPC dispatch, task lifecycle), but the application developer is responsible for the following security layers:

Non-Goals: The SDK does not provide protection against prompt injection, cross-agent instruction smuggling, or webhook egress safety (SSRF).

To host an A2A agent in an ASP.NET Core application, follow these steps:

1. Implement IAgentHandler: Create a class that defines the agent's logic in ExecuteAsync.
2. Register the Agent: Use AddA2AAgent<THandler>(AgentCard) in your service collection to register the handler, its card, and necessary A2A services.
3. Map Endpoints: Use MapA2A(path) to expose JSON-RPC endpoints and MapWellKnownAgentCard(card) to enable agent discovery.

Example implementation of an Echo Agent:

using A2A;
using A2A.AspNetCore;

var builder = WebApplication.CreateBuilder(args);

// Register the agent with DI
builder.Services.AddA2AAgent<EchoAgent>(EchoAgent.GetAgentCard("http://localhost:5000/echo"));

var app = builder.Build();

// Map JSON-RPC endpoint
app.MapA2A("/echo");

// Map well-known agent card for discovery
var card = app.Services.GetRequiredService<AgentCard>();
app.MapWellKnownAgentCard(card);

app.Run();

public sealed class EchoAgent : IAgentHandler
{
    public async Task ExecuteAsync(
        RequestContext context,
        AgentEventQueue eventQueue,
        CancellationToken cancellationToken)
    {
        var responder = new MessageResponder(eventQueue, context.ContextId);
        await responder.ReplyAsync($"Echo: {context.UserText}", cancellationToken);
    }

    public static AgentCard GetAgentCard(string url) => new()
    {
        Name = "Echo Agent",
        Description = "Echoes messages back to the user",
        Version = "1.0.0",
        SupportedInterfaces = [new AgentInterface
        {
            Url = url,
            ProtocolBinding = "JSONRPC",
            ProtocolVersion = "1.0"
        }],
        DefaultInputModes = ["text/plain"],
        DefaultOutputModes = ["text/plain"],
        Capabilities = new AgentCapabilities { Streaming = false },
        Skills = [new AgentSkill
        {
            Id = "echo",
            Name = "Echo",
            Description = "Echoes back user messages",
            Tags = ["echo"]
        }],
    };
}