目录

一、为什么多 Agent 的难点从来不只是“多几个提示词”

（一）原型成功往往掩盖了运行时缺口

（二）“框架”真正应该消除的是重复的工程决策

二、从两条产品线合流，到一个明确的生产平台

（一）Semantic Kernel 与 AutoGen 分别解决了什么

1、Semantic Kernel 的优势是企业集成与统一抽象

2、AutoGen 的优势是多 Agent 协作模式与研究速度

（二）合流的意义不是“二选一”，而是收敛维护面

（三）截至 2026 年 8 月的成熟度应重新判断

1、核心框架已经进入 GA 后持续发布阶段

2、GA 不等于所有扩展都稳定

三、理解 MAF：不是一层 API，而是四层运行时

（一）Agent 抽象层：把提供方差异压到边界

1、统一的运行接口降低上层耦合

2、工具、中间件与上下文提供器形成可组合管线

（二）工作流层：把 Agent 当作图中的执行者

（三）运行与持久化层：让一次执行拥有可恢复身份

（四）运维与交互层：让系统可看、可停、可干预

四、图式编排的价值：把协作模式变成可治理拓扑

（一）五种常见模式不是功能清单，而是控制权分配

1、顺序模式：阶段边界最清晰

2、并发模式：降低延迟，但增加汇合复杂度

3、Handoff：把路由决定交给 Agent，把拓扑权留给开发者

4、Group Chat：共享讨论空间需要明确终止条件

5、Magentic 模式：适合动态规划，不适合默认套用

（二）superstep 是理解并发、检查点和可观测的共同钥匙

1、每一轮形成一致的逻辑边界

2、边不是简单连线，而是消息交付规则

五、检查点：把“失败重跑”升级为“有语义地恢复”

（一）检查点解决的是进度保存，更是副作用边界

1、可恢复不等于可安全重放

1.1 外部副作用必须拥有稳定操作标识

2、恢复要求拓扑与执行器身份稳定

2.1 工作流定义需要版本化与兼容策略

（二）三类 Python 存储体现了不同可靠性等级

1、内存存储只适合测试与短任务

2、文件存储适合单机恢复与开发验证

3、Cosmos DB 存储面向分布式生产

（三）安全边界常被低估：检查点本身就是高价值数据

六、OpenTelemetry：把“Agent 为什么这样做”变成可查询证据

（一）内置遥测的价值是统一因果链，而不是多几个日志

1、从模型调用扩展到工作流执行

2、span link 更符合异步消息的真实因果关系

（二）可观测性必须和隐私策略一起设计

1、敏感内容默认不应进入生产遥测

2、从“能看 trace”走向可运营指标

2.1 指标应覆盖可靠性、效率、治理与质量

七、Human-in-the-loop：不是弹窗，而是一种持久化协议

（一）人工介入应发生在风险边界，而不是每一步

1、审批点应该与副作用和不确定性对齐

2、RequestPort 把人类变成外部异步参与者

（二）一个合格的审批对象必须包含决策上下文

（三）暂停与恢复引入了新的并发问题

八、开发体验：声明式配置、DevUI 与 Agent Harness 各自解决什么

（一）YAML 的价值在于可审查配置，不是取代代码

（二）DevUI 缩短的是反馈回路，不是替代测试体系

（三）Agent Harness 把长循环常见能力进一步产品化

九、分发与托管：框架解决执行语义，平台解决运行环境

（一）PyPI 与 NuGet 让 MAF 更容易进入现有工程体系

（二）Foundry Hosted Agents 提供的是托管生产面

（三）第三方系统责任不会因微软背书而消失

十、MAF 与同类方案：真正的分界线在运行时与生态偏好

（一）MAF 与 LangGraph 的能力重叠比表面更大

（二）AutoGen 与 Semantic Kernel 更适合被视为迁移来源

（三）通用工作流引擎仍可能是关键搭档

十一、一个可落地的生产参考架构

（一）把控制面、执行面与数据面分开

1、控制面管理定义、策略与版本

2、执行面运行 MAF 并处理事件

3、数据面按用途拆分

（二）以“供应商准入审查”工作流为例

1、阶段设计

2、恢复与可观测设计

十二、落地路线：先证明可恢复，再扩大自主性

（一）第一阶段：建立可测的单 Agent 基线

（二）第二阶段：用图拆开确定性与概率性步骤

（三）第三阶段：验证检查点、恢复和幂等

（四）第四阶段：加入人工治理与分级权限

（五）第五阶段：托管、容量与持续评估

十三、需要正视的限制与风险

（一）统一 API 不能消除提供方语义差异

（二）高频发布会带来升级治理成本

（三）“内置”不等于“自动满足合规”

（四）多 Agent 可能成为不必要的复杂度

十四、结论：MAF 的核心价值是一套“可运行的承诺”

可参考的文章与文档

干货分享，感谢您的阅读！

如果把一个大模型请进公司，它大概像一位聪明得令人不安、偶尔又会记错会议室号码的新同事；如果再请来五个 Agent，让它们分工、讨论、互相交接，现场很容易从“智能协作”升级成“数字版办公室连续剧”。演示时，一切都很丝滑：规划者拆任务，研究者找资料，审校者挑毛病，几十秒后端出漂亮答案。可一到生产环境，剧情立刻换台——模型限流、工具超时、审批人下班、网络中断，退款接口也许已经执行，工作流却只留下半截聊天记录。最尴尬的问题不再是“Agent聪不聪明”，而是“它刚才做了什么，接下来从哪里继续，出了问题谁负责”。

Microsoft Agent Framework正为这些“不够酷、却会半夜叫醒工程师”的问题而来。它不像又一位抢镜的超级Agent，更像舞台监督、交通警察、黑匣子与应急预案的合体：用图式Workflow安排顺序、并发、移交与群体协作，用检查点保存长任务进度，用OpenTelemetry串起模型、工具、消息和审批的因果链，再借助人工介入，让高风险动作在落地前停下来等人签字。更值得关注的是，MAF把Semantic Kernel的企业集成基因与AutoGen的多Agent经验汇入同一套运行时，试图把两条技术路线收拢为生产底座。

