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();