AG-UI 协议现在有了一等公民级的 .NET SDK

Microsoft .NET Blog 发布日期待确认

.NET 团队很高兴地宣布，我们与 CopilotKit 合作，为 AG-UI 贡献了一套 .NET SDK。这套 AG-UI .NET SDK 与 TypeScript、Python 版 SDK 一同放在 AG-UI 仓库中，以 MIT 许可证发布在 NuGet 上。现在，任何 .NET 服务都能直接使用 AG-UI。Microsoft Agent Framework（MAF）对 .NET 的 AG-UI 支持，如今就建立在这套 AG-UI .NET SDK 之上。

什么是 AG-UI？

Agent 打破了传统的「请求—响应」模式。它们长时间运行，边工作边流式输出 token，会把任务委派给子 agent，还会在回复过程中调用工具。如果没有一套共享协议，每个 agent 框架或服务都可能用不同的流式格式，应用开发者就得自己去解析数据块、跟踪状态、把框架特有的事件映射到 UI 上。这些样板代码得自己维护，而且一旦事件格式变动就可能失效。

AG-UI（Agent-User Interaction Protocol，Agent 与用户交互协议）统一了 agent 与面向用户的应用之间的通信方式。它把 agent 的生命周期以带类型的事件形式流式输出，并分成若干类别。前端监听 RUN_STARTED、TEXT_MESSAGE_CONTENT、STATE_DELTA 等事件，无需关心它们由哪个框架产生。状态事件让 agent、应用和用户三者保持同步。这些事件怎么展示由客户端决定，所以界面可以是网页应用、终端、移动应用，甚至是 Slack、Teams 这类聊天平台。

.NET SDK 把这套能力带到了 C#。后端可以用原生方式发出这些事件，客户端则能消费任何受支持语言编写的 agent。

快速上手

这套 SDK 支持双向通信。AGUI.Server 把 agent 变成一个 AG-UI 端点，AGUI.Client 让 .NET 应用去消费这样的端点。服务端和客户端都建立在同一组 AG-UI 基础原语之上。

dotnet add package AGUI.Server

你的 agent 是一个 IChatClient，也就是 Microsoft.Extensions.AI 里的标准聊天抽象。假设你的应用定义了一个 CreateChatClient() 方法，返回配置好的 IChatClient，那么注册这个 client 和 AG-UI 序列化器即可：

using AGUI.Abstractions;
using AGUI.Server;
using Microsoft.AspNetCore.Http.Json;

using Microsoft.Extensions.AI;
using Microsoft.Extensions.Options;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddSingleton(CreateChatClient());
builder.Services.Configure<JsonOptions>(options =>
    options.SerializerOptions.TypeInfoResolverChain.Insert(
        0,
        AGUIJsonUtilities.DefaultTypeInfoResolver));

var app = builder.Build();

app.MapPost("/", (
    RunAgentInput input,
    IChatClient chatClient,
    IOptions<JsonOptions> jsonOptions,
    CancellationToken cancellationToken) =>
{
    var context = input.ToChatRequestContext(
        jsonOptions.Value.SerializerOptions);

    var events = chatClient
        .GetStreamingResponseAsync(
            context.Messages,
            context.ChatOptions,
            cancellationToken)
        .AsAGUIEventStreamAsync(context, cancellationToken);

    return TypedResults.ServerSentEvents(events);
});

await app.RunAsync();

ToChatRequestContext 会把收到的 RunAgentInput（协议规定的请求负载）拆解成 IChatClient 需要的消息和选项。AsAGUIEventStreamAsync 则把响应流重新变回协议事件：在一次运行的前后发出 RUN_STARTED 和 RUN_FINISHED；在切换到另一条消息或工具调用之前，先关闭已经打开的文本块和推理块；如果有多个中断（interrupt），合并成一个最终的 RUN_FINISHED。协议这块由 SDK 负责，Web 服务器怎么写由你自己决定——也正因如此，Agent Framework 的 ASP.NET Core 包才会把这些底层能力再封装成 AddAGUIServer() 和 MapAGUIServer()。

在 Agent Framework 里，同样的端点只要几行代码就能搞定。假设你已经有一个叫 chatClient 的 IChatClient，下面的代码就能创建并托管这个 agent。完整的服务端和客户端示例，可以参考 Microsoft Learn 上的完整教程。

dotnet add package Microsoft.Agents.AI.Hosting.AGUI.AspNetCore --prerelease

using Microsoft.Agents.AI;
using Microsoft.Agents.AI.Hosting.AGUI.AspNetCore;
using Microsoft.Extensions.AI;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAGUIServer();

var app = builder.Build();

AIAgent agent = chatClient.AsAIAgent(
    name: "AGUIAssistant",
    instructions: "You are a helpful assistant.");

app.MapAGUIServer("/", agent);

await app.RunAsync();

AGUI.Client 负责反方向，把 .NET 应用连接到任意 AG-UI 智能体。

dotnet add package AGUI.Client

using AGUI.Client;

using var httpClient = new HttpClient();

var chatClient = new AGUIChatClient(

```csharp
new(httpClient, "http://localhost:5001"));

AGUIChatClient 实现了 IChatClient 接口，所以只要你的代码里已经用上 IChatClient，就能直接拿它替换。另一端的 agent 用 Python、TypeScript 还是 C# 写的都无所谓，你的代码一行都不用改。只要端点说 AG-UI 协议，任何 AG-UI 客户端都能驱动它：.NET 应用通过 AGUI.Client，React 前端通过 CopilotKit。CopilotKit Interactive Dojo 里就有跑在 .NET 后端上的实例。

仓库中协议的每一部分都有可运行的示例。每一步配一对客户端和服务器，覆盖聊天、后端与前端工具、人工介入（human in the loop）、共享状态、推理、多模态输入、中断、并行工具调用、protobuf 和遥测。

架构

整体是这样协作的：任意 AG-UI 客户端发来请求，端点把它交给你的 agent——用 Microsoft Agent Framework 写的，或者你自己的 agent 代码——agent 调用你的工具和模型，响应则以协议事件的形式流式返回。

包

SDK 在 NuGet 上分成五个包：协议类型、线格式（wire format）格式化器、protobuf 支持、HTTP 客户端，以及一个基于 Microsoft.Extensions.AI、不绑定具体框架的服务端适配器。

客户端包和服务端包会自动引入各自需要的抽象包，所以多数应用只需引用其中一个。

对 Microsoft Agent Framework 意味着什么

Agent Framework 是我们用来在 .NET 和 Python 里构建 AI agent 的 SDK，过去自带一套 AG-UI 协议实现。现在它改为依赖 NuGet 上的 AGUI.* 包，同时保留把 agent 变成端点的 ASP.NET Core 集成。协议由 AG-UI C# SDK 维护，并与 TypeScript、Python SDK 保持线兼容。

详细信息见迁移公告。对现有 Agent Framework 用户来说，编程模型没有变化，只是有几个 API 改了名：

事件格式保持不变，所以现有前端无需改动，直接对接升级后的后端即可正常工作。

查看原文