Microsoft Agent Framework 快速入门

这是什么？适合谁？

Microsoft Agent Framework（MAF，microsoft/agent-framework，13k Stars，MIT，2025-04 首次发布）是微软开源的多语言 Agent 框架：用 .NET 和 Python 构建”生产级”AI Agent 与多 Agent 工作流。它的定位是把 Agent 从原型带到生产：提供跨 Python 与 C#/.NET 的一致 API 基础，编排模式（顺序/并发/交接/群聊协作）、持久化与可重启（checkpointing）、流式、人机回路（human-in-the-loop）、可观测性与治理——架构选型保持开放，需求演进不用重写。

生态位（README 明示）：与 Microsoft Foundry、Azure OpenAI、OpenAI、GitHub Copilot SDK 集成；多 LLM 提供商支持持续扩充；本地开发与云端部署双模式。这是微软在 AutoGen（本站已收录）与 Semantic Kernel 之后的战略收敛：MAF 融合两者的理念，官方路线是微软 Agent 技术栈的下一代统一框架。

适合人群：

• .NET/C# 团队：市面上 Agent 框架多数 Python 优先，MAF 是少数 Python 与 .NET API 一致的框架
• 企业开发团队：需要持久化、可重启、可观测、治理、人机回路这些”生产词”而非 demo 能力
• 已在微软生态（Azure/Foundry/Copilot SDK）的团队：集成路径顺滑
• 需要多 Agent 编排（工作流图）的场景：sequential/concurrent/handoff/group chat 四种模式开箱即用

不适合：纯前端/JS 技术栈（官方无 JS 支持）；想五分钟跑通 demo 的体验党（生产级框架的完备性意味着更多概念）；非微软生态且有强偏好的团队（LangGraph/CrewAI 等生态同样成熟）。

使用前提：Python 3.10+ 或 .NET 8+；至少一家 LLM 提供商（Azure OpenAI/OpenAI/Anthropic 等）的访问。

准备工作

• 环境：Python 3.10+（pip install agent-framework）或 .NET 8+（NuGet：Microsoft.Agents.AI）
• 账号：需要 LLM 提供商访问（Azure OpenAI 部署 / OpenAI Key / 其他支持的提供商）
• 时间预算：Hello World 半小时；工作流+持久化+人机回路的完整模式一天起步
• 成本：MIT 开源免费；LLM 调用按提供商计费；Azure 部署另计
• 学习材料：MS Learn 官方文档 + 官方博客（devblogs.microsoft.com/agent-framework）+ 仓库 Python/.NET 双语示例

快速上手（3 步）

第一步：安装

# Python
pip install agent-framework

# .NET
dotnet add package Microsoft.Agents.AI

第二步：创建第一个 Agent（Python 示例）

from agent_framework import ChatAgent

agent = ChatAgent(
    instructions="你是一个严谨的助手",
    # 模型接入按官方 providers 文档配置（Azure OpenAI / OpenAI / 其他）
)
result = await agent.run("用一句话解释 checkpointing")
print(result)

第三步：跑一个多 Agent 工作流

从仓库示例（python/samples/03-workflows/ 或 dotnet/samples/03-workflows/）挑一个 graph 工作流示例跑通：两个 Agent 交接（handoff）完成任务，观察编排器如何路由消息。把示例里的任务描述换成你自己的场景。

成功判定：工作流示例端到端跑通（消息在 Agent 间按图流转）；启用 checkpointing 的示例重启后能从断点继续。

初级用法

• 单 Agent 会话：ChatAgent + 指令 + 工具，快速验证模型接入
• 中间件链：请求/响应处理、异常处理、自定义管道（middleware 体系）
• 多提供商切换：改配置换 LLM 提供商，业务代码不动
• 流式输出：长回复场景开 streaming 改善体验

高级玩法

1. 图编排四模式组合：sequential（流水线）、concurrent（并行扇出）、handoff（专家交接）、group chat（群聊协作）按业务组合成多 Agent 图——这是 MAF 的核心抽象
2. 持久化与 time-travel：checkpointing 让长任务可重启；time-travel 调试回放历史执行状态定位问题
3. 人机回路闸门：关键决策点插入人工审批（human-in-the-loop），审批通过才继续——生产级 Agent 的合规刚需
4. Foundry 托管 Agent：用 Foundry Hosted Agents 把本地开发的 Agent 无缝上云托管（Azure 侧运维）
5. 可观测性三件套：OpenTelemetry 集成 + 治理钩子（guardrails）+ 中间件埋点，把 Agent 运行纳入企业监控体系

