A2A 托管

代理框架提供托管包,这些包通过 代理到代理 (A2A) 协议公开 AI 代理。 托管后,任何符合 A2A 的客户端都可以发现代理并与代理通信,而不管客户端是使用哪种框架或技术构建的。

NuGet 包:

入门指南

安装 ASP.NET Core托管包(它会自动安装核心托管包和 A2A SDK 包):

dotnet add package Microsoft.Agents.AI.Hosting.A2A.AspNetCore --prerelease
dotnet add package Microsoft.Agents.AI.Foundry --prerelease

以下示例演示了通过 A2A 托管单个代理的最小 ASP.NET 核心应用程序。 它使用 Microsoft Foundry 作为 AI 提供程序 - 请参阅 提供程序 以获取其他选项。

using A2A;
using A2A.AspNetCore;
using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.AspNetCore.Builder;
using Microsoft.Extensions.DependencyInjection;

var builder = WebApplication.CreateBuilder(args);

string endpoint = builder.Configuration["FOUNDRY_PROJECT_ENDPOINT"]
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string model = builder.Configuration["FOUNDRY_MODEL"] ?? "gpt-4o-mini";

// 1. Create and register the "weather-agent" agent in the DI container.
builder.Services.AddKeyedSingleton<AIAgent>("weather-agent", (sp, _) =>
{
    return new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
        .AsAIAgent(
            model: model,
            instructions: "You are a helpful weather assistant.",
            name: "weather-agent");
});

// 2. Register the A2A server for the "weather-agent" agent.
builder.AddA2AServer("weather-agent");

var app = builder.Build();

// 3. Map A2A protocol endpoints for the "weather-agent" agent.
app.MapA2AHttpJson("weather-agent", "/a2a/weather-agent");

// 4. Serve a minimal agent card for the "weather-agent" agent discovery.
app.MapWellKnownAgentCard(new AgentCard
{
    Name = "WeatherAgent",
    Description = "A helpful weather assistant.",
    SupportedInterfaces =
    [
        new AgentInterface
        {
            Url = "http://localhost:5000/a2a/weather-agent",
            ProtocolBinding = ProtocolBindingNames.HttpJson,
            ProtocolVersion = "1.0",
        }
    ]
});

app.Run();

代理现在可以通过 A2A HTTP+JSON 协议绑定,在 /a2a/weather-agent 访问,其代理卡可在 /.well-known/agent-card.json 位置发现。 任何符合 A2A 的客户端都可以发现此代理并与之通信。

协议绑定

A2A 协议定义两个传输绑定。 两者均受支持:

Binding 方法 说明
HTTP+JSON MapA2AHttpJson 用于流式传输的标准 HTTP 请求和服务器发送事件。
JSON-RPC MapA2AJsonRpc JSON-RPC 2.0 通过 HTTP。

可以同时映射这两个绑定,以便客户端可以选择其首选传输。 如有必要,可以使用不同的路径:

app.MapA2AHttpJson("weather-agent", "/a2a/weather-agent");  // HTTP+JSON
app.MapA2AJsonRpc("weather-agent", "/a2a/weather-agent");   // JSON-RPC

代理卡

代理卡片描述你的代理的元数据(名称、说明、版本和支持的接口),以便客户端在发送请求之前发现并了解该代理的能力。 入门部分展示了一个最简代理卡。 对于生产用途,请提供完全填充的卡片:

using A2A;
using A2A.AspNetCore;

app.MapWellKnownAgentCard(new AgentCard
{
    Name = "WeatherAgent",
    Description = "A helpful weather assistant.",
    Version = "1.0",
    DefaultInputModes = ["text"],
    DefaultOutputModes = ["text"],
    SupportedInterfaces =
    [
        new AgentInterface
        {
            Url = "http://localhost:5000/a2a/weather-agent",
            ProtocolBinding = ProtocolBindingNames.HttpJson,
            ProtocolVersion = "1.0",
        }
    ]
});

注释

MapWellKnownAgentCard 由 A2A SDK 包(A2A.AspNetCore)提供,而不是由代理框架托管包提供。

Tip

每个主机只能提供一个代理卡,因此只有一个代理可通过已知路径发现。 仍可通过 URL 直接访问其他代理。 有关更多选项,请参阅 代理发现 。

AddA2AServer的工作原理

AddA2AServer方法在依赖项注入容器中注册一个键控A2AServer单例。 构造服务器时,它会解析或创建多个内部组件:

组件 Default Purpose
IAgentHandler A2AAgentHandler 将传入的 A2A 请求桥接到AIAgent。 转换消息、运行代理,并将响应作为 A2A 消息返回。
AgentSessionStore InMemoryAgentSessionStore 存储对话会话,使代理能够在使用同一contextId的多个请求之间保持上下文。

Warning

默认的 InMemoryAgentSessionStore 仅用于开发。 状态在应用程序重启时会丢失,且不会在多个实例间共享。 对于生产部署,请注册持久化实现。

重写默认值

在调用 AddA2AServer之前,可以通过在 DI 容器中注册键式服务来替换其中任何组件。 服务器使用代理名称作为键来解析键控服务。

自定义会话存储 - 用于持久对话存储:

builder.Services.AddKeyedSingleton<AgentSessionStore>("weather-agent", new MyDurableSessionStore());

builder.AddA2AServer("weather-agent");

自定义代理处理程序 - 完全控制请求处理。 注册密钥 IAgentHandler 后,它将完全替换默认值 A2AAgentHandler :

builder.Services.AddKeyedSingleton<IAgentHandler>("weather-agent", new MyCustomHandler());

builder.AddA2AServer("weather-agent");

多个代理

可以在单个应用程序中托管多个代理。 每个代理获取自己的 A2A 服务器和终结点:

// Register agents in DI.
builder.Services.AddKeyedSingleton<AIAgent>("weather-agent", (sp, _) =>
{
    return new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
        .AsAIAgent(model: model, instructions: "You are a helpful weather assistant.", name: "weather-agent");
});

builder.Services.AddKeyedSingleton<AIAgent>("scientist", (sp, _) =>
{
    return new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
        .AsAIAgent(model: model, instructions: "You are a scientist.", name: "scientist");
});

// Register A2A servers.
builder.AddA2AServer("weather-agent");
builder.AddA2AServer("scientist");

var app = builder.Build();

// Map endpoints.
app.MapA2AHttpJson("weather-agent", "/a2a/weather-agent");
app.MapA2AHttpJson("scientist", "/a2a/scientist");

app.Run();

在此示例中,两个代理都没有代理卡,因此客户端必须直接知道终结点 URL。 可以使用MapWellKnownAgentCard添加代理卡发现功能,但每个主机只能发布一个代理,请参阅代理卡。

任务支持

注释

默认代理处理程序尚未返回 A2A 任务。 托管代理始终使用 A2A 消息进行响应。

若要返回任务,请注册自定义 IAgentHandler,如 重写默认设置中所示。 它将替换默认处理程序,因此处理程序必须运行代理并创建、更新、恢复和取消任务。

后续步骤

另见