当然，框架不是万能防事故符。检查点不等于副作用幂等，看得见trace也不等于可以随意记录敏感数据，Agent会交接更不意味着它该拥有无限权限。本文将从架构、编排、恢复、可观测、治理与选型边界逐层拆解MAF，看看它究竟解决了什么、还把哪些责任留给业务系统，以及团队如何避免把一场精彩演示，部署成凌晨三点的事故复盘会。

一、为什么多 Agent 的难点从来不只是“多几个提示词”

（一）原型成功往往掩盖了运行时缺口

一个多 Agent 演示通常很容易令人兴奋：规划者拆分任务，研究者调用搜索，写作者形成初稿，审校者给出修改意见，几十行代码便能展示“协作”。但当同一套逻辑进入真实业务，问题会迅速从模型能力转向系统能力。一次执行可能持续数十分钟，横跨多个模型、工具、数据源和审批人；任一节点都可能限流、超时、返回格式错误，或者产生具有现实副作用的动作。如果系统只保留一段聊天记录，那么失败后究竟从哪里继续、哪些工具已经执行、是否会重复扣款、谁批准了某次操作，都没有可靠答案。

生产系统关心的不是 Agent 是否偶尔给出漂亮答案，而是它能否在大量不理想条件下保持可解释的行为。模型输出具有概率性，外部工具具有故障性，网络具有不确定性，人类反馈具有延迟性。三者叠加以后，多 Agent 应用本质上更接近一个分布式、事件驱动、长时间运行的业务流程，而不是一个加长版聊天机器人。

因此，生产化至少需要五类统一契约：第一，执行拓扑与状态转移契约；第二，消息、工具调用和副作用的边界契约；第三，暂停、检查点与恢复契约；第四，追踪、指标和审计契约；第五，人工审批与安全策略契约。缺少任何一类，都可以通过应用代码临时补齐，但系统越复杂，补丁之间越容易互相冲突。

多 Agent 生产化能力栈：①编排契约；②状态与恢复；③可观测；④人工介入；⑤安全治理。右侧箭头表示能力从“能运行”向“可负责”递进。

（二）“框架”真正应该消除的是重复的工程决策

团队当然可以自行组合模型 SDK、消息队列、状态数据库、工作流引擎、OpenTelemetry、审批系统和前端调试台。问题不在于这些组件不可获得，而在于它们之间缺少共享语义。例如，工作流引擎认为一次活动已经成功，Agent 层却还没持久化工具结果；遥测系统记录了模型调用，却没有把它和上游路由、下游人工审批串成同一条因果链；恢复逻辑重放节点后，又触发了一次不可重复的支付操作。

这类问题无法靠“再加一个库”自动解决。需要有人定义：一次 Agent 运行的身份是什么，节点完成的边界在哪里，状态在何时形成一致快照，恢复时拓扑必须满足哪些条件，敏感输入能否进入遥测，人工响应如何与等待中的请求精确匹配。Microsoft Agent Framework（下文简称 MAF）的目标，正是把这些决策上移为统一运行时能力，让 Python、.NET 以及独立 Go SDK 中的 Agent 和工作流拥有相近的操作模型。

这也解释了为什么评价 MAF 不能只看“支持多少模型”“有没有群聊模式”。真正有区分度的问题是：它是否把长任务的生命周期做成了可操作对象，是否能把执行状态与可观测上下文关联起来，是否允许业务在关键副作用之前插入明确的人工控制点。围绕这些问题，MAF 才体现出从开发框架到生产底座的野心。

二、从两条产品线合流，到一个明确的生产平台

（一）Semantic Kernel 与 AutoGen 分别解决了什么

1、Semantic Kernel 的优势是企业集成与统一抽象

Semantic Kernel 长期擅长把模型能力嵌入常规应用：连接不同推理服务，把函数暴露为工具，管理提示模板、插件、内存与依赖注入，并在 .NET 生态中提供自然的工程体验。它的核心视角更接近“如何让现有应用安全地使用 AI 服务”，因此在企业身份、Azure 服务和传统软件架构的衔接上有明显优势。

但随着 Agent 需求增长，以 Kernel 为中心的对象结构也带来一定复杂度。不同后端往往对应不同 Agent 类型，线程或会话的创建与清理需要调用者理解提供方差异，工具又常通过插件与 Kernel 间接注册。微软当前迁移指南把 MAF 的变化概括为更简化的 API、统一的提供方接口和更直接的工具注册，这表明合流并非简单改名，而是对对象模型进行收敛。

2、AutoGen 的优势是多 Agent 协作模式与研究速度

AutoGen 把“多个角色通过消息协作”变成易于表达的编程模式。AgentChat、群聊、选择器、Swarm、Magentic-One 等能力降低了多角色原型的门槛，也形成了丰富的研究与社区实践。它证明了多 Agent 不是单一调度算法，而是一组可组合的协作范式：轮流发言、动态选择、任务移交、计划与执行分离，以及专门的终止条件。

AutoGen 的强项也意味着它更靠近探索前沿。生产团队若要获得跨运行恢复、稳定的持久化契约、统一遥测以及和企业宿主的一致集成，往往仍需额外设计。MAF 吸收了这些协作思想，同时将它们放入统一的 Agent 抽象、图式工作流和运行时能力中。

（二）合流的意义不是“二选一”，而是收敛维护面

微软在 2026 年 Build 相关文章中明确表示，MAF 1.0 GA 带来了 AutoGen 与 Semantic Kernel 的合流，并定位为单一、受支持的平台。这句话的重要性在于，它改变了技术选型的时间尺度。过去，团队可能分别评估 SK 的企业集成和 AutoGen 的多 Agent 表达；现在，新项目更应先把 MAF 视为微软 Agent 技术路线的收敛点，再判断是否存在必须留在旧栈的兼容性理由。

合流并不表示旧代码会自动迁移，也不表示两套框架的所有行为都一一对应。迁移指南显示，命名空间、Agent 类型、会话、工具注册、调用方法和返回类型均有变化。MAF 还允许将 Semantic Kernel 的 KernelFunction 转换为 Agent Framework 工具，为渐进迁移保留了桥梁。这种桥梁比“一次性重写”更符合生产现实：先稳定边界，再替换内部实现，最后迁移工作流和运维面。

