在 .NET AI 聊天應用中升級到 Microsoft 代理框架
引言
隨着人工智能技術的快速發展，簡單的聊天機器人已經不能滿足複雜業務場景的需求。Microsoft 代理框架（Microsoft Agent Framework）為 .NET 開發者提供了構建智能代理（AI Agent）的能力，使應用程序能夠實現多步推理、工具調用和複雜工作流編排。本文將詳細介紹如何將一個基礎的 .NET AI 聊天應用升級為基於 Microsoft 代理框架的智能代理系統，包括環境準備、框架集成、功能擴展和最佳實踐等內容。
1. Microsoft 代理框架概述
Microsoft 代理框架是微軟推出的 .NET AI 代理開發框架，相比傳統聊天機器人，它具有以下核心能力：
- 多步驟工作流推理：能夠分解複雜任務為多個執行步驟
- 工具調用能力：可與API、數據庫和服務進行交互
- 上下文保持：維護整個對話的上下文一致性
- 自主決策：根據指令和數據做出智能判斷
- 多代理協作：支持多個代理協同工作
該框架基於 .NET 開發者熟悉的模式構建，如依賴注入、中間件和遙測技術，與 Microsoft.Extensions.AI 深度集成，為開發者提供了熟悉的開發體驗。
2. 環境準備與基礎應用創建
2.1 先決條件
在開始升級前，需要準備以下環境：
- .NET 9 SDK
- Visual Studio 2022 或 VS Code（含 C# Dev Kit）
- Azure 賬號（可訪問 Azure OpenAI）
- 安裝 .NET AI 應用模板
2.2 創建基礎應用
使用 .NET AI 模板創建基礎聊天應用：
dotnet new install Microsoft.Extensions.AI.Templates
dotnet new ai-chat-webapp -n ChatApp20 -ai azure-openai -vs local -or aspire該命令會創建一個包含三個項目的解決方案：
- ChatApp20.Web：Blazor Server 聊天界面
- ChatApp20.AppHost：.NET Aspire 業務流程
- ChatApp20.ServiceDefaults：共享服務配置
2.3 項目結構分析
關鍵文件結構如下：
ChatApp20/
├── ChatApp20.Web/
│ ├── Components/Pages/Chat/ # 聊天界面
│ ├── Services/ # 數據服務
│ ├── Program.cs # AI 配置
│ └── wwwroot/Data/ # 示例PDF
├── ChatApp20.AppHost/
└── ChatApp20.ServiceDefaults/初始的 Program.cs 已配置了 Azure OpenAI 客户端、語義搜索和向量存儲功能。
3. 集成 Microsoft 代理框架
3.1 安裝必要的 NuGet 包
在 ChatApp20.Web.csproj 中添加以下包引用：
<itemgroup>
<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>這些包提供了代理框架的核心功能、抽象定義和 OpenAI 集成支持。
3.2 創建專用工具服務
將搜索功能從 UI 組件移到專用服務類中：
using System.ComponentModel;
namespace ChatApp20.Web.Services;
public class SearchFunctions
{
private readonly SemanticSearch _semanticSearch;
public SearchFunctions(SemanticSearch semanticSearch)
{
_semanticSearch = semanticSearch;
}
[Description("Searches for information using a phrase or keyword")]
public async Task<ienumerable<string>> SearchAsync(
[Description("The phrase to search for.")] string searchPhrase,
[Description("Filter by filename if specified")] string? filenameFilter = null)
{
var results = await _semanticSearch.SearchAsync(searchPhrase, filenameFilter, 5);
return results.Select(r =>
$"<result filename="\"{r.DocumentId}\"" page_number="\"{r.PageNumber}\"">{r.Text}</result>");
}
}這種設計實現了關注點分離，便於測試和擴展。
3.3 配置 AI 代理
在 Program.cs 中註冊代理服務：
// 註冊搜索功能服務
builder.Services.AddSingleton<searchfunctions>();
// 配置 AI 代理
builder.AddAIAgent("ChatAgent", (sp, key) =>
{
var searchFunctions = sp.GetRequiredService<searchfunctions>();
var chatClient = sp.GetRequiredService<ichatclient>();
return chatClient.CreateAIAgent(
name: key,
instructions: "You are a helpful assistant that provides short and accurate answers.",
tools: [AIFunctionFactory.Create(searchFunctions.SearchAsync)]
)
.UseOpenTelemetry(c => c.EnableSensitiveData = builder.Environment.IsDevelopment())
.Build();
});關鍵配置點包括：
- 代理名稱標識
- 系統指令定義代理行為
- 工具註冊和方法綁定
- 集成遙測監控
4. 更新聊天界面組件
4.1 修改 Chat.razor
更新組件代碼以使用代理框架：
@inject IServiceProvider ServiceProvider
@using Microsoft.Agents.AI
@code {
private AIAgent _agent;
protected override void OnInitialized()
{
_agent = ServiceProvider.GetRequiredKeyedService<aiagent>("ChatAgent");
}
private async Task AddUserMessageAsync(ChatMessage userMessage)
{
// ... 原有消息處理邏輯
await foreach (var update in _agent.RunStreamingAsync(
messages.Skip(statefulMessageCount),
currentResponseCancellation.Token))
{
// 處理流式響應
}
}
}4.2 響應流處理
代理框架支持流式響應，提供更流暢的用户體驗。
5. 測試與驗證
5.1 使用 .NET Aspire 運行
.NET Aspire 提供了統一的服務管理面板，可以：
- 查看服務發現
- 監控日誌和遙測數據
- 檢查服務健康狀況
- 管理配置和密鑰
啓動應用後，Aspire 儀表板會自動打開，顯示各組件狀態和交互情況。
5.2 測試代理行為
典型的測試場景包括：
基礎對話測試：
用户：你好！
代理：你好！我是一個樂於助人的AI助手。工具調用測試：
用户：應急生存套裝應該包含哪些物品？
代理：基礎生存套裝應包含：<result filename="Survival_Kit.pdf" page_number="2">防水火柴、急救包...</result>文件特定查詢：
用户：GPS手錶有哪些功能？
代理：主要功能包括：<result filename="GPS_Watch.pdf" page_number="3">實時追蹤、路線規劃...</result>通過 Aspire 儀表板可以實時觀察代理的決策過程、工具調用參數和響應生成情況。
6. 高級應用場景
6.1 添加更多工具
擴展代理能力，如添加天氣查詢：
public class WeatherFunctions
{
[Description("獲取指定位置的天氣情況")]
public async Task<string> GetWeatherAsync(
[Description("城市名稱")] string city)
{
// 調用天氣API
return $"{city}天氣：晴，25°C";
}
}
// 註冊到代理
builder.AddAIAgent("ChatAgent", (sp, key) =>
{
// ... 其他配置
tools: [
AIFunctionFactory.Create(searchFunctions.SearchAsync),
AIFunctionFactory.Create(weatherFunctions.GetWeatherAsync)
]
});6.2 多代理協作
實現專業化代理協作：
// 研究代理
builder.AddAIAgent("ResearchAgent", (sp, key) =>
{
// 專注於信息檢索
});
// 寫作代理
builder.AddAIAgent("WritingAgent", (sp, key) =>
{
// 專注於內容生成
});
// 協調代理
builder.AddAIAgent("CoordinatorAgent", (sp, key) =>
{
// 協調其他代理工作
});這種架構適合複雜的內容生成場景。
6.3 自定義中間件
添加代理行為定製：
.AsBuilder()
.Use(async (messages, options, next, ct) =>
{
// 調用前處理
logger.LogInformation("Processing {count} messages", messages.Count());
var result = await next(messages, options, ct);
// 調用後處理
logger.LogInformation("Generated response");
return result;
})可用於實現緩存、日誌、驗證等橫切關注點。
7. 最佳實踐與性能優化
7.1 工具設計指南
- 提供清晰的工具描述
- 參數説明要詳細具體
- 返回格式標準化
- 錯誤處理要健壯
7.2 測試策略
編寫全面的單元和集成測試：
[Fact]
public async Task SearchAsync_ReturnsFormattedResults()
{
// 準備模擬數據
var mockSearch = new Mock<semanticsearch>();
mockSearch.Setup(x => x.SearchAsync("test", null, 5))
.ReturnsAsync(/* 測試數據 */);
// 執行測試
var functions = new SearchFunctions(mockSearch.Object);
var results = await functions.SearchAsync("test");
// 驗證結果
Assert.Contains("test data", results.First());
}7.3 性能考量
- 流式 vs 非流式：交互式場景用流式，批處理用非流式
- 工具調用優化：減少不必要的工具調用
- 監控指標：跟蹤令牌用量、響應時間、錯誤率等
7.4 部署到 Azure
使用 .NET Aspire 的 Azure 部署工具：
az login
cd ChatApp20.AppHost
azd init
azd up該流程會自動配置所有必要的 Azure 資源。
結論
通過將 .NET AI 聊天應用升級到 Microsoft 代理框架，開發者可以獲得更強大的AI能力，包括複雜任務處理、工具集成和多代理協作。本文詳細介紹了從環境準備、框架集成到高級應用的完整流程，並提供了最佳實踐指導。關鍵優勢包括：
- 架構清晰：實現關注點分離，提升可維護性
- 擴展性強：易於添加新工具和代理類型
- 開發友好：基於熟悉的 .NET 模式構建
- 可觀測性好：內置遙測和監控支持
隨着 AI 代理技術的不斷髮展，採用 Microsoft 代理框架將為 .NET 開發者提供構建下一代智能應用的堅實基礎。
