MAF 现已更新至 1.0.0-rc4 版本，稳定性已显著提升。当然，此次升级过程充满挑战，尤其对一路持续跟进更新的开发者而言。

但曙光将近，最复杂的阶段即将过去，对于之前保持观望的.NET 开发者，现在正是上手实践的好时机，智能体时代已然到来。

以下内容出自我精心打造的《.NET+AI | 智能体开发进阶》课程，希望通过此次整理，帮助大家快速升级。该课程现已全面适配 MAF 最新版本，若你希望进行系统学习，高效掌握，少走弯路，欢迎阅读原文了解课程详情。

MAF Breaking Changes 完整汇总(截至 1.0.0-rc3)

来源：microsoft/agent-framework releases[1]
共整理 30 项 Breaking Changes，按版本倒序排列

🔴 dotnet-1.0.0-rc3（2026-03-04）

1. PR #4327[2] — Add response filter for store input in *Providers

变更说明： 为所有 *Provider（AIContextProvider / ChatHistoryProvider）增加了控制"是否存储输入消息"的响应过滤器，接口签名发生变化。

代码

Beforeprovider

 没有控制输入存储的过滤能力，所有输入消息默认被存储

After*Provider

 接口新增 Response Filter 参数/方法，用于决定是否将请求消息也存入存储层

2. PR #4395[3] — Change *Provider StateKey to list of StateKeys

变更说明： 将 AIContextProvider 和 ChatHistoryProvider 的单一 StateKey 属性替换为支持多键的 StateKeys 列表，并更新了 ChatClientAgent 的验证逻辑以检测所有键的冲突。

代码

Beforestring StateKey { get; }
AfterIReadOnlyList<string> StateKeys { get; }

迁移方案：将所有自定义 Provider 中的 StateKey 属性实现改为返回 IReadOnlyList<string> 的 StateKeys，例如 ["myKey"]。

🔴 dotnet-1.0.0-rc2（2026-02-25）

3. PR #4097[4] — Add ChatClient decorator for calling AIContextProviders

变更说明：AIContextProvider 和 ChatHistoryProvider 现在可以作为 IChatClient 装饰器使用。此变更更改了 Provider 的注册与调用方式。

代码

Before

Provider 直接附加到 AIAgent，只能在 Agent 上下文中调用

After

Provider 可作为 IChatClient 装饰器注入到管道中，更灵活地参与 ChatClient 调用链

🔴 dotnet-1.0.0-rc1（2026-02-20）

4. PR #3806[5] — Add session StateBag for state storage and support multiple providers on the Agent

变更说明： 在 AgentSession 中引入 StateBag 用于状态存储，Agent 现在支持同时挂载多个 Provider。移除了 InMemoryAgentSession，Provider 的 Serialize 方法也从 Provider 中移除。

代码

BeforeAgentSession

 无 StateBag；Provider 各自管理状态和序列化；使用 InMemoryAgentSession

AfterAgentSession.StateBag

 统一存储所有 Provider 状态；Provider 不再有 Serialize()；使用标准 AgentSession

迁移方案：删除对 InMemoryAgentSession 的引用；自定义 Provider 中移除 Serialize() 方法实现，改用 StateBag 存储状态。

5. PR #3761[6] — Structured Output improvements

变更说明： 删除了 AgentResponse.Deserialize<T>() / TryDeserialize<T>() 方法，移除了 RunAsync<object>() 重载，重构了结构化输出的使用方式。

代码

Beforevar result = response.Deserialize<MyClass>();

 或 agent.RunAsync<object>(...)

After

使用 RunAsync<T>() 泛型重载直接获取结构化输出，不再通过 Response 反序列化

6. PR #3900[7] — Refactor providers to move common functionality to base

变更说明： 将 AIContextProvider 和 ChatHistoryProvider 的公共功能下沉到基类，自定义 Provider 的继承结构发生变化。

代码

Before

自定义 Provider 直接实现接口并重复公共逻辑

After

继承自新的基类（AIContextProvider / ChatHistoryProvider），公共逻辑由基类提供

7. PR #3988[8] — Replace Typed Base Providers with Composition

变更说明： 删除了带泛型的类型化基类 Provider，改为使用组合模式。

代码

Beforeclass MyProvider : TypedAIContextProvider<MyState>
Afterclass MyProvider : AIContextProvider

