当前位置：首页 > news >正文

MAF快速入门（16）用户智能体交互协议AG-UI（上）

news 2026/5/12 17:08:44

大家好，我是Edison。

最近我一直在跟着圣杰的《.NET+AI智能体开发进阶》课程学习MAF开发多智能体工作流，我强烈推荐你也上车跟我一起出发！

上一篇，我们学习了MAF中快速调试的利器DevUI。本篇，我们来了解一个用户智能体交互协议：AG-UI。

1 什么是AG-UI

AG-UI 全称 Agent–User Interaction Protocol 即智能体-用户交互协议，这是一个开放的、基于事件的协议，由 CopilotKit 团队发起，用于标准化 AI Agent 与用户界面的实时交互。

为什么出现AG-UI协议？

这是因为在构建AI Agent应用的界面时，传统API模式面临很多问题和挑战：

而AG-UI则是专门为AI Agent与用户界面的交互而设计的协议，其核心价值体现在：

📡 实时流式响应：即时展示 Agent 输出，无需等待
🎯 事件驱动架构：细粒度的交互事件，精确控制 UI
🔄 状态同步机制：Snapshot/Delta 模式，保持 UI 与 Agent 状态一致
🔧 工具调用可视化：透明展示 Agent 的思考和行动过程

三大Agent协议对比

我们之前已经学习了MCP 和 A2A两个重要的协议了，加上AG-UI，它们共同组成了Agent的三大通信协议体系。

不过，它们的定位各有侧重，并非非此即彼，而是协同使用，用形象的比喻来讲：

AG-UI 像是"客服窗口"：

用户与 Agent 之间的交互界面
实时展示 Agent 的工作状态
支持用户输入和反馈

MCP 像是"工具箱"：

Agent 调用外部工具完成任务
工具是被动的，等待调用
扩展 Agent 的能力边界

A2A 像是"同事协作"：

多个 Agent 之间的任务分发
每个 Agent 都是自主的
可以互相委托和协作

在实际企业场景中，三大协议通常协同使用：

AG-UI：用户通过界面与主 Agent 交互
MCP：Agent 内部使用 MCP 调用工具
A2A：复杂任务委托给专家 Agent 处理

下图展示了三大协议的详细对比：

2 快速开始：AG-UI对话应用

AG-UI协议定义了清晰的架构组件，包括 Server、Client 和 Agent。

在MAF中提供了一个内置的AG-UI组件，我们可以非常方便地创建集成AG-UI的Agent应用。

接下来，我们就一步一步完成一个AG-UI对话应用涉及到的Server 和 Client。

AG-UI Server

首先，我们创建一个ASP.NET Web应用，安装以下NuGet包：

Microsoft.Agents.AI.Hosting.AGUI.AspNetCore
Microsoft.Agents.AI.OpenAI
Microsoft.Extensions.AI.OpenAI

然后，就是整个示例的核心部分，我们一块一块来说：

（1）创建应用并注册AG-UI服务

// Step0. Create WebApplication builder
var builder = WebApplication.CreateBuilder(args);
builder.Services.AddHttpClient().AddLogging();// Step1. Register AG-UI services
builder.Services.AddAGUI();

（2）创建一个AI Agent：

var app = builder.Build();// Step2. Load Configuration
var config = new ConfigurationBuilder().AddJsonFile($"appsettings.json", optional: false, reloadOnChange: true).AddJsonFile($"appsettings.{Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT")}.json", optional: true, reloadOnChange: true).Build();
var openAIProvider = config.GetSection("OpenAI").Get<OpenAIProvider>();// Step3. Create one ChatClient
var chatClient = new OpenAIClient(new ApiKeyCredential(openAIProvider.ApiKey),new OpenAIClientOptions { Endpoint = new Uri(openAIProvider.Endpoint) }).GetChatClient(openAIProvider.ModelId).AsIChatClient();// Step4. Create one AI Agent
var agent = chatClient.AsAIAgent(name: "AGUI-Assistant",instructions: "你是一个友好的AI助手，请使用中文回答用户的问题。");
Console.WriteLine("✅ AI Agent 创建成功");

（3）映射AGUI端点并启动应用：

// Step5. Mapping AG-UI Endpoints
app.MapAGUI("/", agent);Console.WriteLine("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
Console.WriteLine("🚀 AG-UI Server 已启动");
Console.WriteLine("📍 端点地址: https://localhost:8443/");
Console.WriteLine("💡 使用 Ctrl+C 停止服务");
Console.WriteLine("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");app.Run();

可以看到，我们仅用一行代码 app.MapAGUI() 就启用了AG-UI协议，So Easy!

启动起来的效果如下图所示：

AG-UI Client

首先，我们创建一个控制台应用，安装以下NuGet包：

Microsoft.Agents.AI.AGUI
Microsoft.Agents.AI

然后，我们创建AG-UI Client 和 AI Agent：

// Load Configuration
var config = new ConfigurationBuilder().AddJsonFile($"appsettings.json", optional: false, reloadOnChange: true).Build();
var openAIProvider = config.GetSection("OpenAI").Get<OpenAIProvider>();
var serverEndpoint = config.GetValue<string>("AGUI_SERVER_URL")?? "https://localhost:8443";
Console.WriteLine("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━");
Console.WriteLine("🚀 AG-UI 客户端已启动");
Console.WriteLine($"📍 服务端地址: {serverEndpoint}");
Console.WriteLine("━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n");
// Step1. Create HTTP Client
using HttpClient httpClient = new()
{Timeout = TimeSpan.FromSeconds(60)
};
// Step2. Create AG-UI Client
var chatClient = new AGUIChatClient(httpClient, serverEndpoint);
// Step3. Create AI Agent
var agent = chatClient.AsAIAgent(name: "agui-client",description: "AG-UI Client Agent");

然后，准备开始对话：

// Step4. Prepare for Conversation
var session = await agent.GetNewSessionAsync();
var messages = new List<ChatMessage>()
{new ChatMessage(ChatRole.System, "你是一个友好的AI助手，使用中文回答用户的问题。")
};
Console.WriteLine("💬 开始对话（输入 :q 或 quit 退出）\n");while (true)
{Console.Write("👤 用户: ");string? message = Console.ReadLine();if (string.IsNullOrWhiteSpace(message)) continue;if (message is ":q" or "quit") break;// 添加用户消息messages.Add(new ChatMessage(ChatRole.User, message));// 流式接收响应Console.Write("🤖 助手: ");await foreach (var update in agent.RunStreamingAsync(messages, session)){foreach (AIContent content in update.Contents){switch (content){case TextContent textContent:Console.Write(textContent.Text);break;case UsageContent usageContent:Console.WriteLine($"\n[📊 Tokens: {usageContent.Details.TotalTokenCount}]");break;default:Console.Write("Unknown content!");break;}}}Console.WriteLine("\n");
}
Console.WriteLine("👋 再见！");
Console.ReadKey();