Semantic Kernel（SK）的企业集成能力与 AutoGen（AG）的多 Agent 协作经验，在 MAF 中收敛，并于 2026 年 4 月进入 1.0 GA。

（三）截至 2026 年 8 月的成熟度应重新判断

1、核心框架已经进入 GA 后持续发布阶段

MAF 于 2026 年 4 月 2 日达到 1.0 GA。撰写时 PyPI 的agent-framework最新公开版本为 1.16.0，发布日期是 2026 年 8 月 28 日；GitHub Releases 同时列出 .NET 1.19.0。NuGet 的Microsoft.Agents.AI页面也显示 1.19.0。版本号并非质量证明，但高频迭代、跨语言同步文档以及正式迁移指南，说明它已经从“方向性预览”进入可被严肃评估的产品阶段。

README 当前还把 Go 支持单独指向microsoft/agent-framework-go。因此，“多语言”已经不应只理解为 Python 与 .NET；更准确的说法是：Python 与 .NET 是主仓库中的核心实现，Go 通过独立 SDK 承担相同方向的扩展。跨语言概念接近，不代表 API、持久化格式和功能成熟度完全等价，架构评审仍应以目标语言的具体实现为准。

2、GA 不等于所有扩展都稳定

MAF 仓库同时存在稳定包、预览连接器、带 beta 标识的集成，以及 AF Labs 下的研究能力。2026 年 8 月的发布资产中，核心元包已经稳定，而 Anthropic、A2A 或部分 Azure 集成仍可能以 beta 版本独立发布。Build 文章中的 CodeAct 也明确位于 alpha 包。正确的生产判断应在“框架整体已经 GA”和“能力成熟度按包分层”之间保持张力。

因此，采购式问法“MAF 能不能上生产”过于粗糙。更可执行的问题是：计划使用的核心包是否稳定；目标提供方连接器是否稳定；所需持久化后端是否满足合规；恢复语义是否覆盖本业务的副作用；团队是否接受当前版本的升级频率。只有这些答案同时成立，GA 标签才会转化为真正的上线信心。

三、理解 MAF：不是一层 API，而是四层运行时

（一）Agent 抽象层：把提供方差异压到边界

1、统一的运行接口降低上层耦合

MAF 希望应用以相近方式运行不同提供方的 Agent。在 Python 中，常用入口是Agent、BaseAgent与SupportsAgentRun；在 .NET 中则以AIAgent、ChatClientAgent和Microsoft.Extensions.AI的消息类型为基础。调用侧围绕run、流式更新、会话和工具工作，不必让业务流程直接依赖每个模型服务的线程类型。

这种抽象的价值并不是让所有后端“看起来完全一样”。真正的价值是把差异压到适配层：某个会话可能保存在本地，也可能由服务管理；某个提供方支持原生工具审批，另一个需要框架模拟；某个模型返回推理更新，另一个只返回最终文本。统一接口让工作流只依赖可承诺的公共能力，而把提供方特性留在明确的选项类型中。

2、工具、中间件与上下文提供器形成可组合管线

工具让模型产生外部动作；中间件在请求、响应、异常或工具调用周围插入策略；上下文提供器则为 Agent 注入记忆、文件、技能或会话信息。三者共同构成“模型之外的执行环境”。认证、限流、缓存、内容过滤、租户隔离、费用标记、重试与审计，都可以在这一层统一实现，而不必散落在每个 Agent 的提示词里。

这里有一个重要设计原则：提示词应该表达角色、目标与判断标准，不应该承担可靠性协议。把“失败重试三次”“敏感工具必须审批”“记录租户 ID”等规则写进系统提示，只是让模型知晓策略，并不能确保策略执行。中间件和运行时钩子才是强制边界。

（二）工作流层：把 Agent 当作图中的执行者

MAF 的 Workflow 不仅可以编排 Agent，也可以编排普通确定性执行器。图由节点、边、消息、共享状态和外部请求构成。一个节点可以调用模型，也可以运行规则引擎、访问数据库、验证模式或生成文档。这样，团队可以在同一条流程中混合确定性步骤与概率性步骤：金额校验由代码完成，例外解释由模型生成，最终发布再由人工批准。

这是生产 Agent 的关键形态。完全自由的 Agent 循环难以预测成本和副作用，完全确定的工作流又无法利用模型处理模糊信息。图式运行时允许开发者决定“哪里交给模型，哪里必须确定”，并通过边的条件和消息类型显式控制流向。

（三）运行与持久化层：让一次执行拥有可恢复身份

工作流运行不仅是一个函数调用，而是包含输入、事件流、当前状态、待处理消息、外部请求和检查点的生命周期对象。MAF 按 superstep 推进工作流：同一轮中可执行的节点完成后，运行时在轮次边界形成一致状态，并为下一轮准备消息。这个模型类似批量同步并行思想，天然适合表达并发分支与汇合。

检查点并不是把聊天文本定期写入数据库。官方文档说明，一个检查点可以捕获所有执行器状态、下一 superstep 的待处理消息、未完成的请求与响应以及共享状态。Python 1.13.0 起还增加入口检查点与响应交付检查点，使完整运行更易重放。只有覆盖这些内容，系统恢复后才知道“下一步应该做什么”，而不仅是“之前说过什么”。

（四）运维与交互层：让系统可看、可停、可干预

MAF 内置 OpenTelemetry 集成，Agent 与 Workflow 都能产生追踪、指标和日志。Workflow 级 span 覆盖构建、会话、单次调用、执行器处理、边组处理和消息发送；消息传递通过 span link 表达因果，而不是错误地伪装成同步嵌套调用。对于并发、扇入和异步路由，这种建模比简单父子树更准确。

DevUI 面向本地开发、测试与调试；Human-in-the-loop 通过请求/响应通道暂停工作流，等待外部系统或人类回复；Hosted Agents 则把容器、身份、弹性伸缩、会话状态和监控放入 Foundry 托管环境。四层组合以后，MAF 才形成从代码到运行的完整叙事。

