目录一句话简介 核心价值 核心接口 执行流程 三个核心方法详解典型应用场景 实现示例用户信息记忆 最佳实践✅ DO - 推荐做法❌ DONT - 避免的错误 总结上一篇一句话简介AIContextProvider 是 MAF 的抽象基类用于在 Agent 调用 AI 模型前后注入自定义逻辑实现用户信息记忆、知识库检索等企业级功能。 核心价值✅InvokingAsync调用模型前注入上下文用户信息、知识库检索结果✅InvokedAsync调用模型后提取信息更新内部状态✅Serialize序列化记忆状态支持持久化和跨 Thread 共享 核心接口public abstract class AIContextProvider { // 1️⃣ 调用前注入上下文信息 public virtual ValueTaskAIContext InvokingAsync( InvokingContext context, CancellationToken ct default); // 2️⃣ 调用后提取信息更新状态 public virtual ValueTask InvokedAsync( InvokedContext context, CancellationToken ct default); // 3️⃣ 序列化保存记忆状态 public virtual JsonElement Serialize( JsonSerializerOptions? options null); } 执行流程 三个核心方法详解方法执行时机主要用途返回值InvokingAsync调用模型前注入 Instructions、MessagesAIContextInvokedAsync调用模型后提取信息、更新状态ValueTaskSerializeThread 序列化时保存记忆状态JsonElement典型应用场景场景InvokingAsyncInvokedAsync用户信息记忆注入已知姓名、年龄从对话中提取新信息知识库检索(RAG)注入检索到的文档记录检索命中情况个性化配置根据用户偏好调整 Instructions学习用户偏好统计分析注入用户行为统计更新统计数据 实现示例用户信息记忆public sealedclassUserInfoMemory : AIContextProvider { privatereadonly IChatClient _chatClient; // ❌ 不序列化 public UserInfo UserInfo { get; set; } // ✅ 序列化 // 构造函数1首次创建 public UserInfoMemory(IChatClient chatClient, UserInfo? userInfo null) { _chatClient chatClient; UserInfo userInfo ?? new UserInfo(); } // 构造函数2反序列化恢复 public UserInfoMemory(IChatClient chatClient, JsonElement serializedState, ...) { _chatClient chatClient; UserInfo serializedState.DeserializeUserInfo()!; } // 调用前注入用户信息 public override ValueTaskAIContext InvokingAsync(...) { var instructions UserInfo.UserName isnull ? Ask the user for their name. : $The users name is {UserInfo.UserName}.; returnnew ValueTaskAIContext(new AIContext { Instructions instructions }); } // 序列化只保存数据状态 public override JsonElement Serialize(...) { return JsonSerializer.SerializeToElement(UserInfo); } } 最佳实践✅ DO - 推荐做法// ✅ 分离数据状态和服务依赖 private readonly IChatClient _chatClient; // 不序列化 public UserInfo UserInfo { get; set; } // 序列化 // ✅ 实现两个构造函数 public MyProvider(IChatClient client) { } // 首次创建 public MyProvider(IChatClient client, JsonElement) { } // 反序列化 // ✅ 使用 ?? 运算符仅更新未知信息 UserInfo.UserName ?? extractedInfo.UserName; // ✅ 异常处理不影响主流程 try { /* 提取信息 */ } catch { Console.WriteLine(提取失败); }❌ DONT - 避免的错误// ❌ 序列化服务依赖 return JsonSerializer.SerializeToElement(new { ChatClient _chatClient }); // ❌ 在 InvokingAsync 中执行耗时操作 await _db.GetAsync(...); // 每次调用都执行 // ❌ 直接修改 Agent.Instructions agent.Instructions ...; // 应该通过 AIContext.Instructions 注入 总结✅三个核心方法InvokingAsync注入上下文、InvokedAsync提取信息、Serialize持久化✅两个构造函数首次创建 反序列化恢复✅分离原则数据状态序列化vs 服务依赖不序列化✅应用场景用户信息记忆、RAG、个性化配置、统计分析下一篇引入地址