Microsoft Agent Framework：微软开源多语言 Agent 框架，Python 与 .NET 一套 API｜部署与使用全指南

仓库：https://github.com/microsoft/agent-framework 语言：Python（PyPI agent-framework）、.NET（NuGet Microsoft.Agents.AI）；Go SDK 在独立仓库 microsoft/agent-framework-go 形态：SDK / 框架（不是独立可运行服务），通过 pip / dotnet 引入到自己的 Agent 工程

1. 项目简介

Microsoft Agent Framework（MAF）是微软开源的、面向生产的多语言 Agent 与多 Agent 工作流框架，在 Python 与 C#/.NET 上提供一致的 API。它面向"把 Agent 从原型推向生产"的团队：提供图编排（sequential / concurrent / handoff / group collaboration）、检查点、流式、人在回路、时间旅行、OpenTelemetry 可观测、声明式 YAML Agent、Agent Skills、Foundry 托管部署等能力。底层支持 Microsoft Foundry、Azure OpenAI、OpenAI、GitHub Copilot SDK 等多家 provider。

1.1 核心信息一览

1.2 适用场景

• 已经在做 Agent / 工作流，需要从原型走向生产，想要检查点、重启、可观测、人在回路。
• 需要图编排：sequential、concurrent、handoff、group collaboration 等多 Agent 模式。
• 团队既有 Python 又有 .NET 代码，想统一一套 Agent API。
• 已经在用 Azure / Foundry，希望加 Foundry Hosted Agents 直接托管。
• 从 Semantic Kernel 或 AutoGen 迁移过来的项目。

1.3 能力边界（官方口径）

• 这是框架 / 库，不是开箱即用的服务，安装后需要自己写代码构造 Agent 并接入到自己的宿主（Web 服务、CLI、任务队列等）。
• 官方 Important Notes 提醒：与第三方服务器、Agent、代码、非 Azure 模型一起使用时，风险由使用方自担；需自行负责数据合规边界、安全过滤与质量验证。
• Go SDK 与文档在独立仓库 microsoft/agent-framework-go。

2. 功能特性

• Python 与 C#/.NET 双语言：一致的 Agent API 抽象，跨语言团队共用。
• 多 Provider 支持：Microsoft Foundry、Azure OpenAI、OpenAI、GitHub Copilot SDK 等。
• 中间件系统：灵活的请求 / 响应处理、异常处理、自定义管线。
• 图编排与工作流：sequential、concurrent、handoff、group collaboration；带 checkpoint、流式、人在回路、time-travel。
• Foundry Hosted Agents：多加两行代码即可把 Agent 部署到 Foundry 托管基础设施。
• 可观测性：内置 OpenTelemetry 集成，分布式追踪、监控、调试。
• 声明式 Agent：用 YAML 定义 Agent，便于版本管理与快速搭建。
• Agent Skills：从文件、内联代码、类库构建领域知识库，供 Agent 发现与使用。
• AF Labs：实验性包，覆盖 benchmarking、强化学习、研究方向。
• DevUI：交互式开发者 UI，用于 Agent 开发、测试与调试工作流。

3. 官方界面预览

框架本身无独立 Web 界面；官方 README 提供 30 分钟介绍视频（YouTube）与 DevUI 演示视频。

4. 官方跳转链接汇总

• 仓库：https://github.com/microsoft/agent-framework
• Go SDK：https://github.com/microsoft/agent-framework-go
• 官方文档（MS Learn）：https://learn.microsoft.com/en-us/agent-framework/
• 快速入门：https://learn.microsoft.com/agent-framework/tutorials/quick-start
• 博客：https://devblogs.microsoft.com/agent-framework/
• PyPI：https://pypi.org/project/agent-framework/
• NuGet：https://www.nuget.org/profiles/MicrosoftAgentFramework/
• Discord：https://discord.gg/b5zjErwbQM
• 迁移指南（Semantic Kernel）：from-semantic-kernel
• 迁移指南（AutoGen）：from-autogen

5. 前置要求与服务器配置

5.1 软件前提（Python）

• Python 3.9+（按 PyPI 包要求）。
• 一个可用的模型后端：Microsoft Foundry / Azure OpenAI / OpenAI / GitHub Copilot SDK。
• 若走 Azure 凭证，需要安装并登录 Azure CLI。

5.2 软件前提（.NET）

• .NET 8 SDK 或更新版本。
• 同上，需要一个模型后端与 Azure 凭证（如走 Foundry）。

5.3 硬件与系统建议

• 框架本身不跑大模型，普通开发机即可；生产部署按所选模型与宿主（Foundry / Azure Functions / 自建 Web）的要求准备。

5.4 端口分配

6. 方式一：pip / NuGet 安装（推荐路径）

6.1 Python 安装