MAF 四层运行时：①Agent 抽象与中间件；②图式 Workflow；③检查点与持久化；④遥测、调试和人工控制。

四、图式编排的价值：把协作模式变成可治理拓扑

（一）五种常见模式不是功能清单，而是控制权分配

1、顺序模式：阶段边界最清晰

顺序编排让 Agent 或执行器依次接收上一步结果，适合“提取—验证—生成—审校”这类管线。它的优势是因果关系清晰、成本容易估计、检查点自然；缺点是总延迟累加，前序错误会沿链传播。生产实现中应让每一步输出结构化结果，并在进入下一节点前做模式验证，而不是把大段自由文本不断拼接。

2、并发模式：降低延迟，但增加汇合复杂度

并发模式让多个专家同时处理同一输入，例如风险、合规、成本和用户体验四个评审 Agent 并行工作。它能显著缩短墙钟时间，却会引入配额竞争、结果顺序不确定、部分失败和汇合策略。汇合节点不能只做字符串拼接，而应明确最少成功数、超时窗口、冲突处理、去重与优先级。

3、Handoff：把路由决定交给 Agent，把拓扑权留给开发者

Handoff 的精髓是控制权转移。开发者声明哪些角色之间允许移交，框架向 Agent 注入相应的移交工具；Agent 根据对话与任务状态选择下一角色。这样既避免中央路由器成为所有领域规则的瓶颈，又避免 Agent 任意调用未授权角色。拓扑是治理边界，路由是运行时判断。

4、Group Chat：共享讨论空间需要明确终止条件

群体协作适合开放式评审、方案争论和共同完善，但也是最容易失控的模式。Agent 可能重复观点、互相附和或持续发言。生产使用必须设置选择策略、最大轮数、预算、终止条件和产出汇总者。群聊越自由，越需要强制性的外部边界。

5、Magentic 模式：适合动态规划，不适合默认套用

Magentic 类模式强调计划者根据进展持续重排任务，适合信息不完整、需要探索的复杂目标。代价是执行路径更难预估，成本与延迟更不稳定，恢复后还要判断计划是否仍有效。它应被视为高自主性模式，而不是“高级版顺序流程”。当业务步骤已经清楚时，确定性图通常更可靠。

五种编排模式：①顺序；②并发；③Handoff；④Group Chat；⑤Magentic 动态规划。图形只表达拓扑，不代表固定实现。

（二）superstep 是理解并发、检查点和可观测的共同钥匙

1、每一轮形成一致的逻辑边界

MAF Workflow 以 superstep 为单位推进。可以把它理解为：当前有资格运行的一组执行器消费消息、更新状态并产生下一轮消息；本轮全部完成后，系统才进入下一轮。并发节点因此共享一个逻辑阶段，检查点也能在阶段末捕获一致快照。

这种边界比“每执行一行就保存”更高效，也比“整条流程结束才保存”更可靠。它还为遥测提供稳定粒度：一个工作流会话可以包含多次输入到暂停的 invoke cycle，每次 cycle 内又包含多个 executor 与 edge span。运维人员可以从业务运行一路下钻到具体消息路由。

2、边不是简单连线，而是消息交付规则

边可以包含条件、类型和扇入逻辑。官方 Workflow 遥测会记录delivered、dropped type mismatch、dropped target mismatch、dropped condition false、buffered与exception等交付状态。这说明框架把“消息为何没有到达”视为一等运维问题。

在多 Agent 故障排查中，这一点非常重要。很多所谓的“模型不回复”其实是路由条件未满足、消息类型不兼容或扇入仍在等待。若系统只记录模型调用日志，团队会把运行时错误误判为模型质量问题。边级遥测把隐藏的控制流显性化。

五、检查点：把“失败重跑”升级为“有语义地恢复”

（一）检查点解决的是进度保存，更是副作用边界

1、可恢复不等于可安全重放

假设工作流已经调用银行接口创建退款，随后在生成通知邮件时崩溃。恢复到退款之前会导致重复退款，恢复到退款之后又要求系统证明该操作确实成功。检查点只能告诉运行时状态在哪里，不能自动保证外部副作用幂等。因此，生产设计必须同时使用业务幂等键、操作日志或 transactional outbox，把外部动作的事实与工作流状态关联起来。

1.1 外部副作用必须拥有稳定操作标识

推荐做法是为每个有副作用的工具调用生成稳定的operation_id，由目标系统或适配层实现去重；工具返回中记录外部资源 ID；在检查点前确保结果进入可持久化状态。恢复后，执行器先查询该operation_id的结果，再决定跳过、补偿或重试。这样，检查点负责“恢复控制流”，幂等协议负责“保护现实世界”。

2、恢复要求拓扑与执行器身份稳定

官方文档明确指出，重新水合的工作流必须保持创建检查点时的拓扑和执行器身份。.NET 中，本地 ChatClientAgent 若跨请求、依赖注入作用域或部署重建，应设置稳定且唯一的 Agent ID；如果设置了 Name，也要保持不变。使用对话 ID、请求 ID、用户 ID或敏感信息作为 Agent ID 都是不合适的。

2.1 工作流定义需要版本化与兼容策略

这意味着工作流定义也需要版本化。一次运行开始后，如果团队发布了拓扑变更，旧检查点未必能由新版本安全恢复。成熟做法是把workflow_definition_version写入运行元数据，保留兼容的旧执行镜像，或提供显式迁移函数。数据库 schema 有迁移，长运行 Agent 的状态同样需要迁移纪律。

（二）三类 Python 存储体现了不同可靠性等级

1、内存存储只适合测试与短任务

InMemoryCheckpointStorage在进程退出后丢失状态，适合单元测试、演示和短生命周期工作流。它可以验证暂停与恢复逻辑，但不能证明跨进程恢复，更不能用来支撑生产可用性结论。

2、文件存储适合单机恢复与开发验证

FileCheckpointStorage把状态写入指定目录，可跨进程重启，适合单机部署和本地调试。容器环境中必须确认目录挂载到持久卷，并处理并发访问、备份、加密与权限。它不是天然的分布式一致存储。

