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

简介

1 什么是AG-UI

为什么出现AG-UI协议？

三大Agent协议对比

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

AG-UI Server

AG-UI Client

3 小结

示例源码

简介

大家好，我是Edison。

上一篇，我们学习了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();

最终的调试效果如下图所示：

可以看到，我们很容易就创建了一个用户友好的对话客户端，实时的流式响应也不需要我们写过多代码实现。