代理框架提供托管包,这些包通过 代理到代理 (A2A) 协议公开 AI 代理。 托管后,任何符合 A2A 的客户端都可以发现代理并与代理通信,而不管客户端是使用哪种框架或技术构建的。
NuGet 包:
-
Microsoft.Agents.AI.Hosting.A2A.AspNetCore - 用于 A2A 协议绑定的 ASP.NET Core 终结点映射。 此包通过传递依赖项包含
Microsoft.Agents.AI.Hosting.A2A。 - Microsoft.Agents.AI.Hosting.A2A - 将 AI 代理桥接到 A2A 协议的核心托管逻辑(服务器注册、请求处理、会话管理)。
入门指南
安装 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,如 重写默认设置中所示。 它将替换默认处理程序,因此处理程序必须运行代理并创建、更新、恢复和取消任务。