3、Cosmos DB 存储面向分布式生产

CosmosCheckpointStorage通过独立扩展包提供跨进程持久化，并以工作流名称作为分区键。它更接近生产多实例部署需要，但仍应设计租户隔离、吞吐容量、保留期限、灾备和数据驻留。使用托管身份与 RBAC 通常优于长期账户密钥。

下面的 Python 片段展示的是结构，而不是完整业务代码：

from agent_framework import WorkflowBuilder from agent_framework_azure_cosmos import CosmosCheckpointStorage async with CosmosCheckpointStorage( endpoint=cosmos_endpoint, credential=credential, database_name="agent-runtime", container_name="workflow-checkpoints", ) as checkpoint_storage: workflow = ( WorkflowBuilder( start_executor=intake, checkpoint_storage=checkpoint_storage, ) .add_edge(intake, analyze) .add_edge(analyze, approval) .add_edge(approval, publish) .build() ) async for event in workflow.run(request, stream=True): await event_sink.write(event)

（三）安全边界常被低估：检查点本身就是高价值数据

检查点可能包含用户输入、模型输出、工具参数、共享状态、待审批动作和外部资源标识。它既是恢复资产，也是攻击面。官方文档将检查点存储明确视为信任边界，并提醒 Python 的文件与 Cosmos 实现对非 JSON 类型使用pickle。框架默认采用受限反序列化器，但若应用通过allowed_checkpoint_types放宽类型范围，仍需进行安全审查。

最低要求包括：存储加密、最小权限、服务级身份、租户隔离、完整性保护、审计、保留与删除策略；不得从不可信来源载入检查点；敏感字段尽量只保存引用而非明文；生产恢复流程要验证工作流版本、租户、运行 ID 和授权主体。检查点不是普通缓存，不能按缓存的安全等级处理。

安全恢复生命周期：①运行状态；②一致检查点；③故障；④从兼容拓扑恢复；⑤以幂等与审计保护副作用。虚线表示恢复后的新执行分支。

六、OpenTelemetry：把“Agent 为什么这样做”变成可查询证据

（一）内置遥测的价值是统一因果链，而不是多几个日志

1、从模型调用扩展到工作流执行

传统 LLM 监控通常记录模型、token、延迟和错误码，但多 Agent 故障经常发生在模型之外：路由未命中、节点等待、工具超时、审批迟迟未到、恢复使用了错误版本。MAF 的 Agent 遥测遵循 OpenTelemetry GenAI Semantic Conventions，Workflow 遥测又补充工作流构建、会话、调用周期、执行器、边组与消息发送等 span。

这使一次业务请求可以形成跨层追踪：入口 API span 关联工作流会话，工作流调用关联多个执行器，Agent span 关联模型与工具，消息发送再通过 span link 连接到目标执行器。团队可以回答：哪个 Agent 消耗最多 token，哪个边经常丢弃消息，哪类审批导致最长停顿，恢复后的运行是否延续了正确上下文。

2、span link 更符合异步消息的真实因果关系

同步函数调用天然适合父子 span；消息发送和目标消费却不一定嵌套。MAF 使用 link 把发送 span 与目标执行 span 关联，并在扇入场景中允许多个来源共同指向一个处理节点。这避免了把异步系统硬塞成调用树，也为关键路径分析提供更准确的数据模型。

（二）可观测性必须和隐私策略一起设计

1、敏感内容默认不应进入生产遥测

MAF 的敏感数据记录默认关闭。启用后，提示、响应、函数调用参数与结果可能进入 span 或日志。官方文档明确建议只在安全的开发或测试环境使用。生产系统应建立字段分级：运行 ID、模型、延迟、token 和错误类型通常可记录；用户正文、工具参数和业务结果需要脱敏、哈希、采样或完全禁止。

另一个细节是重复采集。如果同时在 ChatClient 与 Agent 层启用包含内容的遥测，上下文可能在两个 span 中重复出现，扩大泄露面与存储成本。正确做法是决定哪个层级负责内容级证据，其余层仅记录元数据和关联 ID。

2、从“能看 trace”走向可运营指标

2.1 指标应覆盖可靠性、效率、治理与质量

追踪适合调查单次异常，指标适合发现系统性趋势。建议基于 OTel 数据构建四组 SLI：可靠性包括工作流完成率、恢复成功率、节点重试率和消息丢弃率；效率包括端到端时延、关键路径时长、token 与工具成本；治理包括审批命中率、拒绝率、越权工具请求和敏感数据拦截；质量包括结构化输出通过率、人工修改率和任务返工率。

这些指标应带上工作流版本、Agent 角色、模型、提供方、租户等级和环境等低基数字段。不要把完整用户 ID、提示文本或请求 ID放进指标标签，否则会造成隐私与基数爆炸。高基数细节留在受控追踪或审计存储中。

OpenTelemetry 因果链：①Workflow 会话；②并行执行器；③模型或工具 span；④汇合与结果。虚线 link 表达异步消息因果。

七、Human-in-the-loop：不是弹窗，而是一种持久化协议

（一）人工介入应发生在风险边界，而不是每一步

1、审批点应该与副作用和不确定性对齐

让人审核所有模型输出会把自动化变成人工流水线；完全不审核又可能放大错误。适合强制介入的场景通常具备至少一个特征：不可逆或高成本副作用，如付款、删除、发布和权限变更；高影响决策，如信贷、医疗和雇佣建议；模型置信不足或输入冲突；跨越数据与合规边界；需要人类补充框架无法获取的信息。

低风险读取、格式转换和可撤销草稿一般不应阻塞。可以通过工具分类、参数条件、金额阈值、环境和用户角色决定是否审批。人工介入是策略引擎的结果，不应仅靠 Agent 自己“觉得要不要问”。

2、RequestPort 把人类变成外部异步参与者

MAF Workflow 使用类型化 RequestPort 表达请求与响应。执行器发送请求后，运行时发出 RequestInfoEvent；外部审批服务、前端或操作人员处理该事件，再把响应路由回原执行器。工作流可以在此暂停，并结合检查点跨越几分钟、几小时甚至更长时间。

