[AG-UI详解-01]创建一个类似ChatGPT应用与Agent实时交互

AG‑UI是微软在Microsoft Agent Framework (MAF)中定义的标准化前后端通信协议用来构建Web/移动端的AI Agent UI。它让Agent不再只是后端逻辑而是能以统一格式与前端实时交互、流式输出、同步状态并渲染交互式组件。本系列将对协议本身以及背后的执行原理对AG-UI进行系统介绍。1. AG-UI概述AG-UI是一种协议它使您能够构建具有实时流、状态管理和交互式UI组件等高级功能的基于Web的Agent应用程序。MAF与AG-UI的集成可实现Agent和Web客户端之间的无缝连接。AG-UI提供以下功能远程Agent托管将Agent部署为可供多个客户端访问的Web服务实时流式传输使用SSE传输Agent响应以实现即时反馈标准化通信一致的消息格式确保Agent交互的可靠性会话管理在多个请求之间保持对话上下文高级功能人机协作审批、状态同步和UI渲染等。AG-UI可以应用到如下场景构建与Agent交互的Web或移动应用程序将Agent部署为可供多个并发用户访问的服务实时传输Agent响应以提供即时用户反馈实现用户在执行操作前确认的审批工作流同步客户端和服务器之间的状态以实现交互式体验根据Agent工具调用渲染自定义UI组件。2. 将Agent暴露成HTTP终结点如果你之前没有接触过AG-UI可以利用如下这个演示实例体验一下如何利用此协议将一个Agent对象以ASP.NET Core路由终结点的形式暴露出来并利用客户端程序采用HTTP/SSE的形式与它进行实时交互实时返回Agent的输出实际上我们目前看到的基于对于的AI工具比如ChatGPT就采用类似的交互方式。如下所示的是一个ASP.NET Core程序。在这个程序中我们根据指定的Microsoft Foundry项目地址创建了一个AIProjectClient对象并使用部署的模型将其封装成一个AIAgent对象。我们直接调用WebApplication的MapAGUI扩展方法采用根路径“/”注册了一个路由终结点来调用这个AIAgent对象。在这之前我们还会调用IServiceCollection的AddAGUI扩展方法注册AG-UI所需的服务。usingAzure.AI.Projects;usingAzure.Identity;usingDotNetEnv;usingMicrosoft.Agents.AI.Hosting.AGUI.AspNetCore;Env.Load();varprojectUrlEnvironment.GetEnvironmentVariable(PROJECT_URL)!;varapiKeyEnvironment.GetEnvironmentVariable(OPENAI_API_KEY)!;varmodelEnvironment.GetEnvironmentVariable(MODEL)!;varbuilderWebApplication.CreateBuilder(args);builder.Services.AddHttpClient().AddLogging();builder.Services.AddAGUI();varappbuilder.Build();varagentnewAIProjectClient(newUri(projectUrl),newAzureCliCredential()).AsAIAgent(model:model,name:HistoryAssistant,instructions:你是一个深谙中国古代历史的专家善于根据正史以公正客观的态度于人交流历史问题。对于用户提出的问题请以简介概括性的语言予以答复字数尽量保持在200字以内。);app.MapAGUI(/,agent);awaitapp.RunAsync();注 之前针对AG-UI的.NET SDK有如下两个实现官方实现,相关的NuGet包为AGUI.AbstractionsAGUI.ServerAGUI.Client微软针对MAF的实现, 相关的NuGet包为Microsoft.Agents.AI.AGUI最近后者的核心代码被移除只保留一些胶水代码比如针对ASP.NET Core将AIAgent暴露成采用AG-UI协议的终结点。代码NuGet包尚未发布当新的NuGet保护之后相关的AddAGUI和MapAGUI方法将会替换成AddAGUIServer和MapAGUIServer关于这个更新的详细介绍可以参考githu站点3. 利用AGUIChatClient远程调用Agent终结点我们创建一个控制台程序来模拟客户端程序可以将其视为ChatGPT客户端应用。如下面的代码所示我们创建根据创建的HttpClient和上面暴露出来的AG-UI终结点地址创建了一个AGUIChatClient对象。AGUIChatClient类型实现了IChatClient接口它会将目标终结点视为LLM利用指定的HttpClient与之交互。正因为这是一个IChatClient对象所以我们可以调用AsAIAgent扩展方法将其封装为一个AIAgent对象。usingMicrosoft.Agents.AI;usingMicrosoft.Agents.AI.AGUI;usingMicrosoft.Extensions.AI;usingHttpClienthttpClientnew(){TimeoutTimeSpan.FromSeconds(60)};varchatClientnewAGUIChatClient(httpClient,http://localhost:9999);varagentchatClient.AsAIAgent(name:AGUIAgent,description:AG-UI Client Agent);varsessionawaitagent.CreateSessionAsync();while(true){Console.Write(\n$ (:q or quit to exit): );varmessageConsole.ReadLine();if(messageis:qorquit){break;}awaitforeach(AgentResponseUpdateupdateinagent.RunStreamingAsync([newChatMessage(ChatRole.User,message)],session)){varchatUpdateupdate.AsChatResponseUpdate();foreach(AIContentcontentinupdate.Contents){if(contentisTextContenttextContent){Console.Write(textContent.Text);}elseif(contentisErrorContenterrorContent){Console.WriteLine($\n[Error:{errorContent.Message}]);}}}}由于AGUIChatClient实现了远程调用的全部细节所以客户端程序只需要以常规方式调用生成的AIAgent对象即可。在上面演示的程序中我们创建了一个Session并在此Session基础上开启了一个对话循环。为了提高用户体验我们采用流的形式调用AIAgent并实施输出ChatResponseUpdate的内容。如下的输出体现了我们与AI进行的一轮对话。$ (:q or quit to exit): 战国四大名将一般指的是谁 “战国四大名将”通常指战国后期四位最具代表性的军事统帅 - 白起秦国号称“人屠”长平之战重创赵国是秦统一的重要功臣。 - 王翦秦国老成持重率军灭楚、灭燕奠定秦统一天下基础。 - 廉颇赵国赵国名将以善守著称“负荆请罪”故事主角之一。 - 李牧赵国战国末期名将曾大破匈奴并在肥之战重创秦军。 这一说法主要流行于后世并非战国时期官方称谓。 $ (:q or quit to exit): 吴起、司马错、乐毅和魏无忌的军事才能都不弱于这四位吧 确实如此。所谓“战国四大名将”更多是后世综合战绩、影响力与知名度形成的概括并非绝对排名。你提到的几人军事才能都非常突出。 吴起兼具军事与改革才能在魏、楚都取得显著战绩是战国初期最顶尖的统帅之一。 司马错是秦国早期名将主张“先取蜀”灭蜀后为秦国统一奠定战略基础眼光极强。 乐毅率五国伐齐连下七十余城几乎灭齐是战国最成功的联军统帅之一。 魏无忌信陵君虽非职业将领但窃符救赵、统兵破秦展现了极强的军事与政治号召力。 若论纯军事能力他们未必逊于“战国四大名将”只是时代、战绩持续性及后世影响不同。 $ (:q or quit to exit): 如何正确评价锋芒被其父掩盖的王贲 王贲是秦统一战争中极关键的统帅实际战功并不逊于其父王翦只是名气长期被“灭楚主帅”王翦遮盖。 他主要功绩包括灭魏时引黄河、鸿沟灌大梁随后灭燕、代俘燕王喜又南下灭齐完成统一最后一环。秦最后统一六国王贲直接参与了其中三国的覆灭。 与王翦相比王贲更偏进取型作战节奏快、攻坚能力强王翦则更稳健老练。父子二人实际上形成了互补。 后世对王贲关注较少一是《史记》记载篇幅有限二是其功业大多发生在秦统一后期容易被“秦始皇—王翦”这一更宏大的叙事掩盖。但若以实际灭国战绩论王贲完全称得上一流名将。4. 从HTTP请求和响应分析AG-UI分析HTTP请求和响应的内容更能揭示AG-UI协议的本质。上面的输出体现了三轮对话如下所示的是第一轮对话的请求。可以看出这是一个常规的POST请求Conent-Type为application/json。POST http://localhost:9999/ HTTP/1.1 Host: localhost:9999 Content-Type: application/json; charsetutf-8 Content-Length: 268 {threadId:thread_eb2bd3b287494deb8736f079863bdbc7,runId:run_8f8ed2f303824ab6acc9875e9ebdf908,messages:[{name:null,id:1d008f8827e044758e1de9e44bd13989,role:user,content:战国四大名将一般指的是谁}],context:[]}请求的JSON包含四个字段threadId表示Session或者Conversation的IDrunId 针对当前Agent调用的标识messages输入的消息列表context用于传递额外上下文如前端状态、表单内容、UI状态。实际上作为调用AG-UI的请求内容还可以包含其他成员我们将在后续内容进行介绍。如下这段内容为对应的响应从Content-Typetext/event-stream可以看出服务端采用SSE以流的形式实施输出生成的内容data表示的Chunk。data: {threadId:thread_b62ca0e770654dbc9bbe7283b0cbffc5,runId:run_d85eea336f6b498baf4c5b5d8258b858,type:RUN_STARTED} data: {messageId:chatcmpl-E3SpqsP2hJDy8fw2XQJUBwglyemYh,role:assistant,type:TEXT_MESSAGE_START} data: {messageId:chatcmpl-E3SpqsP2hJDy8fw2XQJUBwglyemYh,delta:\u201C,type:TEXT_MESSAGE_CONTENT} ... data: {messageId:chatcmpl-E3SpqsP2hJDy8fw2XQJUBwglyemYh,delta:\u3002,type:TEXT_MESSAGE_CONTENT} data: {messageId:chatcmpl-E3SpqsP2hJDy8fw2XQJUBwglyemYh,type:TEXT_MESSAGE_END} data: {threadId:thread_b62ca0e770654dbc9bbe7283b0cbffc5,runId:run_d85eea336f6b498baf4c5b5d8258b858,result:null,type:RUN_FINISHED}AG-UI是一个完全采用事件驱动的协议客户端和服务端完全利用事件的方式实现流式数据交换上述的响应就包含了五种典型的事件RUN_STARTED标志Agent调用开始TEXT_MESSAGE_STAR标志文本消息传输开始TEXT_MESSAGE_CONTENT传输具体的消息内容TEXT_MESSAGE_END标志文本消息传输结束RUN_FINISHED标志Agent调用结束