agent-framework

microsoft/agent-framework 是微软开源的多语言、多智能体开发框架，用于构建生产级 AI Agent 和多智能体工作流，同时支持 Python 和 C#/.NET 双运行时。

图1：Microsoft Agent Framework 架构概览（来源：GitHub 仓库 docs/assets）

背景：为什么需要 Agent 编排框架？

传统的 AI 调用模式通常是一次问答（Single-turn）或简单的对话循环（Chat Loop）。当任务变得复杂——比如「先查天气，再根据天气推荐出行，最后调用 API 订机票」——单一调用链就力不从心了。

更棘手的是：多步骤执行中一旦出错，如何回滚？多个 Agent 之间如何交接上下文？人类的决策节点如何嵌入自动流程？这些是让 AI 从「玩具演示」走向「生产系统」的核心工程难题。

微软 Agent Framework 正是为解决这些工程挑战而生。它的目标不是替代 LangChain 或 AutoGen，而是提供一套更接近生产级标准的编排基础设施，填补企业级 Agent 开发的工具链空白。

核心功能：四层能力拆解

1. Agent 层：构建单个智能体

MAF 的 Agent 是状态机加上消息处理器的组合。每个 Agent 具备以下核心能力：

• Memory/State：维护对话历史和中间状态，支持 checkpointing（检查点保存）和 time-travel（时间回溯）——这对长流程调试至关重要
• Skills：可挂载领域知识库，支持从文件、代码、类库等多种来源构建，Agent 可以动态发现和使用这些技能
• Middleware：拦截请求/响应的中间件管道，用于日志、认证、限流等横切关注点，与 ASP.NET Core Middleware 设计一脉相承
• Provider 抽象：统一接口对接多种 LLM 后端，包括 Azure OpenAI、OpenAI、Claude、Gemini、Bedrock、GitHub Copilot SDK 等，换 Provider 几乎不需要改业务代码

2. 编排层：多 Agent 协作模式

MAF 的工作流引擎基于有向图设计，支持四种核心编排模式：

• Sequential（顺序）：链式调用，A 执行完结果传给 B，B 再传给 C，适合线性任务分解
• Concurrent（并发）：并行分发任务，并发执行后汇总结果，适合独立子任务的并行处理
• Handoff（交接）：Agent 之间平滑交接上下文和状态，适合复杂任务的分工协作
• Group Collaboration（群协作）：多个 Agent 协作解决同一任务，适合需要多视角分析的复杂问题

每种模式都内置 checkpointing 和 streaming 支持，并天然支持 Human-in-the-Loop（人在回路）干预——你可以在任意节点暂停，等待人工确认后再继续。

3. 可观测性层：OpenTelemetry 原生集成

MAF 内置分布式追踪能力，对接 OpenTelemetry 标准生态，可无缝接入 Azure Monitor、Jaeger、Prometheus 等监控系统。这在多 Agent 协作调试时价值巨大——你可以清晰看到一次请求在各 Agent 之间的完整流转路径、各节点耗时和状态变化，类似于微服务架构中的分布式追踪体验。

4. 部署层：灵活托管选项

MAF 不绑定任何特定部署方式，提供多种选择：

• 本地开发：通过 .devcontainer 一键进入配置好的容器环境，内置 uv 包管理器、Azure CLI、Docker-in-Docker，开箱即用
• Foundry Hosted：仅需两行额外代码，即可将 Agent 部署到 Azure Foundry 托管基础设施，享受免运维体验
• Foundry Local：本地运行 Foundry 模拟环境，适合离线开发和测试
• 自托管：标准的 Python 包安装加 FastAPI/Uvicorn 自行部署，完全掌控基础设施

技术架构：Python 与 .NET 双生态并行

MAF 最显著的特点是双语言支持：同一个框架，同时维护 Python 和 C#/.NET 两套实现，且 API 设计保持语义一致。

Python 侧采用 uv workspace 管理的 monorepo 结构，包含多个子包：

• packages/core：核心接口和抽象定义
• packages/a2a：Agent-to-Agent 通信协议实现
• packages/ag-ui：Agent UI 协议
• packages/declarative：YAML 声明式 Agent 定义
• packages/devui：本地交互式开发调试 UI
• packages/foundry*：Azure Foundry 集成全家桶
• 各 packages/{provider}：LLM provider 对接（azure-ai-search、bedrock、gemini、claude 等）

.NET 侧采用标准 .NET 项目结构，NuGet 包分发，与 Azure Identity、Azure AI Projects 等微软生态深度集成。代码质量方面，项目使用 mypy/pyright 做类型检查，pytest 做测试（支持 xdist 并行和超时控制），pre-commit 钩子做代码风格检查，生产级质量标准。

上手体验：快不快？难不难？

Python 侧：pip install agent-framework 即可安装全部子包，或按需 pip install agent-framework-core、pip install agent-framework-claude 等单独安装单个 provider 包。官方 QuickStart 从零开始，MS Learn 有体系化学习路径。

无 Web UI：MAF 是 SDK 级别的框架，没有开箱即用的 Web 界面。DevUI 包提供本地命令行调试工具，支持逐步调试 Agent 执行流程和查看中间状态，但相比 Streamlit/Gradio 类方案，交互体验偏技术向。

文档质量：这是微软的强项——README 详尽，有 Architecture 文档、Architecture Decision Records（ADR）、Contributing 指南、Coding Standard，MS Learn 上还有完整的教程体系，文档质量远超大多数开源项目。

局限与挑战

• 不是 LangChain 替代品：MAF 更偏向生产基础设施，如果你需要快速实验性原型，LangChain/LlamaIndex 可能更灵活，学习曲线也更低
• 学习曲线存在：虽然安装简单，但多 Agent 编排的状态机思维模型需要一定时间适应
• Azure 生态绑定：Foundry 相关功能与 Azure 平台绑定较紧，纯开源部署时部分高级功能不可用
• DevUI 能力有限：本地调试 UI 功能基础，大规模多 Agent 调试仍需配合 OpenTelemetry 链路追踪
• 依赖较新 Python 版本：要求 Python 3.10 以上，部分企业存量环境需要升级

行业意义

微软将 Agent Framework 开源，反映了企业级 AI 开发的重要趋势：从单点调用走向结构化编排。随着 Azure Foundry、GitHub Copilot 等产品的普及，越来越多的企业需要一套能横跨 Python 和 .NET 生态的 Agent 开发标准。MAF 填补了这一空白，同时通过支持 A2A（Agent-to-Agent）和 AG-UI 等开放协议，推动 Agent 互操作性的行业标准化。

项目由微软 Azure AI 团队维护，遵循 MIT 许可证，贡献者中包含多位来自 Semantic Kernel 和 AutoGen 项目的工程师，技术积累深厚。