
用 AutoGen 搭多 Agent,demo 阶段很顺手:几个 AssistantAgent 放进 RoundRobinGroupChat,它们自己讨论出结果。真要上线就开始头疼:进程跑到一半挂了,前面十几轮全白跑;Agent 要调一个发邮件的工具,想先看一眼再放行,没有现成的入口;哪个 Agent 在哪一步花了多少 token,只能自己往日志里加打印。
现在 AutoGen 的 README 已经写明项目正在转为归档状态,不建议用于生产,新用户请直接用 Microsoft Agent Framework(简称 MAF),老用户按官方指南迁移。MAF 是微软把 AutoGen 和 Semantic Kernel 两条线合并后的接班框架,保留了 AutoGen 的多 Agent 编排思路,也带上了 Semantic Kernel 的状态管理和遥测能力。它已发布 1.0 正式版,承诺 API 稳定和长期支持,支持 Python 和 .NET,采用 MIT 协议。
这篇按上手顺序讲:怎么装、怎么写第一个 Agent、多 Agent 编排怎么写、检查点和工具审批这些生产能力怎么用,最后是 AutoGen 迁移和本地调试。

第 1 步:安装 Microsoft Agent Framework
Python 版本需要 3.11 及以上(以 PyPI 上 agent-framework 的当前要求为准),装一个包即可:
pip install agent-framework
export OPENAI_API_KEY=sk-...
.NET 项目用 NuGet 安装对应的包(例如接 Foundry 时用 Microsoft.Agents.AI.Foundry),官方 README 里有 .NET 版的快速开始。
第 2 步:写一个带工具的 Agent
一个带工具的 Agent 十几行就够:
import asyncio
from agent_framework import Agent, tool
from agent_framework.openai import OpenAIChatClient
@tool(approval_mode="never_require")
def get_weather(city: str) -> str:
"""查询城市天气"""
return f"{city}:晴,26°C"
async def main():
agent = Agent(
client=OpenAIChatClient(model="gpt-4.1-mini"),
name="WeatherAgent",
instructions="你是一个简洁的助手",
tools=[get_weather],
)
print(await agent.run("上海今天适合跑步吗?"))
asyncio.run(main())
模型这一层可以替换。仓库里有 OpenAI、Anthropic、Gemini、Ollama、Bedrock、Mistral、GitHub Copilot、Microsoft Foundry 等对应的 client 包,换模型主要改 client 那一行,Agent 和工作流代码不用动。官方 README 的快速开始默认用的是 FoundryChatClient,本地试用时换成上面的 OpenAIChatClient 也可以。
第 3 步:用工作流编排多个 Agent
AutoGen 的核心是让 Agent 互相聊天,MAF 把这件事改成了画图:节点是 Agent 或普通函数,边决定消息往哪走。常见的几种协作方式都有现成的 Builder:
| 模式 | 适合的场景 |
|---|---|
| Sequential | 研究员查资料、写手写稿、编辑把关,一个传一个 |
| Concurrent | 同一个问题同时交给几个 Agent,最后汇总 |
| Handoff | 前台客服先接,判断是退款还是查物流,再转给对应专员 |
| Group Chat / Magentic | 几个 Agent 一起讨论,由主持人决定下一个谁发言;Magentic 延续了 AutoGen 的 Magentic-One |
顺序编排写起来是这样:
from agent_framework.orchestrations import SequentialBuilder
workflow = SequentialBuilder(participants=[researcher, writer, editor]).build()
result = await workflow.run("写一段电动车的产品简介")
需要更细的控制,比如编辑不满意就打回给写手重写,可以用 WorkflowBuilder 自己连边,边上能挂条件,也能连成环。

第 4 步:打开检查点、工具审批和可观测性
前面这些 AutoGen 也能做,MAF 真正补上的是上线才会遇到的几个问题。
跑一半挂了能接着跑。 工作流支持 checkpoint,每一步执行完自动存档。进程崩了,拿着 checkpoint_id 重新运行,从断点继续(最后一行就是崩溃后从最近的存档点恢复):
workflow = WorkflowBuilder(
start_executor=start,
checkpoint_storage=InMemoryCheckpointStorage(),
).add_edge(start, worker).build()
workflow.run(checkpoint_id=latest.checkpoint_id, stream=True)
测试时用内存存档,正式环境可以换成 Cosmos DB 这类持久化存储。
危险操作先问人。 定义工具时把 approval_mode 设成 always_require,Agent 想调用它时,工作流会先停下来抛出审批请求,批准后才真正执行。删数据、发邮件这类工具建议都这样配置。
每一步都看得见。 MAF 内置 OpenTelemetry,哪个 Agent 调了哪个工具、花了多久,可以直接进 Jaeger、Grafana 这类已有的监控系统。
此外还有中间件,可以在请求前后插入自己的逻辑做内容过滤、日志脱敏;Agent 能用 YAML 声明,方便版本管理;对外支持 MCP 和 A2A 协议,接工具、和其他框架的 Agent 互通都有路径。

第 5 步:从 AutoGen 迁移
老 AutoGen 用户最关心迁移成本。仓库的 python/samples/autogen-migration 目录按单 Agent 和多 Agent 编排分好了对照示例,覆盖 RoundRobinGroupChat、SelectorGroupChat、Swarm、Magentic-One 这些常用团队写法,先看 AutoGen 写法,再对照 MAF 写法改。官方文档里也有完整的《从 AutoGen 迁移》指南。
比较稳妥的做法是:先找到和你团队结构对应的那份对照代码,改一个最小流程跑通,再逐步搬其余部分。AutoGen 不再加新功能,拖得越久,和新模型、新协议的差距越大。
第 6 步:用 DevUI 在本地调试
写工作流最难受的是看不见中间过程。MAF 带了一个 DevUI,安装后一行代码起一个本地网页:
pip install agent-framework-devui --pre
from agent_framework.devui import serve
serve(entities=[agent], auto_open=True)
运行后浏览器会打开 http://localhost:8080。选好 Agent 或工作流就能直接对话,每次工具调用、每一步消息怎么流转,界面上都看得到。如果 Agent 都放在一个目录里,命令行 devui ./agents --port 8080 能自动扫描出来。DevUI 目前仍是预发布版本,定位是开发调试用的样例应用,正式上线还是要自己写接口和前端。

和其他多 Agent 框架怎么选
- 和 LangGraph 比,MAF 多了一条 .NET 线,团队用 C# 或者已经在 Azure 上的,接起来更顺手。
- 和 CrewAI 比,MAF 更底层,图怎么连、哪一步存档、哪一步停下等人审批,都由你自己决定。
- 手上有 AutoGen 老项目的,可以开始排迁移计划。
总结
Microsoft Agent Framework 把 AutoGen 的多 Agent 编排和 Semantic Kernel 的工程能力合到一起,重点补上了检查点恢复、工具审批和 OpenTelemetry 可观测性这些上线必需的能力。新项目可以直接从它开始,老 AutoGen 项目按官方对照示例逐步迁移。
如果你同时在用 Claude Code、Codex 这类编程 Agent,想了解一个 Key 怎么接入多种模型,可以看 AIGoCode 是什么;不同协议该怎么选,可以参考 直接 API 请求还是接入 Claude Code / Codex CLI。