pip install agent-framework
# 实验模块单独装
# pip install agent-framework-lab

官方提示：Windows 上首次安装可能需要一分钟。

6.2 写一个最小 Agent（Python）

# 先用 az login 完成 Azure 认证
import os, asyncio
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

async def main():
    agent = Agent(
        client=FoundryChatClient(
            credential=AzureCliCredential(),
            # project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            # model=os.environ["FOUNDRY_MODEL"],
        ),
        name="HaikuAgent",
        instructions="You are an upbeat assistant that writes beautifully.",
    )
    print(await agent.run("Write a haiku about Microsoft Agent Framework."))

if __name__ == "__main__":
    asyncio.run(main())

6.3 .NET 安装

dotnet add package Microsoft.Agents.AI
# Foundry 集成相关
dotnet add package Microsoft.Agents.AI.Foundry
dotnet add package Azure.AI.Projects
dotnet add package Azure.Identity

6.4 写一个最小 Agent（C#）

using Azure.AI.Projects;
using Azure.Identity;
using Microsoft.Agents.AI;

string endpoint = Environment.GetEnvironmentVariable("FOUNDRY_PROJECT_ENDPOINT")
    ?? throw new InvalidOperationException("FOUNDRY_PROJECT_ENDPOINT is not set.");
string deploymentName = Environment.GetEnvironmentVariable("FOUNDRY_MODEL") ?? "gpt-5.4-mini";

AIAgent agent =
    new AIProjectClient(new Uri(endpoint), new DefaultAzureCredential())
        .AsAIAgent(model: deploymentName,
                   instructions: "You are an upbeat assistant that writes beautifully.",
                   name: "HaikuAgent");

Console.WriteLine(await agent.RunAsync("Write a haiku about Microsoft Agent Framework."));

7. 方式二：源码 / 本地开发运行

git clone https://github.com/microsoft/agent-framework.git
cd agent-framework

仓库结构：

• python/packages/：Python 包源码
• python/samples/：Python 示例（01-get-started / 02-agents / 03-workflows / 04-hosting / 05-end-to-end）
• dotnet/src/：.NET 源码
• dotnet/samples/：.NET 示例
• declarative-agents/：YAML 声明式 Agent 示例
• docs/：设计文档与 ADR

Python 开发环境参考 python/DEV_SETUP.md。

8. 配置项说明

官方建议：DefaultAzureCredential 适合开发，生产环境应使用具体凭证（如 ManagedIdentityCredential），避免回退探测带来的延迟与安全风险。

9. 常用运维命令

# Python
pip install -U agent-framework
python your_agent_app.py

# .NET
dotnet add package Microsoft.Agents.AI
dotnet build
dotnet run

# 安装 Agent Framework builder skill 给 Claude / Cursor 等编码 Agent
gh skill install microsoft/agent-framework agent-framework-builder-python@main

# 或用跨 agent skills CLI
npx skills add microsoft/agent-framework --skill agent-framework-builder-python

# 升级依赖 / 查看示例
git pull
cd python/samples && ls

10. 常见故障排查

• Azure 凭证报错：先执行 az login；生产环境改用 ManagedIdentityCredential。
• API Key 报错：检查密钥是否正确、是否对应该资源 / provider；不要把开发 Key 带进生产。
• 找不到 agent_framework 模块：确认 pip install agent-framework 成功；Windows 上首次安装较慢，看是否真的完成。
• .NET 还原失败：确认 NuGet 源可访问；dotnet restore 重试。
• 多 Agent 工作流不持久化：检查是否接入了 Durable Task 扩展（Durable Agent Framework extension）。
• OpenTelemetry 没数据：确认环境变量与 exporter 配置；参考 python/samples/02-agents/observability/。
• 第三方系统数据出边界：官方明确提醒，与非 Azure 模型 / 第三方服务器集成时，数据合规与安全由使用方负责。

11. 风险与合规说明

• 许可证：以仓库根目录 LICENSE 为准（微软开源项目通常为 MIT 类宽松许可）；商用前请核对最新版本。
• 框架定位：MAF 是开发框架，不是托管服务；部署形态、鉴权、限流、监控、合规由你自己负责。
• 第三方系统风险：官方 Important Notes 明确：使用第三方服务器、Agent、代码、非 Azure 模型时，"风险由使用方自担"，需自行审查数据流向、留存、地域边界与合规。
• 负责任 AI：官方要求使用方自行实现 metaprompt、内容过滤、安全系统，确保应用质量、可靠性、安全与可信；参见 TRANSPARENCY_FAQ.md。
• 云成本：Foundry / Azure OpenAI / OpenAI 等模型调用均按对应平台计费；生产前先压测与设置用量告警。
• 版本演进：框架仍在快速迭代，从 Semantic Kernel / AutoGen 迁移时请按官方迁移指南逐步进行。