常见踩坑（5 条）

踩坑 1：Python 与 .NET 文档混淆

• 现象：照着 Python 示例写 C# 报 API 不存在
• 原因：双语言 API”一致”是理念层面，命名空间与细节有差异
• 解决：严格走对应语言的 samples 目录（python/samples 与 dotnet/samples 分开维护）

踩坑 2：checkpointing 没配存储

• 现象：宣称可重启但重启后状态丢失
• 原因：默认 checkpoint 存内存，进程退出即失
• 解决：按文档配置持久化存储（如 Azure 存储/数据库 provider）

踩坑 3：编排图设计成大泥球

• 现象：所有 Agent 互相 handoff，行为不可预期
• 原因：群聊模式被滥用；职责边界没想清
• 解决：从 sequential 起步；只在真正需要动态路由处用 handoff/group chat；每步有明确输入输出契约

踩坑 4：把 AutoGen 教程拿来用

• 现象：AutoGen 的 API/模式在 MAF 里找不到
• 原因：MAF 是新框架（融合 AutoGen 与 SK 理念但 API 全新）
• 解决：只看 MAF 自己的文档与 samples；AutoGen 迁移参考官方迁移指南

踩坑 5：本地跑通上云报权限

• 现象：本地 OpenAI Key 正常，部署 Azure 后调用失败
• 原因：云端走托管标识（managed identity）而非 Key 认证
• 解决：按 Azure 部署文档配置标识与角色；本地开发保留 Key 路径

小技巧（5 条）

1. 先读 “Is this the right framework for you?” 一节：README 开头的自检清单帮你 3 分钟判断匹配度
2. Python/.NET 双语示例对照学：同一功能两种实现并读，加深对框架抽象的理解
3. 中间件优先：横切需求（日志/审计/限流）全走 middleware，别散落在 Agent 指令里
4. 每周看官方博客：devblogs.microsoft.com/agent-framework 持续放出新模式与实战
5. Discord 讨论：Microsoft Foundry Discord 有专区，微软工程师活跃

常见问题 FAQ

Q1：MAF 免费吗？

A：MIT 开源免费（13k Stars，2026-08-21 采集）。费用是 LLM 调用（按提供商）与可选的 Azure 托管资源。

Q2：它和 AutoGen、Semantic Kernel 什么关系？

A：MAF 吸收两者理念（AutoGen 的多 Agent 协作 + SK 的生产化设计），是微软 Agent 技术栈走向统一的新一代框架（2025-04 发布）。新项目官方推荐 MAF；存量 AutoGen/SK 项目按官方迁移指南过渡。

Q3：Python 和 .NET 功能完全对等吗？

A：设计目标是一致的核心 API（编排/持久化/中间件/人机回路），双语言各自维护完整 samples；边缘特性上线节奏可能有先后，以对应语言的文档为准。

Q4：能接非 OpenAI 系模型吗？

A：能。多提供商支持（含 Anthropic 等）持续扩充，见仓库 providers 示例目录。

Q5：不上 Azure 能用吗？

A：能。本地开发与自托管部署完全开源可用；Azure/Foundry 是可选的托管加速器而非依赖。

进阶学习建议

• 通读 03-workflows 示例目录的四种编排模式（sequential/concurrent/handoff/group chat），理解”图编排”与”自由群聊”的适用边界——这是多 Agent 系统设计的核心判断力
• 跑通 checkpointing + time-travel 调试回放，这是生产级 Agent（长任务、可审计）与 demo Agent 的分水岭能力
• 对照 LangGraph（图编排先驱）与 CrewAI（角色协作）与本框架，建立自己的选型矩阵：语言栈/生态/治理能力三维度
• 把一个真实审批流改造成 human-in-the-loop 模式（Agent 提案 -> 人工审批 -> 继续），体验”治理”如何落地为代码
• 跟进 MS Learn 文档与官方博客的更新节奏，MAF 处于快速演进期（2025-04 至今），API 变化要看 release notes

参考链接

• Microsoft Agent Framework GitHub 仓库
• MS Learn 官方文档
• 官方博客
• 官方 Discord（Microsoft Foundry）

本文基于公开资料于 2026-08-21 整理，社区指标来自 GitHub API 公开数据。独立实测未进行，API 细节以官方文档为准（框架处于快速演进期）。