这种模型比在 Agent 函数中等待终端输入更适合生产，因为审批渠道与执行进程解耦。审批人可以通过企业门户、Teams、移动端或工单系统响应；工作流服务可以重启；响应仍能凭请求 ID 回到正确的等待点。

（二）一个合格的审批对象必须包含决策上下文

只显示“是否允许调用 send_email”是不够的。审批对象至少应包含：工作流与业务对象标识、发起 Agent、工具名称、参数摘要、预期副作用、目标资源、风险等级、证据来源、可选动作、过期时间和策略依据。若允许编辑参数，还要记录修改前后差异；若拒绝，要把结构化原因传回 Agent，避免它用另一种方式重复同一危险动作。

审批记录应独立进入不可篡改审计链，不能只存在于模型对话中。批准者身份、时间、设备或渠道、决策、修改内容以及随后真正执行的工具结果，都要能够关联。这样才能证明“有人批准了什么”，而不是仅证明“系统曾经弹出一个请求”。

（三）暂停与恢复引入了新的并发问题

审批期间，业务对象可能被其他流程修改；价格、库存、权限或政策也可能变化。恢复前应重新验证前置条件，必要时让审批失效。可以采用乐观并发版本、资源 ETag、审批有效期和二次确认。对于高风险动作，批准的应是精确参数哈希，而不是模糊意图。

此外，审批响应可能重复提交或乱序到达。响应处理必须幂等，并验证请求是否仍处于待处理状态。工作流运行时负责路由，但业务仍要定义“迟到的批准是否有效”“多人审批如何汇总”“一个拒绝是否立即终止”等规则。

人工介入闭环：①生成待审动作；②发出结构化请求；③批准、编辑或拒绝；④恢复工作流并保留审计记录。

八、开发体验：声明式配置、DevUI 与 Agent Harness 各自解决什么

（一）YAML 的价值在于可审查配置，不是取代代码

声明式 Agent 允许用 YAML 定义名称、指令、模型与工具引用，便于版本管理、环境覆盖和非核心代码评审。它适合稳定的角色定义和部署配置，也便于在多个语言实现间共享意图。然而，复杂分支、动态权限、错误补偿和强类型业务规则仍更适合代码。

生产团队应把 YAML 纳入与代码相同的供应链：schema 校验、密钥外置、变更评审、环境差异检查和回滚。配置可读并不等于配置安全。尤其不要把 API Key、连接字符串或真实用户样例直接写进声明文件。

（二）DevUI 缩短的是反馈回路，不是替代测试体系

DevUI 适合交互式运行 Agent、观察消息与工具调用、检查工作流拓扑和快速复现问题。它把“写脚本—打印日志—猜发生了什么”的循环压缩为可视化探索。但 DevUI 中一次成功运行不能代表生产可靠性。

真正的质量体系仍需要：确定性单元测试验证执行器和边条件；记录回放验证兼容性；对抗性样例验证工具安全；离线评估验证输出质量；故障注入验证限流、超时和恢复；负载测试验证并发与配额；端到端测试验证审批、身份和数据边界。DevUI 是开发驾驶舱，测试和可观测平台才是运行保障。

（三）Agent Harness 把长循环常见能力进一步产品化

MAF 在 2026 年 Build 发布的 Agent Harness，把上下文压缩、文件记忆、文件访问、待办管理、计划/执行模式、技能发现、后台子 Agent、Web 搜索、工具审批和 OTel 等模式组合为更高层入口。它解决的是“自主 Agent 循环”的重复搭建问题，而 Workflow 解决的是显式多步骤拓扑。两者可以互补：Harness Agent 作为图中的高自主节点，Workflow 则为跨角色、审批与关键业务阶段提供外部控制。

需要警惕的是，Harness 的默认能力越丰富，权限面也越大。文件、Shell、Web 和后台 Agent 都必须受沙箱、目录白名单、网络策略、预算和审批控制。生产默认值应偏向最小权限，再按角色逐项开放。

九、分发与托管：框架解决执行语义，平台解决运行环境

（一）PyPI 与 NuGet 让 MAF 更容易进入现有工程体系

Python 可以安装完整元包，也可以只安装 core 与特定提供方，以减少依赖和攻击面；.NET 通过Microsoft.Agents.AI及 Foundry 等扩展包接入。选择性安装不仅是镜像大小优化，更是供应链治理：不用的连接器不应进入生产制品，不稳定扩展要与稳定核心分开升级。

跨语言团队应共享的是运行契约，而不是强行共享实现细节。可以统一工作流命名、Agent 角色 ID、遥测字段、审批对象 schema、幂等键规则和版本策略；具体服务仍用最适合的语言实现。这样，“多语言”才真正降低组织摩擦，而不是制造两个相似但不可互操作的代码库。

（二）Foundry Hosted Agents 提供的是托管生产面

微软将 Hosted Agents 描述为把自有代码打包为容器并运行在 Foundry 托管基础设施上，提供身份、自动伸缩、会话状态、可观测和版本能力。Build 资料还强调按会话隔离的 VM 沙箱、缩容到零以及恢复时保留文件系统和会话身份。对已经采用 Azure 的团队，这能显著减少宿主、身份和监控的拼装工作。

但框架与托管平台不应混为一谈。MAF 可以本地或自托管运行，也可以进入 Foundry；选择 Hosted Agents 会引入 Azure 平台、区域、成本、网络和合规约束。设计时应把 Agent 逻辑、工作流状态、外部工具与宿主绑定程度分别评估，避免为了便利把所有业务状态都锁进单一运行环境。

（三）第三方系统责任不会因微软背书而消失

MAF README 对第三方服务器、Agent、代码和非 Azure Direct 模型给出明确风险提示：数据处理、费用、合规边界与责任仍由使用者承担。提供方可插拔提升了架构选择自由，也扩大了数据流向与供应链范围。每个连接器都需要回答数据发送到哪里、保留多久、由谁计费、如何撤销凭据、发生故障如何降级。

十、MAF 与同类方案：真正的分界线在运行时与生态偏好

