引言

随着人工智能技术的快速发展，简单的聊天机器人已经不能满足复杂业务场景的需求。Microsoft 代理框架（Microsoft Agent Framework）为 .NET 开发者提供了构建智能代理（AI Agent）的能力，使应用程序能够实现多步推理、工具调用和复杂工作流编排。本文将详细介绍如何使用 Microsoft Agent Framework 构建智能代理，帮助 .NET 开发者快速上手这一强大的 AI 开发工具。

一、Microsoft Agent Framework 概述

1.1 核心能力

Microsoft Agent Framework 相比传统聊天机器人，具有以下核心能力：

• 多步骤工作流推理：能够分解复杂任务为多个执行步骤
• 工具调用能力：可与 API、数据库和服务进行交互
• 上下文保持：维护整个对话的上下文一致性
• 自主决策：根据指令和数据做出智能判断
• 多代理协作：支持多个代理协同工作

1.2 技术架构

该框架基于 .NET 开发者熟悉的模式构建，如依赖注入、中间件和遥测技术，与 Microsoft.Extensions.AI 深度集成，为开发者提供了熟悉的开发体验。

二、环境准备与基础应用创建

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 客户端、语义搜索和向量存储功能。

三、集成 Microsoft Agent Framework

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.1 修改 Chat.razor

更新组件代码以使用代理框架：

@inject IServiceProvider ServiceProvider
@using Microsoft.Agents.AI

@code {
    private AIAgent _agent;

    protected override void OnInitialized()
    {
        _agent = ServiceProvider.GetRequiredService<AIAgent>();
    }

    private async Task SendMessage()
    {
        var response = await _agent.SendAsync(new AIAgentMessage {
            Content = userInput,
            Role = AIAgentMessageRole.User
        });
        
        // 处理代理响应
        messages.Add(new ChatMessage {
            Content = response.Content,
            Role = ChatMessageRole.Assistant
        });
    }
}

4.2 处理代理响应

代理框架的响应可能包含工具调用和多轮对话，需要正确处理：

private async Task ProcessAgentResponse(AIAgentResponse response)
{
    if (response.ToolCalls.Any())
    {
        // 处理工具调用
        foreach (var toolCall in response.ToolCalls)
        {
            // 执行工具并获取结果
            var toolResult = await ExecuteToolCall(toolCall);
            
            // 将工具结果发送回代理
            var toolResponse = await _agent.SendAsync(new AIAgentMessage {
                Content = toolResult,
                Role = AIAgentMessageRole.Tool,
                ToolCallId = toolCall.Id
            });
            
            // 递归处理代理的新响应
            await ProcessAgentResponse(toolResponse);
        }
    }
    else
    {
        // 显示代理的最终回答
        messages.Add(new ChatMessage {
            Content = response.Content,
            Role = ChatMessageRole.Assistant
        });
    }
}

五、高级特性与最佳实践

5.1 多代理协作

对于复杂任务，可以创建多个代理协同工作：

// 创建多个专业代理
var researchAgent = chatClient.CreateAIAgent(
    name: "ResearchAgent",
    instructions: "You are an expert researcher who finds accurate information.",
    tools: [AIFunctionFactory.Create(searchFunctions.SearchAsync)]
);

var writingAgent = chatClient.CreateAIAgent(
    name: "WritingAgent",
    instructions: "You are a skilled writer who creates clear and engaging content.");

// 代理之间的协作
var researchResult = await researchAgent.SendAsync(new AIAgentMessage {
    Content = "Research the latest .NET AI features",
    Role = AIAgentMessageRole.User
});

var finalContent = await writingAgent.SendAsync(new AIAgentMessage {
    Content = $"Write an article based on this research: {researchResult.Content}",
    Role = AIAgentMessageRole.User
});

5.2 中间件使用

利用中间件增强代理功能：

// 添加日志中间件
builder.AddAIAgent("ChatAgent", (sp, key) => 
{
    var chatClient = sp.GetRequiredService<IChatClient>();
    
    return chatClient.CreateAIAgent(
        name: key,
        instructions: "You are a helpful assistant."
    )
    .UseMiddleware<LoggingMiddleware>()
    .UseMiddleware<ValidationMiddleware>()
    .Build();
});

5.3 最佳实践

• 明确的代理指令：为每个代理提供清晰、具体的指令
• 工具设计原则：工具应该职责单一，易于理解和使用
• 错误处理：实现完善的错误处理机制，确保代理在遇到问题时能够优雅降级
• 监控与日志：集成遥测和日志，以便跟踪代理的行为和性能
• 安全考虑：对工具调用进行适当的权限控制和输入验证

六、实际应用场景

6.1 企业知识管理

使用 Agent Framework 构建智能知识助手，帮助员工快速获取企业内部知识：

• 集成企业知识库和文档管理系统
• 提供自然语言查询接口
• 支持多轮对话和上下文理解

6.2 客户服务自动化

构建智能客服代理，处理常见客户问题：

• 自动回答常见问题
• 处理简单的业务流程
• 当遇到复杂问题时，平滑转接到人工客服

6.3 智能开发助手

为开发者提供智能编码助手：

• 代码生成和优化建议
• 技术文档查询和解释
• 问题排查和解决方案推荐

七、总结与展望

Microsoft Agent Framework 为 .NET 开发者提供了构建智能代理的强大工具，使应用程序能够实现更复杂、更智能的交互体验。通过本文的介绍，相信您已经对如何使用 Agent Framework 有了初步的了解。

随着 AI 技术的不断发展，Agent Framework 也在持续演进。未来，我们可以期待更多高级特性的加入，如更强大的多代理协作能力、更丰富的工具生态系统，以及更智能的决策机制。

作为 .NET 开发者，现在正是拥抱 AI 时代的最佳时机。通过掌握 Microsoft Agent Framework，您可以构建出更具竞争力的智能应用，为用户提供更优质的体验。

参考资料

• Microsoft Agent Framework 官方文档
• 在 .NET AI 聊天应用中升级到 Microsoft 代理框架
• 使用 C# 和 Microsoft Agent Framework 构建 AI 代理