，通过 StateBag 获取状态（组合方式）

8. PR #3441[9] — Unify AgentResponse[Update] events as WorkflowOutputEvents

变更说明：AgentResponseEvent 和 AgentResponseUpdateEvent 的父类从 ExecutorEvent 改为 WorkflowOutputEvent。AIAgentHostExecutor 内部改用 YieldOutputAsync() 代替 AddEventAsync()。

代码

BeforeAgentResponseEvent : ExecutorEvent

；使用 AddEventAsync(agentEvent)

AfterAgentResponseEvent : WorkflowOutputEvent

；使用 YieldOutputAsync(agentEvent)

迁移方案：如果在自定义 Executor 中监听 AgentResponseEvent，需更新对 WorkflowOutputEvent 的引用，并将 AddEventAsync 改为 YieldOutputAsync。

9. PR #3792[10] — Implement Polymorphic Routing

变更说明： Workflow 路由系统重构，支持多态消息类型路由，相关路由配置 API 发生变化。

代码

Before

路由基于单一消息类型

After

路由支持多态类型，需使用新的类型注册/路由 API

10. PR #4037[11] — Decouple Checkpointing from Run/StreamAsync APIs

变更说明： Checkpointing 从 Run/StreamAsync 的直接参数中解耦，改为 IWorkflowExecutionEnvironment 的属性。

代码

Beforeworkflow.RunAsync(input, checkpointManager: myCheckpointManager)
After

Checkpoint Manager 配置在 IWorkflowExecutionEnvironment 上，而不是作为运行时参数传入

11. PR #4090[12] — Workflows API Review Naming Changes (Part 1)

变更说明： 对 .NET Workflows 相关 API 进行了一批命名规范化重命名，以统一 API 风格。

代码

Before

部分 Workflow 类/方法使用旧命名约定

After

统一使用新命名规范（详情参见 PR 的 diff）

🟠 dotnet-1.0.0-preview.260205.1（2026-02-06）

12. PR #3501[13] — Rename GetNewSession to CreateSession

变更说明： 全局重命名，更清晰地表达语义（Session 不一定绑定到底层存储服务）。

代码

Beforeawait agent.GetNewSessionAsync()
Afterawait agent.CreateSessionAsync()

13. PR #3650[14] — Move AgentSession.Serialize to AIAgent

变更说明： 序列化责任从 Session 转移到 Agent，使 Agent 可以控制序列化格式。

代码

Beforestring json = session.Serialize();
Afterstring json = agent.SerializeSession(session);

14. PR #3681[15] — Rename session state json param

变更说明： Session 状态 JSON 参数名称的变更，影响反序列化相关重载方法。

代码

Before

参数名为旧命名（如 sessionJson 或 stateJson）

After

参数统一重命名以与 StateBag 设计保持一致

15. PR #3380[16] — Obsoleting ReflectingExecutor in favor of source gen

变更说明： 基于反射的消息处理器发现机制标记为过期，改用 [MessageHandler] 特性 + Source Generator 方式。

代码

Beforeclass MyExecutor : ReflectingExecutor<MyMessage>

 + 实现 IMessageHandler<T>

After

在方法上使用 [MessageHandler] 特性，由 Source Generator 自动生成注册代码

16. PR #3682[17] — Remove UserInputRequests property

变更说明： 从响应类型中移除了 UserInputRequests 属性。

代码

Beforeresponse.UserInputRequests

 可访问用户输入请求列表

After

属性已移除，应使用 Workflow 事件系统（WorkflowOutputEvent）处理用户输入请求

17. PR #3695[18] — Provide agent and session to AIContextProvider & ChatHistoryProvider

变更说明： Provider 的核心方法签名新增 agent 和 session 参数，让 Provider 在运行时可访问 Agent 和 Session 的上下文信息。

代码

BeforeTask<IList<ChatMessage>> GetContextAsync(CancellationToken ct)
AfterTask<IList<ChatMessage>> GetContextAsync(AIAgent agent, AgentSession session, CancellationToken ct)

迁移方案：所有自定义 AIContextProvider 和 ChatHistoryProvider 的方法实现需新增 AIAgent agent, AgentSession session 参数。

🟠 dotnet-1.0.0-preview.260127.1（2026-01-27）