（一）MAF 与 LangGraph 的能力重叠比表面更大

LangGraph 同样定位为长时间运行、有状态 Agent 的低层编排框架，强调 durable execution、持久化、流式和 human-in-the-loop。把它简单描述为“只有图状态机，而 MAF 才有检查点”是不准确的。两者的真正差异更偏向生态、抽象边界和运维集成。

LangGraph 在 Python/JavaScript 与 LangChain/LangSmith 生态中拥有成熟实践，低层图控制细致，持久化与中断模型广为采用；MAF 的优势则是 .NET 一等公民、与 Microsoft.Extensions.AI 和 Azure/Foundry 的自然衔接、统一的 Agent/Workflow 叙事，以及开源 OTel 作为核心观测接口。LangGraph 的深度可观测通常与 LangSmith 组合，MAF 更强调标准化遥测后端选择。

（二）AutoGen 与 Semantic Kernel 更适合被视为迁移来源

对于新建微软技术栈项目，AutoGen 与 Semantic Kernel 已不宜再被当作与 MAF 完全平行的长期路线。它们仍有存量生态、特定能力和维护价值，但微软已经通过 GA 宣告收敛方向，并提供两套迁移指南。合理策略是先盘点现有资产，再渐进迁移，而不是因为“旧框架还能运行”就永久冻结架构。

AutoGen 用户应重点映射 AgentChat/Teams、状态、终止条件和自定义组件；SK 用户应重点映射 Kernel、插件/函数、Agent 类型、线程/会话和依赖注入。迁移不是语法替换，还要重新验证消息语义、工具调用、流式事件和遥测维度。

（三）通用工作流引擎仍可能是关键搭档

Temporal、Azure Durable Functions 等通用持久化工作流系统在事务活动、长期定时器、补偿和跨服务可靠执行方面经验深厚。MAF 的内置检查点足以覆盖大量 Agent 工作流，但若流程横跨数天、包含大量非 AI 微服务、需要严格的活动重试与补偿，通用引擎可能仍更合适。

一种常见组合是：外层 Durable/Temporal 管理业务流程、计时器和跨服务 SLA，内层 MAF 管理某个 AI 阶段的 Agent 协作、上下文和 OTel。不要为了“统一”而让 Agent 框架承担所有企业流程，也不要为了“可靠”而把每个模型 token 都变成工作流活动。边界应按状态寿命和副作用责任划分。

示意性选型矩阵：横轴①为微软生态与跨语言贴合度，纵轴②为通用持久化流程能力。MAF、LG（LangGraph）、AG（AutoGen/SK 存量路径）与 WF（通用工作流）的位置表示相对倾向，不是性能评分。

十一、一个可落地的生产参考架构

（一）把控制面、执行面与数据面分开

1、控制面管理定义、策略与版本

控制面保存 Workflow 定义版本、Agent 角色与稳定 ID、模型路由策略、工具权限、审批规则、预算、评估集和发布记录。变更需要代码评审与自动验证，并能把一次运行准确映射到当时的定义和策略。控制面不承载长时间模型调用，以免配置发布与执行负载互相影响。

2、执行面运行 MAF 并处理事件

执行面接收请求，创建带全局 run ID 的 Workflow，运行 Agent 与确定性执行器，向检查点存储写入状态，向 OTel Collector 输出遥测，向审批队列发布 RequestInfoEvent。执行实例应无状态或只保留可重建缓存，扩缩容不能影响恢复。

3、数据面按用途拆分

检查点存储保存恢复所需状态；业务数据库保存业务事实；对象存储保存大文件与中间制品；向量或搜索服务提供检索；审计仓保存不可变审批与工具操作记录；遥测后端保存 traces、metrics、logs。不要把所有数据塞进 Agent 会话，也不要把业务事实仅保存在检查点里。

（二）以“供应商准入审查”工作流为例

1、阶段设计

入口执行器验证申请 schema 并分配业务 ID；并发分支分别进行合规检索、财务风险摘要、合同条款抽取和制裁名单查询；汇合节点验证四类结果是否齐全；决策 Agent 根据政策生成建议；确定性规则检查金额与风险阈值；高风险项目通过 RequestPort 进入人工委员会；获批后，发布工具写入供应商主数据并发送通知。

模型适合处理条款解释、证据摘要和冲突说明；制裁名单命中、金额阈值、身份匹配与最终写入则由确定性代码承担。每个外部查询具有缓存与幂等键，写入工具要求审批令牌和操作 ID。

2、恢复与可观测设计

每个 superstep 形成检查点。并发分支中单个查询失败时，只重试该分支；超过阈值后进入人工补充，而不是重跑全部分析。工作流版本、政策版本和证据时间戳进入共享状态。OTel trace 记录各分支时延、模型与 token、边交付状态和审批等待时间，但不记录完整合同文本。

若系统在主数据写入后崩溃，恢复时发布执行器先用operation_id查询写入结果；若已完成则补发通知，若未完成才执行写入。这个例子说明：MAF 提供恢复和路由骨架，业务仍负责幂等、证据有效期和最终一致性。

生产参考架构：①控制面保存定义、策略和版本；②执行面运行 Agent 与 Workflow 并输出 OTel；③数据面拆分检查点、业务事实、制品和审计。

十二、落地路线：先证明可恢复，再扩大自主性

（一）第一阶段：建立可测的单 Agent 基线

先选择一个边界清晰、可回退、没有高风险副作用的任务。定义输入输出 schema、质量评估集、token 与延迟预算，把模型调用放入统一 Agent 接口，加入最小 OTel。此时不要急于拆成多个角色；如果单 Agent 加工具已经足够，多 Agent 只会增加成本和故障点。

验收标准包括：固定测试集达到质量门槛；错误能分类；所有运行带版本与 trace ID；敏感内容默认不进入遥测；工具调用有超时与参数校验。只有基线清晰，后续拆分才知道是否真正改进。

（二）第二阶段：用图拆开确定性与概率性步骤

把流程中具有不同失败语义、权限或扩缩容特征的阶段拆成执行器。引入顺序和有限并发，使用结构化消息，显式定义边条件和汇合策略。为每个角色设置稳定 ID，并冻结第一版 Workflow schema。

