在 .NET AI 聊天应用中升级到 Microsoft 代理框架
引言
随着人工智能技术的快速发展，简单的聊天机器人已经不能满足日益复杂的业务需求。Microsoft 推出的 Agent Framework 为 .NET 开发者提供了构建智能代理的强大工具，能够实现多步骤工作流、自主决策和复杂任务编排。本文将详细介绍如何将基于 .NET AI 模板的标准聊天应用升级到 Microsoft 代理框架，利用其强大的功能和灵活性来构建更智能的应用。
正文内容
1. Microsoft 代理框架概述
Microsoft Agent Framework 是微软推出的预览框架，专为在 .NET 中构建 AI 代理而设计。它超越了简单聊天机器人的能力，提供了以下核心功能：
- 通过多步骤工作流程进行推理和计划
- 使用工具和函数与 API、数据库和服务交互
- 在整个对话中维护上下文
- 基于指令和数据做出自主决策
- 在多代理场景中与其他代理协调
该框架建立在 .NET 开发者熟悉的模式之上，如依赖注入、中间件和遥测，并与 Microsoft.Extensions.AI 深度集成。
2. 先决条件
在开始升级前，需要准备以下环境：
- 已安装 .NET 9 SDK
- Visual Studio 或带有 C# Dev Kit 的 Visual Studio Code
- 可访问 Azure OpenAI 的 Azure 账户，或使用 GitHub 模型
- 已安装 .NET AI 应用模板
- 基本熟悉 .NET、Blazor 和 AI 概念
3. 创建基础 AI 聊天应用
3.1 安装模板
首先使用官方 .NET AI 模板创建基线聊天应用：
dotnet new install Microsoft.Extensions.AI.Templates 3.2 创建项目
可以通过 Visual Studio 或 CLI 创建项目：
Visual Studio 方式：
- 打开 Visual Studio 2022
- 选择"创建新项目"
- 搜索"AI Chat Web App"
- 配置项目名称和位置
- 选择 Azure OpenAI 作为 AI 提供程序
- 为矢量存储选择"本地磁盘"
- 选择 .NET Aspire 进行业务流程
CLI 方式：
使用 dotnet new 命令创建项目，配置选项与 Visual Studio 相同。
3.3 项目结构
模板生成的解决方案包含三个项目：
ChatApp20/ ├── ChatApp20.Web/ # 带有聊天 UI 的 Blazor Server 应用 ├── ChatApp20.AppHost/ # .NET Aspire 业务流程 └── ChatApp20.ServiceDefaults/ # 共享服务配置 主要工作将在 ChatApp20.Web 项目中进行。
4. 添加 Microsoft 代理框架
4.1 安装必要的 NuGet 包
首先将 Microsoft Agent Framework 包添加到 ChatApp20.Web.csproj：
<ItemGroup> <!-- 保留现有包 --> <PackageReference Include="Aspire.Azure.AI.OpenAI" Version="9.5.1-preview.1.25502.11" /> <PackageReference Include="Microsoft.Extensions.AI.OpenAI" Version="9.10.0-preview.1.25513.3" /> <!-- 添加 Microsoft 代理框架包 --> <PackageReference Include="Microsoft.Agents.AI" Version="1.0.0-preview.251009.1" /> <PackageReference Include="Microsoft.Agents.AI.Abstractions" Version="1.0.0-preview.251009.1" /> <PackageReference Include="Microsoft.Agents.AI.Hosting" Version="1.0.0-preview.251009.1" /> <PackageReference Include="Microsoft.Agents.AI.Hosting.OpenAI" Version="1.0.0-alpha.251009.1" /> <PackageReference Include="Microsoft.Agents.AI.OpenAI" Version="1.0.0-preview.251009.1" /> </ItemGroup>
4.2 创建专用搜索功能服务
为了更好的关注点分离和可测试性，创建一个新的 SearchFunctions.cs 服务：
using System.ComponentModel; namespace ChatApp20.Web.Services; public class SearchFunctions { private readonly SemanticSearch _semanticSearch; public SearchFunctions(SemanticSearch semanticSearch) { _semanticSearch = semanticSearch; } [Description("使用短语或关键字搜索信息")] public async Task<IEnumerable<string>> SearchAsync( [Description("要搜索的短语")] string searchPhrase, [Description("如果可能，指定文件名仅搜索该文件")] string? filenameFilter = null) { var results = await _semanticSearch.SearchAsync(searchPhrase, filenameFilter, maxResults: 5); return results.Select(result => $"<result filename="{result.DocumentId}" page_number="{result.PageNumber}">{result.Text}</result>"); } } 4.3 在 Program.cs 中注册 AI 代理
使用 Agent Framework 的托管扩展配置 AI 代理：
// 注册使用代理框架的 AI 代理 builder.AddAIAgent("ChatAgent", (sp, key) => { var logger = sp.GetRequiredService<ILogger<Program>>(); var searchFunctions = sp.GetRequiredService<SearchFunctions>(); var chatClient = sp.GetRequiredService<IChatClient>(); // 创建并配置 AI 代理 var aiAgent = chatClient.CreateAIAgent( name: key, instructions: "你是一个有用的代理，提供简短而有趣的回答。", description: "帮助用户提供简短而有趣回答的 AI 代理。", tools: [AIFunctionFactory.Create(searchFunctions.SearchAsync)] ) .AsBuilder() .UseOpenTelemetry(configure: c => c.EnableSensitiveData = builder.Environment.IsDevelopment()) .Build(); return aiAgent; }); // 注册 SearchFunctions 以便通过 DI 注入到代理中 builder.Services.AddSingleton<SearchFunctions>(); 4.4 更新聊天组件
更新 Chat.razor 以使用新的 AI 代理：
@inject IServiceProvider ServiceProvider @using Microsoft.Agents.AI @code { private AIAgent aiAgent = default!; protected override void OnInitialized() { // 解析 Program.cs 中注册为"ChatAgent"的键控 AI 代理 aiAgent = ServiceProvider.GetRequiredKeyedService<AIAgent>("ChatAgent"); } private async Task AddUserMessageAsync(ChatMessage userMessage) { // 用代理流式处理替换 ChatClient.GetStreamingResponseAsync await foreach (var update in aiAgent.RunStreamingAsync( messages: messages.Skip(statefulMessageCount), cancellationToken: currentResponseCancellation.Token)) { var responseUpdate = update.AsChatResponseUpdate(); messages.AddMessages(responseUpdate, filter: c => c is not TextContent); responseText.Text += update.Text; chatOptions.ConversationId = responseUpdate.ConversationId; ChatMessageItem.NotifyChanged(currentResponseMessage); } } } 5. 运行和测试增强应用
5.1 使用 .NET Aspire 运行
.NET Aspire 提供了服务发现、统一日志记录和遥测、健康检查等功能：
- 运行应用，Aspire 仪表板会自动在浏览器中打开
- 首次运行时，系统会提示配置 Azure OpenAI：
- 选择 Azure 订阅
- 选择或创建资源组
- 选择或预配 Azure OpenAI 资源
- 确保部署了聊天模型(如 gpt-4o-mini)和嵌入模型(如 text-embedding-3-small)
5.2 测试代理
应用运行后，在 Aspire 仪表板中点击 Web 端点(通常是 https://localhost:7001)进行测试：
基本对话：
用户: 你好！你好吗？ 代理: 嘿！我很好——充满电，就像应急救生包一样。 带有语义搜索的工具调用：
用户: 应急救生包应该包括什么？ 代理: 简短的救生包清单(有趣版) 急救用品——绷带、纱布、消毒剂。 <citation filename='Example_Emergency_Survival_Kit.pdf' page_number='1'>水和食物供应</citation> 特定文件查询：
用户: 告诉我关于 GPS 手表的功能 代理: GPS 手表包括... <citation filename='Example_GPS_Watch.pdf' page_number='2'>实时跟踪</citation>
6. 高级场景
6.1 向代理添加更多工具
可以轻松扩展代理功能，例如添加天气查询：
public class WeatherFunctions { [Description("获取某个位置的当前天气")] public async Task<string> GetWeatherAsync( [Description("城市和州/国家")] string location) { // 调用天气 API return $"{location}的天气: 晴天, 72°F"; } } // 在 Program.cs 中 builder.Services.AddSingleton<WeatherFunctions>(); builder.AddAIAgent("ChatAgent", (sp, key) => { var searchFunctions = sp.GetRequiredService<SearchFunctions>(); var weatherFunctions = sp.GetRequiredService<WeatherFunctions>(); var chatClient = sp.GetRequiredService<IChatClient>(); return chatClient.CreateAIAgent( name: key, instructions: "你可以搜索文档和查询天气...", tools: [ AIFunctionFactory.Create(searchFunctions.SearchAsync), AIFunctionFactory.Create(weatherFunctions.GetWeatherAsync) ] ).Build(); }); 6.2 多代理场景
代理框架可以轻松协调多个专用代理：
// 注册研究代理 builder.AddAIAgent("ResearchAgent", (sp, key) => { var chatClient = sp.GetRequiredService<IChatClient>(); var searchFunctions = sp.GetRequiredService<SearchFunctions>(); return chatClient.CreateAIAgent( name: "ResearchAgent", instructions: "你是研究专家。从文档中查找和总结信息。", tools: [AIFunctionFactory.Create(searchFunctions.SearchAsync)] ).Build(); }); // 注册写作代理 builder.AddAIAgent("WritingAgent", (sp, key) => { var chatClient = sp.GetRequiredService<IChatClient>(); return chatClient.CreateAIAgent( name: "WritingAgent", instructions: "你是写作专家。获取信息并创建结构良好、引人入胜的内容。", tools: [] ).Build(); }); // 注册协调代理 builder.AddAIAgent("CoordinatorAgent", (sp, key) => { var chatClient = sp.GetRequiredService<IChatClient>(); var researchAgent = sp.GetRequiredKeyedService<AIAgent>("ResearchAgent"); var writingAgent = sp.GetRequiredKeyedService<AIAgent>("WritingAgent"); // 创建委托给其他代理的函数 async Task<string> ResearchAsync(string topic) { var messages = new[] { new ChatMessage(ChatRole.User, topic) }; var result = await researchAgent.RunAsync(messages); return result.Text ?? ""; } async Task<string> WriteAsync(string content) { var messages = new[] { new ChatMessage(ChatRole.User, $"基于以下内容写文章: {content}") }; var result = await writingAgent.RunAsync(messages); return result.Text ?? ""; } return chatClient.CreateAIAgent( name: "CoordinatorAgent", instructions: "协调研究和写作以创建全面的文章。", tools: [ AIFunctionFactory.Create(ResearchAsync), AIFunctionFactory.Create(WriteAsync) ] ).Build(); }); 6.3 自定义代理中间件
可以添加自定义中间件进行日志记录、缓存或自定义行为：
builder.AddAIAgent("ChatAgent", (sp, key) => { var chatClient = sp.GetRequiredService<IChatClient>(); var searchFunctions = sp.GetRequiredService<SearchFunctions>(); var logger = sp.GetRequiredService<ILogger<Program>>(); return chatClient.CreateAIAgent( name: key, instructions: "...", tools: [AIFunctionFactory.Create(searchFunctions.SearchAsync)] ) .AsBuilder() .Use(async (messages, options, next, cancellationToken) => { // 自定义预处理 logger.LogInformation("代理正在处理 {MessageCount} 条消息", messages.Count()); // 调用管道中的下一个 var result = await next(messages, options, cancellationToken); // 自定义后处理 logger.LogInformation("代理生成了包含 {ContentCount} 个内容项的响应", result.Contents.Count); return result; }) .UseOpenTelemetry(configure: c => c.EnableSensitiveData = true) .Build(); }); 7. 最佳实践
7.1 设计清晰的工具描述
代理工具调用的质量很大程度上取决于良好的描述：
[Description("在产品文档中搜索特定信息。" + "当用户询问功能、规格或产品使用方法时使用此工具。" + "返回带有文件名和页码的相关摘录以供引用。")] public async Task<IEnumerable<string>> SearchAsync( [Description("要搜索的特定短语、关键字或问题。" + "要具体并包含相关上下文。")] string searchPhrase, [Description("可选: 要搜索的精确文件名(如'ProductManual.pdf')。" + "留空则搜索所有文档。")] string? filenameFilter = null) { // 实现 } 7.2 测试代理行为
为代理工具创建单元测试，为代理工作流创建集成测试：
public class SearchFunctionsTests { [Fact] public async Task SearchAsync_WithValidQuery_ReturnsResults() { // 准备 var mockSemanticSearch = new Mock<SemanticSearch>(); mockSemanticSearch .Setup(s => s.SearchAsync("test", null, 5)) .ReturnsAsync(new List<IngestedChunk> { new IngestedChunk { DocumentId = "test.pdf", PageNumber = 1, Text = "测试内容" } }); var searchFunctions = new SearchFunctions(mockSemanticSearch.Object); // 执行 var results = await searchFunctions.SearchAsync("test"); // 断言 Assert.NotEmpty(results); Assert.Contains("测试内容", results.First()); } } 7.3 监控代理性能
使用 Application Insights 或 .NET Aspire 的仪表板监控：
- 每次代理交互的令牌使用量
- 工具调用模式(使用哪些工具，使用频率)
- 代理操作的响应时间
- 工具调用的错误率
- 通过反馈机制获得的用户满意度
8. 性能考虑
8.1 流式与非流式
代理框架支持流式和非流式响应：
使用流式的情况：
- 构建交互式聊天界面
- 用户期望实时反馈
- 处理长时间运行的查询
使用非流式的情况：
- 后台处理
- 批量操作
- 简单 API 端点
8.2 工具调用优化
尽量减少不必要的工具调用：
// 好: 具体指令 "仅当用户询问关于文档的具体问题时使用搜索工具。 如果可以从常识中回答，则不搜索。" // 不好: 模糊指令 "你可以访问搜索工具。" 9. 部署到 Azure
应用已准备好使用 .NET Aspire 的 Azure 预配进行部署：
# 登录 Azure az login # 创建 Azure 资源 cd ChatApp20.AppHost azd init azd up 这将：
- 预配 Azure OpenAI 资源
- 将 Web 应用部署到 Azure 容器应用
- 设置 Application Insights 进行监控
- 配置服务连接和身份验证
结论
通过本文的步骤，我们成功将标准的 AI 聊天应用升级为使用 Microsoft 代理框架的智能代理系统。这一升级带来了更清晰的架构关注点分离、更轻松的测试和内置的可观测性，同时仍然使用 .NET 开发者熟悉的模式。
Microsoft 代理框架的优势在于它不需要开发者学习全新的方式，而是建立在依赖注入、中间件和遥测等熟悉的 .NET 概念之上。无论是简单的工具调用还是复杂的多代理协调，该框架都提供了强大而灵活的功能来满足各种业务需求。
随着 AI 技术的不断发展，采用代理框架将使您的应用能够更好地适应未来需求，提供更智能、更自然的用户体验。