18. PR #3250[19] — Allow passing auth token credential to CosmosDB extensions

变更说明： CosmosDB 扩展方法签名新增 TokenCredential 参数，支持托管身份认证，原有纯连接字符串的重载可能发生变化。

代码

Beforeservices.AddCosmosChatHistoryProvider(connectionString)
Afterservices.AddCosmosChatHistoryProvider(endpoint, new DefaultAzureCredential())

19. PR #3240[20] — Fix: Subworkflows do not work well with Chat Protocol and Checkpointing

变更说明： 修复 Subworkflow 与 Checkpointing 行为不一致的问题，带来部分 API 行为变化。CheckpointInfo 中的 RunId 处理方式变更，WorkflowHostExecutor.ResetAsync() 执行时机调整。

代码

Before

恢复 Checkpoint 时需要额外传入 RunId，可能与 CheckpointInfo 内的 Id 冲突

After

直接使用 CheckpointInfo 内部存储的 Id，避免外部传参错误

20. PR #3375[21] — Rename ChatMessageStore to ChatHistoryProvider

变更说明： 全面重命名，明确该组件是为 Agent 每次运行"提供"对话历史，而非通用 CRUD 存储。

旧名称

新名称

BeforeChatMessageStoreChatHistoryProvider
BeforeInMemoryChatMessageStoreInMemoryChatHistoryProvider
BeforeCosmosChatMessageStoreCosmosChatHistoryProvider
BeforeWorkflowMessageStoreWorkflowChatHistoryProvider

21. PR #3142[22] — Improve Agent hosting inside Workflows

变更说明：AIAgentBinding 的构造方式变更，新增 AIAgentHostOptions 配置类，替代原有的布尔参数。

代码

Beforenew AIAgentBinding(agent, emitAgentEvents: true)
Afternew AIAgentBinding(agent, new AIAgentHostOptions { ... })

22. PR #3430[23] — Rename AgentThread to AgentSession

变更说明： 核心概念重命名，AgentThread 更名为 AgentSession，更贴近实际语义。

旧名称

新名称

BeforeAgentThreadAgentSession
BeforeChatClientAgentThreadChatClientAgentSession
BeforeGetNewThreadAsync()

后续继续更名（见 PR #3501）

🟡 dotnet-1.0.0-preview.260121.1（2026-01-21）

23. PR #3152[24] — Change GetNewThread and DeserializeThread to async

变更说明： 将 GetNewThread 和 DeserializeThread 方法改为异步，以支持需要 I/O 的 Session 创建场景。

代码

BeforeAgentSession session = agent.GetNewThread();
AfterAgentSession session = await agent.GetNewThreadAsync();

24. PR #3197[25] — Rename AgentRunResponse and AgentRunResponseUpdate classes

变更说明： 响应类重命名，统一命名风格。

旧名称

新名称

BeforeAgentRunResponseAgentResponse
BeforeAgentRunResponseUpdateAgentResponseUpdate

25. PR #3214[26] — Rename AgentRunResponseEvent and AgentRunUpdateEvent classes

变更说明： 事件类重命名，与上面的响应类命名保持一致。

旧名称

新名称

BeforeAgentRunResponseEventAgentResponseEvent
BeforeAgentRunUpdateEventAgentResponseUpdateEvent

26. PR #3222[27] — Renamed CreateAIAgent/GetAIAgent to AsAIAgent

变更说明： 所有用于从外部客户端创建 AIAgent 包装器的扩展方法统一重命名为 AsAIAgent()。

旧方法

新方法

适用场景

BeforechatClient.CreateAIAgent()chatClient.AsAIAgent()

本地 ChatClient 包装

BeforeassistantClient.GetAIAgent(id)assistantClient.AsAIAgent(id)

OpenAI Assistant

BeforeazureClient.GetAIAgent(record)azureClient.AsAIAgent(record)

AzureAI Agent

Beforea2aClient.GetAIAgent(card)a2aClient.AsAIAgent(card)

A2A Agent

🟡 dotnet-1.0.0-preview.260108.1（2026-01-09）

27. PR #2749[28] — Introduce RunCoreAsync/RunCoreStreamingAsync delegation pattern in AIAgent

