Microsoft Agent Framework · 起点

Microsoft Agent Framework:无状态 Agent + 两套编排运行时

本教程讲 MAF——微软把 AutoGen 与 Semantic Kernel 收敛成的同一套 agent SDK。基于 MAF 1.0 GA(2026-04 发布;截至 2026-06 为 Python 1.7 / .NET 1.8)。概念向、深度长文。代码示例未在本机运行验证;关键 API 名称、GA 日期与版本号已尽力对照官方文档,仍以官方最新文档为准。

·为什么会有 MAF

2025 年之前,微软同时维护两套相互重叠的 agent 框架,逼着开发者在"能力"和"稳定"之间二选一:

AutoGen——出自微软研究院(MSR),是多智能体前沿模式的研究载体。v0.4(2025-01)做了一次彻底重写,引入事件驱动的 actor 运行时 autogen-core。优点是模式新,缺点是 API 不稳定、不面向生产。
Semantic Kernel(SK)——出自产品组,是企业级生产 SDK。v1.0 早已稳定,带连接器、插件、遥测/过滤器、会话状态管理,支持 C#/Python/Java。优点是稳,缺点是多智能体编排能力弱。

结果是:用 AutoGen 做出来的原型,迁到生产要换框架重写;用 SK 做生产,又拿不到 AutoGen 的前沿编排。原型到生产之间隔着一条沟。

2025 年 10 月,微软给出的答案是把两者收敛成 Microsoft Agent Framework:取 AutoGen 的 autogen-core actor 运行时和多智能体编排,套上 SK 的企业级外壳(连接器、遥测、状态、middleware),合成一套 SDK,语言收敛到 Python 与 .NET。AutoGen 与独立 SK 同时进入维护模式。2026 年 4 月,MAF 1.0 GA。

·适合谁

这份教程为下面这类读者写——三条都满足,收益最大:

能用 Python 写异步代码:理解 async/await,能调试一个 asyncio 程序。MAF 的运行时是异步的,看不懂 await 会卡在第一段示例。
用过至少一个 LLM API(OpenAI / Azure OpenAI / Claude 任一),知道 function-calling(工具调用)是什么、长什么样。
想搞懂"多智能体框架的运行时与编排到底怎么转",而不是只想抄一两段能跑的 API 调用。

·不适合谁(去更合适的地方)

完全没碰过 LLM API:先过一遍所选 provider 的官方 quickstart,建立 prompt / message / tool-call 的基本概念,再回来。
只想最快做出一个 demo、不关心机制:CrewAI 的 role-based crew 上手更快(几小时出 demo)。本教程的重心是"为什么这么设计",不是"最短路径跑通"。
在找 AutoGen v0.2 的 ConversableAgent / GroupChat 老教程:那套自 2025-10 起进入维护模式。本教程讲的是它的继任者 MAF,概念能迁移,但类名和 import 已经变了(02 章有迁移对照)。
JVM 重度团队想要 Java SDK:SK 曾有 Java,MAF 砍掉了,只剩 Python / .NET。这一条是硬约束。

·读完之后你能做到什么

读完这份教程,一个工作多年的后端工程师能向同事讲清楚一件文档不会直接告诉你的事: 为什么 MAF 把 Agent 设计成无状态、把"编排"拆成"actor 消息运行时"与"Pregel 超步图 Workflow"两套执行模型——以及在什么场景下该用哪一套。 把这句话讲明白,就抓住了这个框架的骨架。具体能力:

画出 MAF 的分层结构(Agent / 两套编排 / actor 运行时 / 可观测),说清每层的职责边界;
面对一个需求,判断该用 AgentChat 模式还是 Workflow 图引擎,并给出依据;
解释 client-managed 与 server-managed 两种 AgentThread 持久化的差异和各自适用场景;
在 MAF / LangGraph / CrewAI / OpenAI Agents SDK 之间做选型,说出至少 3 条决策依据;
看懂一段 AutoGen v0.4 → MAF 的迁移改动,指出 AssistantAgent→ChatAgent 等变化背后的设计意图。

一句话本质

MAF 把"单个 Agent"降格为无状态执行单元,把"多 Agent 编排"升格为一等公民。
编排有两套执行模型叠在一起:底层是 AutoGen 继承来的 actor 消息运行时(开放、分布式、松耦合 pub/sub),上层是 SK 工程化包装出的 Pregel 超步图 Workflow(确定性、可检查点、类型校验)。
看懂"Agent 无状态 + 编排分两套运行时",就看懂了 MAF 的全貌。

现状速览 · 截至 2026-06

稳定:核心 SDK 自 2026-04 的 1.0 GA 起稳定(Python 1.7 / .NET 1.8,两个运行时版本号不同步,.NET 略领先)。单 Agent、连接器、middleware、记忆/上下文、Workflow 图引擎、编排模式、声明式 YAML、MCP 均已 GA。

仍在变:A2A 绑定仍是 preview("即将支持 1.0");DevUI 调试器、Foundry 托管 agent V2、Skills、AG-UI/CopilotKit 适配器等仍在 preview。Build 2026(2026-05)把方向延伸到 OS 层(Windows Agent Runtime、NPU 本地 agent)。

已被取代:AutoGen(v0.2 与 v0.4)与独立 Semantic Kernel 自 2025-10 起进入维护模式——只修 bug/安全、不加新功能、无硬性下线日期,迁移是自愿而非强制。

先承认一件事:读得顺 ≠ 学会了

这份教程在讲一个"两套运行时叠在一起"的框架,概念之间互相纠缠。下面三种自我感觉,基本都是错觉,别被它们骗过:

「我读得很顺」——顺,往往只说明文字写得不绊脚,不代表结构进了脑子。每章末尾的自测才是检验。

「我做题很快」——如果题目都是"X 是什么"的复述题,快只证明你记住了名词。真正的检验是 03 章的判别题:同一个场景,该用 AgentChat 还是 Workflow。

「我没卡壳」——没卡壳,往往是因为你一直在熟悉区打转,没碰到"两套运行时为什么要并存"这种真正硌人的地方。卡壳是好事。

·概念地图

图 0.1MAF 的全貌:红色是两个最该记住的节点。注意:Agent 与 AgentThread 是两个分开的盒子(状态不在 Agent 里);AgentChat 模式和 Workflow 图引擎是并列的两套编排,但它们最终都运行在同一个 actor 运行时上。

·学习路径建议

顶部 breadcrumb 是固定主线:00 起点 → 01 概念 → 02 原理 → 03 自测。按目的可以走不同密度:

只想建立心智模型:index → 01 全 → 02 的前两节(两套运行时机制)→ 03 自测。
做技术选型:index 的现状速览 + 02 的横向对比节 + 03 的判别题。机制细节可后补。
带读 / review 别人的 MAF 代码:01 全(认全部件)+ 02 的 actor 运行时与 Workflow 两节(认两套执行模型)。

·目录

·学完之后

LangGraph——图编排的另一主流实现。MAF 的 Workflow 与它共用 Pregel/超步血统,对照学能看清"图式编排"的通用骨架。(库内已有 ../langgraph/ 教程)
multi-agent 编排模式——handoff / group chat / Magentic 这些模式的跨框架抽象。(库内 ../multi-agent-patterns/)
MCP 规范本身——MAF 只是 MCP 的一个消费方,读规范能搞懂"工具发现"的协议层。
autogen-core——想读懂 MAF 运行时血统,直接看 AutoGen v0.4 的 core 文档与源码。
Azure AI Foundry——MAF 的托管运行与 server-managed Thread 的落地环境(注意它把你绑在 Azure 上)。