DevUI：Agent 的开发期调试界面

写完一个 Agent 或 Workflow，接下来最现实的问题是：它到底跑起来是什么样？ 控制台可以打印最终回答，却不方便观察工具调用、流式输出和多 Agent 串联的中间结果，也很难让产品或测试同学直接上手体验。

DevUI 是 Microsoft Agent Framework 自带的轻量级 Web 调试界面。它会列出后端注册的 Agent 和 Workflow，并提供浏览器对话、文件上传、流式渲染以及 OpenAI 兼容 API。在代码写完、正式前端尚未接入时，可以先用它观察 Agent 的实际运行效果。

但是这种方式依赖于提前编写 Agent 并注册到容器中，而我们编写 Agent 往往是需要动态创建实例的，所以 DevUI 只适合在开发时调试测试，并不适合加入生产环境。

DevUI 如何工作

DevUI 并没有另外实现一套 Agent 运行时。它把托管层已有的 Agent 发现、会话管理和流式响应接到固定 UI 上，再提供一层 OpenAI 兼容接口。整个界面由 ASP.NET Core 中间件和嵌入程序集的前端资源组成，直接挂载在自己的 Web 应用中：

正在渲染 Mermaid 图表...

注册完成后，应用会增加以下端点：

端点	方法	作用
`/devui/{*path}`	GET	SPA 前端入口，所有前端资源都走这里
`/meta`	GET	运行时元数据：`ui_mode`、`runtime`、`auth_required`、`capabilities`
`/v1/entities`	GET	列出所有 Agent/Workflow（`GetKeyedServices` + `GetServices` 收集）
`/v1/entities/{id}/info`	GET	单个实体的详细信息

/meta 会告诉前端当前使用 .NET 运行时以及是否需要 token，响应大致如下：

{
  "ui_mode": "developer",
  "version": "0.1.0",
  "framework": "agent_framework",
  "runtime": "dotnet",
  "capabilities": { "tracing": false, "openai_proxy": false, "deployment": false },
  "auth_required": false
}

安装并启动 DevUI

创建一个 Web 项目，引入以下 nuget 包。

Microsoft.Agents.AI.DevUI
Microsoft.Agents.AI.Hosting
Microsoft.Agents.AI.Hosting.OpenAI

下面的最小示例注册三个 Agent，并打开 DevUI：

using Microsoft.Agents.AI.DevUI;
using Microsoft.Agents.AI.Hosting;
using Microsoft.Extensions.AI;
using OpenAI;
using System.ClientModel;

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllers();
builder.Services.AddOpenApi();

IChatClient chatClient = new OpenAIClient(
        credential: new ApiKeyCredential(key: "1234"),
        options: new OpenAIClientOptions { Endpoint = new Uri("http://127.0.0.1:1234/v1") })
    .GetChatClient(model: "qwen/qwen3.5-9b")
    .AsIChatClient();

builder.Services.AddChatClient(chatClient);
// 注册几个 Agent（带工具），DevUI 会自动发现它们
builder.AddAIAgent("assistant", "You are a helpful assistant.");
builder.AddAIAgent("poet", "You are a poet who replies in verse.");
builder.AddAIAgent("coder", "You are a coding assistant.");

// 注册 OpenAI 兼容端点（DevUI 前端对话依赖它们）
builder.Services.AddOpenAIResponses();
builder.Services.AddOpenAIConversations();
builder.AddDevUI();

var app = builder.Build();

app.MapOpenAIResponses();
app.MapOpenAIConversations();

if (app.Environment.IsDevelopment())
{
    app.MapOpenApi();
    app.MapDevUI();   // 挂载 /devui、/meta、/v1/entities
}

app.UseAuthorization();

app.MapControllers();

app.Run();

启动后访问 https://localhost:<port>/devui，就能看到 assistant、poet、coder 三个 Agent。

DevUI 适合在开发阶段列出并对话 Agent 或 Workflow，处理多模态输入，也能配合 OpenTelemetry 展示基本 tracing。它不是生产前端，下面这些能力不在它的职责范围内：

生产部署所需的多租户、限流和审计
复杂的审批 UI：它是一个通用调试器，不是业务前端
AG-UI 的前端工具、状态同步：那些是 AG-UI 协议的能力，DevUI 不实现（下一章详述）
面向最终用户的产品交互

需要正式的 Web 或 Mobile 前端，并支持工具交互、审批和状态同步时，应继续使用下一章介绍的 AG-UI 协议；需要让不同框架的 Agent 互相调用时，则使用后续介绍的 A2A 协议。DevUI 只负责在开发阶段让这些 Agent 更容易被看见和调试。