变更说明：AIAgent 子类不再重写 RunAsync/RunStreamingAsync，改为重写新的受保护方法 RunCoreAsync/RunCoreStreamingAsync。

代码

Beforeprotected override async IAsyncEnumerable<AgentResponseUpdate> RunAsync(...) { ... }
Afterprotected override async IAsyncEnumerable<AgentResponseUpdate> RunCoreAsync(...) { ... }

迁移方案：将所有自定义 Agent 中的 RunAsync / RunStreamingAsync 方法重命名为 RunCoreAsync / RunCoreStreamingAsync。

28. PR #2604[29] — Refactor ChatMessageStore methods to be similar to AIContextProvider and add filtering support

变更说明：ChatMessageStore（现已更名为 ChatHistoryProvider）的方法签名重构为与 AIContextProvider 保持一致的风格，并新增过滤支持。

代码

BeforeTask StoreAsync(IList<ChatMessage> messages)

 等简单方法

After

参数风格统一，增加 ChatHistoryContext / 过滤器参数，与 AIContextProvider 风格对齐

29. PR #3067[30] — Remove unused AgentThreadMetadata

变更说明： 删除了从未被使用的 AgentThreadMetadata 类。

代码

BeforeAgentThreadMetadata

 类存在

After

类已完全移除，所有对它的引用需删除

30. PR #2748[31] — Prevent loss of input messages & streamed updates when resuming streaming

变更说明： 为修复流式恢复时输入消息丢失的 Bug，将输入消息和流式更新保存到 ContinuationToken 中，ChatClientAgentContinuationToken 的结构发生变化。

代码

BeforeContinuationToken

 中不包含 Input messages 和流式更新

AfterChatClientAgentContinuationToken

 中额外存储输入消息与流式更新，以支持安全恢复

📋 Breaking Changes 快速索引表

#

PR

版本

变更类型

核心变化

1

#4327[2]

rc3

接口新增

*Provider

 增加 response filter

2

#4395[3]

rc3

属性类型变更

StateKey

 → StateKeys: IReadOnlyList<string>

3

#4097[4]

rc2

架构变更

Provider 支持作为 IChatClient 装饰器

4

#3806[5]

rc1

架构变更

引入 StateBag，移除 InMemoryAgentSession

5

#3761[6]

rc1

方法删除

删除 AgentResponse.Deserialize<T>()

6

#3900[7]

rc1

继承结构变化

Provider 公共功能移至基类

7

#3988[8]

rc1

设计模式变化

泛型 Provider 基类 → 组合模式

8

#3441[9]

rc1

继承链变化

AgentResponseEvent

 父类从 ExecutorEvent 改为 WorkflowOutputEvent

9

#3792[10]

rc1

路由 API 变化

多态路由重构

10

#4037[11]

rc1

API 解耦

Checkpointing 从运行参数改为 Environment 属性

11

#4090[12]

rc1

命名变更

Workflow API 批量重命名

12

#3501[13]

preview.260205

方法重命名

GetNewSessionAsync()

 → CreateSessionAsync()

13

#3650[14]

preview.260205

责任转移

session.Serialize()

 → agent.SerializeSession()

14

#3681[15]

preview.260205

参数重命名

Session state JSON 参数名变更

15

#3380[16]

preview.260205

过期/Source Gen

ReflectingExecutor

 → [MessageHandler] 特性

16

#3682[17]

preview.260205

属性删除

移除 UserInputRequests 属性

17

#3695[18]

preview.260205

方法签名变化

Provider 方法新增 agent, session 参数

18

#3250[19]

preview.260127

方法签名变化

CosmosDB 扩展支持 TokenCredential

19

#3240[20]

preview.260127

行为变更

Subworkflow + Checkpoint 行为修正

20

#3375[21]

preview.260127

类型重命名

ChatMessageStore

 → ChatHistoryProvider

21

#3142[22]

preview.260127

参数类型变更

AIAgentBinding

 参数改为 AIAgentHostOptions

22

#3430[23]

preview.260127

类型重命名

AgentThread

 → AgentSession

23

#3152[24]

preview.260121

同步→异步

GetNewThread/DeserializeThread

 → Async

24

#3197[25]

preview.260121

类型重命名

AgentRunResponse

 → AgentResponse

25

#3214[26]

preview.260121

类型重命名

AgentRunResponseEvent

 → AgentResponseEvent

