MAF 快速入门：从 ChatClient 到 AIAgent

一句话简介

Microsoft Agent Framework (MAF) 是微软推出的企业级 AI Agent 开发框架，基于 Microsoft.Extensions.AI 构建，为开发者提供状态管理、身份定义和工具管理等高级能力。

---

🎯 核心价值

• ✅ 状态管理：内置 AgentThread 实现多轮对话记忆

• ✅ 身份定义：固定的 Instructions 和 Name，无需每次传入

• ✅ 工具管理：Agent 级别统一管理工具集合

• ✅ 企业级：构建在 MEAI 之上，适合生产环境

---

📝 Agent vs ChatClient：什么时候用 Agent？

很多开发者会困惑：我已经有 IChatClient 了，为什么还需要 Agent？

特性	IChatClient	AIAgent
定位	💬 底层 AI 调用抽象	🤖 高级智能体封装
状态管理	❌ 无状态，每次调用独立	✅ 内置对话线程 (AgentThread)
身份定义	❌ 需手动传入 System Message	✅ 固定的 Instructions 和 Name
工具管理	⚠️ 需手动配置 ChatOptions.Tools	✅ Agent 级别统一管理
使用场景	🔧 单次对话场景	🏢 多轮交互、企业级对话系统

简单来说：

• ChatClient = 纯函数：给定输入，返回输出，不保留状态

• Agent = 有记忆的助手：有固定身份、能记住上下文、能使用工具

---

🏗️ MAF 架构定位

MAF 构建在 Microsoft.Extensions.AI 之上，提供更高层次的抽象，让开发者专注于业务逻辑。

---

💻 快速开始：创建第一个 Agent

三步创建 Agent

完整示例：口语教练 Agent

// 1. 获取底层 ChatClient
var chatClient = AIClientHelper.GetDefaultChatClient();

// 2. 创建 Agent
AIAgent spokenEnglishCoach = chatClient.CreateAIAgent(
    instructions: "你是一位专业的英语口语教练。帮助学生提升英语口语能力，始终保持鼓励和友好的态度。",
    name: "SpokenEnglishCoach"
);

// 3. 调用 Agent (同步模式)
var response = await spokenEnglishCoach.RunAsync(
    "我想提高英语口语能力，但不知道从哪里开始。你能给我一些建议吗?"
);

Console.WriteLine($"🤖 {spokenEnglishCoach.Name}: {response}");

核心要点：

• 🔧 instructions：定义 Agent 的角色和行为（System Message）

• 🔧 name：Agent 的唯一标识，用于日志和调试

• 🔧 RunAsync：同步调用，等待完整响应

---

🌊 流式调用：提升用户体验

同步调用需要等待完整响应，用户体验不佳。流式调用可以逐字显示 AI 的响应，就像 ChatGPT 那样。

对比：同步 vs 流式

流式调用示例

// 流式调用，逐块输出
await foreach (var chunk in spokenEnglishCoach.RunStreamingAsync(
    "请讲解如何练习英语的连读技巧，并给出例子。"
))
{
    Console.Write(chunk); // 逐块输出，不换行
}

核心差异：

• 同步：RunAsync() → Task<string>

• 流式：RunStreamingAsync() → IAsyncEnumerable<string>

---

🏢 MAF 核心概念

三大核心组件

组件	功能	说明
AIAgent	智能代理	具有固定身份（Name + Instructions）和工具集合
AgentThread	对话线程	维护独立的对话历史，支持序列化
AgentRun	执行实例	每次调用创建一个 Run，返回响应

---

⚠️ 当前限制：无法记住历史

上面的示例中，每次调用 RunAsync() 都是独立的单次对话，Agent 不会记住之前的内容。

问题演示：

// 第一轮
var response1 = await spokenEnglishCoach.RunAsync("我叫张三，我想学英语口语。");

// 第二轮 - Agent 无法记住 "我叫张三"
var response2 = await spokenEnglishCoach.RunAsync("你知道我叫什么名字吗?");
// ❌ Agent 会回答：抱歉，我不知道您的名字...

💡 解决方案：AgentThread

要实现多轮对话记忆，需要使用 AgentThread：

// 创建对话线程
var thread = agent.GetNewThread();

// 所有对话使用同一个 thread
await agent.RunAsync("我叫张三", thread);
await agent.RunAsync("你知道我叫什么吗?", thread); 
// ✅ 能够记住："您好，张三！"

AgentThread 将在下节课详细讲解。

---

🎯 总结

• ✅ MAF 定位：构建在 MEAI 之上的企业级 Agent 框架，提供状态管理和工具能力

• ✅ Agent vs ChatClient：Agent 是有状态、有身份的智能体，适合多轮对话场景

• ✅ 创建 Agent：chatClient.CreateAIAgent(instructions, name) 三步完成

• ✅ 调用模式：同步调用 RunAsync() 和流式调用 RunStreamingAsync()

• ✅ 核心概念：Agent（智能代理）、Thread（对话线程）、Run（执行实例）

• ⚠️ 当前限制：单次调用无历史记忆，需使用 AgentThread 解决（下节课）

下节课预告： 《多轮对话与上下文管理》—— 深入 AgentThread 的创建、使用和持久化。

---

如需获取文章配套完整代码，可扫码咨询领取。👇