此阶段重点不是增加 Agent 数，而是让控制流可观察。团队应能从 trace 看出每个节点的输入摘要、耗时、结果状态和路由原因；能在不调用模型的情况下测试大部分边逻辑；能计算每个阶段对质量和成本的边际贡献。

（三）第三阶段：验证检查点、恢复和幂等

启用持久化检查点，构造进程崩溃、模型限流、工具超时、节点异常和审批跨重启等测试。恢复不应只验证“最后拿到答案”，还要验证没有重复副作用、事件顺序合理、旧检查点与新版本隔离、敏感数据受保护。

建议建立恢复测试矩阵：在每个 superstep 后注入故障；对每个副作用工具重复投递；在审批前后重启；删除临时缓存；模拟存储短暂不可用；使用不兼容拓扑尝试恢复并确认安全失败。可恢复性必须通过故障实验获得，而不是从 API 名称推断。

（四）第四阶段：加入人工治理与分级权限

根据工具风险建立权限表，默认拒绝高风险动作。实现结构化审批对象、过期策略、参数哈希、多人规则和审计。将拒绝原因作为受控反馈返回 Agent，并防止模型绕过审批调用等价工具。

同时实施会话、文件、网络和模型预算隔离。不同 Agent 不应共享相同的全能凭据；检索 Agent 无需发布权限，写作 Agent 无需数据库删除权限。高自主性 Harness 节点尤其要限制文件根目录、Shell 命令、网络域名和子 Agent 数量。

（五）第五阶段：托管、容量与持续评估

最后再决定自托管或 Foundry Hosted Agents。基于真实 trace 进行容量规划：并发分支放大模型 QPS 的倍数，检查点写入频率，审批积压，冷启动，Cosmos 分区吞吐，OTel 采样和遥测成本。建立版本灰度、回滚与会话粘性策略。

生产后持续运行离线评估与在线监控。模型更新、提示变更、连接器升级和工作流拓扑变化都可能改变质量。把关键运行样例去敏后沉淀为回归集，按照工作流版本比较完成率、人工修改率、成本和风险事件，而不是只看平均满意度。

十三、需要正视的限制与风险

（一）统一 API 不能消除提供方语义差异

不同模型和托管 Agent 对会话、工具、流式、推理内容、文件、取消和错误码的支持不同。公共抽象只能覆盖交集，提供方特性仍会通过专用选项泄露到应用。若团队大量依赖某个后端的独特能力，更换提供方仍可能需要重写和重新评估。

（二）高频发布会带来升级治理成本

GA 后 MAF 仍以较快节奏发布，2026 年 7 月至 8 月的 Python 版本连续推进，检查点文档还提到 1.13.0 对迭代计数、消息来源 ID 与顺序带来小幅破坏性变化。生产团队应锁定版本、阅读 release notes、运行检查点兼容测试，并为跨版本长会话制定策略。不能把包自动升级等同于常规补丁更新。

（三）“内置”不等于“自动满足合规”

OpenTelemetry 内置并不意味着追踪内容天然安全；检查点内置并不意味着存储天然合规；HITL 内置也不意味着审批政策合理。框架提供机制，组织仍要定义数据分类、权限、保留、审计、模型风险和责任人。尤其在金融、医疗、政府与跨境数据场景，平台便利不能替代合规设计。

（四）多 Agent 可能成为不必要的复杂度

角色拆分会增加模型调用、上下文复制、路由错误和调试难度。只有当任务确实具有可并行专业分工、不同权限边界、不同模型需求或独立失败语义时，多 Agent 才产生结构性收益。否则，一个带好工具、明确 schema 和验证器的 Agent 往往更便宜、更快、更可靠。

十四、结论：MAF 的核心价值是一套“可运行的承诺”

MAF 最值得关注的地方，不是它又提供了多少种 Agent 协作示例，而是它试图把 Agent 系统最难统一的工程语义放进同一个框架：统一 Agent 接口与中间件，图式工作流与多种协作模式，superstep 检查点与恢复，RequestPort 人工介入，基于 OpenTelemetry 的跨层因果追踪，以及从本地 DevUI 到 Foundry 托管的运行路径。

截至 2026 年 8 月，它已经越过 1.0 GA，并持续快速迭代。对微软生态、.NET 团队或希望 Python 与 .NET 共享运行概念的组织，MAF 已经是应进入正式技术评估的候选。对深度依赖 LangChain/LangSmith 的 Python/JavaScript 团队，LangGraph 仍是成熟而有竞争力的选择。对横跨大量非 AI 服务、需要严格活动补偿的超长流程，通用持久化工作流引擎仍可能是外层骨架。

最终选型不应从 star 数或演示效果出发，而应从五个问题出发：流程能否在任意关键点安全恢复；副作用能否幂等；一次决策能否形成可查询证据；高风险动作能否被可靠拦截；版本升级后旧运行能否继续处理。若 MAF 能在目标语言、目标连接器和目标合规环境中给出满意答案，它就不仅是一个 Agent 框架，而是把概率性模型接入确定性业务世界的一层可信运行时。

可参考的文章与文档

1. Microsoft Agent Framework GitHub 仓库与 README

2. Microsoft Agent Framework GitHub Releases

3. Microsoft Agent Framework at BUILD 2026：1.0 GA、Agent Harness 与 Hosted Agents

4. Microsoft Learn：Agent Framework 概览

5. Microsoft Learn：Workflow 能力总览

6. Microsoft Learn：Workflow Checkpoints

7. Microsoft Learn：Workflow Human-in-the-loop

8. Microsoft Learn：Workflow Observability

9. Microsoft Learn：Agent Observability 与 OpenTelemetry

10. Microsoft Learn：Workflow Orchestrations

11. Semantic Kernel 到 Agent Framework 迁移指南

12. AutoGen 到 Agent Framework 迁移指南

13. PyPI：agent-framework

14. NuGet：Microsoft.Agents.AI

15. LangGraph 官方概览

16. AutoGen AgentChat 官方文档

17. OpenTelemetry：Generative AI Semantic Conventions