26

#3222[27]

preview.260121

方法重命名

CreateAIAgent/GetAIAgent

 → AsAIAgent

27

#2749[28]

preview.260108

委托模式引入

子类重写 RunCoreAsync 代替 RunAsync

28

#2604[29]

preview.260108

方法签名变化

ChatMessageStore

 方法签名重构

29

#3067[30]

preview.260108

类型删除

移除 AgentThreadMetadata

30

#2748[31]

preview.260108

内部结构变化

ContinuationToken

 新增存储 input messages

💡 迁移建议： 从旧版本升级时，建议优先处理重命名类（#20、#22、#24、#25、#26）和方法签名变更（#17、#27），这两类影响范围最广。可参考 官方迁移文档[32] 获取进一步指引。

引用链接

[1] microsoft/agent-framework releases: https://github.com/microsoft/agent-framework/releases?q=dotnet&expanded=true
[2] PR #4327: https://github.com/microsoft/agent-framework/pull/4327
[3] PR #4395: https://github.com/microsoft/agent-framework/pull/4395
[4] PR #4097: https://github.com/microsoft/agent-framework/pull/4097
[5] PR #3806: https://github.com/microsoft/agent-framework/pull/3806
[6] PR #3761: https://github.com/microsoft/agent-framework/pull/3761
[7] PR #3900: https://github.com/microsoft/agent-framework/pull/3900
[8] PR #3988: https://github.com/microsoft/agent-framework/pull/3988
[9] PR #3441: https://github.com/microsoft/agent-framework/pull/3441
[10] PR #3792: https://github.com/microsoft/agent-framework/pull/3792
[11] PR #4037: https://github.com/microsoft/agent-framework/pull/4037
[12] PR #4090: https://github.com/microsoft/agent-framework/pull/4090
[13] PR #3501: https://github.com/microsoft/agent-framework/pull/3501
[14] PR #3650: https://github.com/microsoft/agent-framework/pull/3650
[15] PR #3681: https://github.com/microsoft/agent-framework/pull/3681
[16] PR #3380: https://github.com/microsoft/agent-framework/pull/3380
[17] PR #3682: https://github.com/microsoft/agent-framework/pull/3682
[18] PR #3695: https://github.com/microsoft/agent-framework/pull/3695
[19] PR #3250: https://github.com/microsoft/agent-framework/pull/3250
[20] PR #3240: https://github.com/microsoft/agent-framework/pull/3240
[21] PR #3375: https://github.com/microsoft/agent-framework/pull/3375
[22] PR #3142: https://github.com/microsoft/agent-framework/pull/3142
[23] PR #3430: https://github.com/microsoft/agent-framework/pull/3430
[24] PR #3152: https://github.com/microsoft/agent-framework/pull/3152
[25] PR #3197: https://github.com/microsoft/agent-framework/pull/3197
[26] PR #3214: https://github.com/microsoft/agent-framework/pull/3214
[27] PR #3222: https://github.com/microsoft/agent-framework/pull/3222
[28] PR #2749: https://github.com/microsoft/agent-framework/pull/2749
[29] PR #2604: https://github.com/microsoft/agent-framework/pull/2604
[30] PR #3067: https://github.com/microsoft/agent-framework/pull/3067
[31] PR #2748: https://github.com/microsoft/agent-framework/pull/2748
[32] 官方迁移文档: https://learn.microsoft.com/en-us/agent-framework/support/upgrade/

# .net
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

别让你的 Agent 一口吃成胖子：AI Agent 任务拆分的工程实践指南

avatar AI Agent技术社区
cover

AI Agent律师行业智能体的实践步骤

avatar AI Agent技术社区

MCP + 企业IM架构：AI Agent调用OA、ERP、MES时，身份和权限如何传递？

<think>我们只需要根据内容生成摘要，不超过150字。先理解文章核心：MCP+企业IM架构，AI Agent调用OA/ERP/MES时身份和权限传递。要点：IM从消息入口变任务入口；MCP解决连接，但不解决权限；需要五层身份映射；权限分层（可见性、调用、数据范围、确认）；建议组合MCP+API网关。摘要需简洁。 参考生成： "本文探讨MCP与企业IM集成中AI Agent调用业务系统时的身份权

avatar AI Agent技术社区