目录一、为什么多 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 KernelSK的企业集成能力与 AutoGenAG的多 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( endpointcosmos_endpoint, credentialcredential, database_nameagent-runtime, container_nameworkflow-checkpoints, ) as checkpoint_storage: workflow ( WorkflowBuilder( start_executorintake, checkpoint_storagecheckpoint_storage, ) .add_edge(intake, analyze) .add_edge(analyze, approval) .add_edge(approval, publish) .build() ) async for event in workflow.run(request, streamTrue): await event_sink.write(event)三安全边界常被低估检查点本身就是高价值数据检查点可能包含用户输入、模型输出、工具参数、共享状态、待审批动作和外部资源标识。它既是恢复资产也是攻击面。官方文档将检查点存储明确视为信任边界并提醒 Python 的文件与 Cosmos 实现对非 JSON 类型使用pickle。框架默认采用受限反序列化器但若应用通过allowed_checkpoint_types放宽类型范围仍需进行安全审查。最低要求包括存储加密、最小权限、服务级身份、租户隔离、完整性保护、审计、保留与删除策略不得从不可信来源载入检查点敏感字段尽量只保存引用而非明文生产恢复流程要验证工作流版本、租户、运行 ID 和授权主体。检查点不是普通缓存不能按缓存的安全等级处理。安全恢复生命周期①运行状态②一致检查点③故障④从兼容拓扑恢复⑤以幂等与审计保护副作用。虚线表示恢复后的新执行分支。六、OpenTelemetry把“Agent 为什么这样做”变成可查询证据一内置遥测的价值是统一因果链而不是多几个日志1、从模型调用扩展到工作流执行传统 LLM 监控通常记录模型、token、延迟和错误码但多 Agent 故障经常发生在模型之外路由未命中、节点等待、工具超时、审批迟迟未到、恢复使用了错误版本。MAF 的 Agent 遥测遵循 OpenTelemetry GenAI Semantic ConventionsWorkflow 遥测又补充工作流构建、会话、调用周期、执行器、边组与消息发送等 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 都变成工作流活动。边界应按状态寿命和副作用责任划分。维度Microsoft Agent FrameworkLangGraphAutoGen / Semantic Kernel通用持久化工作流核心定位Agent 图式工作流 生产运行能力低层有状态 Agent 编排运行时微软前代 Agent/AI 应用框架跨服务可靠业务流程主力语言Python、.NETGo 独立 SDKPython、JavaScriptAutoGen 偏 PythonSK 覆盖 .NET/Python/Java多语言 SDK持久化superstep 检查点多种存储checkpointer/persistence能力分散需按项目评估原生 durable history/activity可观测内置 OTelAgent 与 Workflow span常与 LangSmith 组合也可接开放标准各自日志与追踪能力工作流历史与平台监控人工介入RequestPort 与工具审批事件interrupt persistence有 HITL 模式统一度较低外部事件/信号最适合微软生态、.NET 一等、跨语言团队Python/JS、精细图控制、LangChain 生态存量系统与渐进迁移超长业务流程、强补偿与定时器示意性选型矩阵横轴①为微软生态与跨语言贴合度纵轴②为通用持久化流程能力。MAF、LGLangGraph、AGAutoGen/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 框架而是把概率性模型接入确定性业务世界的一层可信运行时。可参考的文章与文档Microsoft Agent Framework GitHub 仓库与 READMEMicrosoft Agent Framework GitHub ReleasesMicrosoft Agent Framework at BUILD 20261.0 GA、Agent Harness 与 Hosted AgentsMicrosoft LearnAgent Framework 概览Microsoft LearnWorkflow 能力总览Microsoft LearnWorkflow CheckpointsMicrosoft LearnWorkflow Human-in-the-loopMicrosoft LearnWorkflow ObservabilityMicrosoft LearnAgent Observability 与 OpenTelemetryMicrosoft LearnWorkflow OrchestrationsSemantic Kernel 到 Agent Framework 迁移指南AutoGen 到 Agent Framework 迁移指南PyPIagent-frameworkNuGetMicrosoft.Agents.AILangGraph 官方概览AutoGen AgentChat 官方文档OpenTelemetryGenerative AI Semantic Conventions