代理框架提供託管套件,透過 代理-代理(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
以下範例展示了一個最小的 ASP.NET Core 應用程式,透過 A2A 托管單一代理。 它使用 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)提供,而非 Agent Framework 主機套件。
Tip
每個主機只能提供一張代理卡,因此透過已知路徑只能偵測到一張代理。 其他代理仍可透過 URL 直接聯繫。 更多選項請參閱 Agent Discovery 。
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();
在此範例中,兩個代理都沒有代理卡,因此用戶端必須直接知道終端網址。 您可以使用 MapWellKnownAgentCard 新增代理程式卡片探索功能,但每個託管只能公告一個代理程式 - 請參閱代理程式卡片。
任務支援
備註
預設代理程式處理程序尚未回傳 A2A 任務。 託管代理總是以 A2A 訊息回應。
若要回傳任務,請如 IAgentHandler 所示註冊自訂 。 它會取代預設的處理器,因此您的處理器必須執行代理程式並建立、更新、恢復及取消任務。