Microsoft Agent Framework (MAF) Skill 技能

技能简介

Microsoft Agent Framework（MAF）是微软官方开源的多语言智能体开发框架，专为将 AI 智能体从原型快速推进到生产环境而设计。MAF 提供统一的编程模型，同时支持 Python、.NET（C#）和 Go 三种主流语言，开发者无需切换技术栈即可构建复杂的多智能体协作系统。框架深度集成 Microsoft Foundry、Azure OpenAI、OpenAI 以及 GitHub Copilot SDK，并提供开箱即用的可观测性（OpenTelemetry）、中间件管道、图结构工作流编排和声明式智能体定义能力。2026年7月正式发布 1.0 版本，是当前企业级 AI 智能体开发领域中最具完整生态的框架之一。

核心能力

多语言支持

MAF 对 Python、.NET（C#）和 Go 三大语言提供完整的框架级支持，三种语言的 API 设计保持一致性，开发者可自由选择主力语言，同时保留跨语言协作的可能性。Python 包通过 pip 安装，.NET 包通过 NuGet 分发，Go SDK 托管于独立仓库 microsoft/agent-framework-go。

多 LLM 提供商集成

框架内置对 Azure OpenAI、OpenAI（GPT-4o、GPT-4o-mini 等）、GitHub Copilot SDK 的原生支持，同时支持接入任何兼容 OpenAI Chat Completions API 的第三方模型。Python 示例目录和 .NET 示例目录均提供完整的提供商配置代码，切换模型只需修改客户端初始化参数，无需改动业务逻辑。

图结构工作流编排

MAF 的核心编排引擎基于有向图结构，支持顺序执行（Sequential）、并发执行（Concurrent）、交接传递（Handoff）和群组协作（Group Collaboration）四种经典多智能体模式。配合检查点（Checkpoint）和时间旅行（Time-Travel）能力，工作流可在任意节点中断后精确恢复，适合处理长周期业务流程。

生产级可观测性

框架内置 OpenTelemetry 集成，开箱即用分布式追踪、日志记录和指标监控能力。开发者无需额外配置即可在本地开发或云端部署时获得完整的智能体执行链路可视化，降低了生产环境调试和运维的复杂度。

中间件与自定义管道

灵活的中间件系统允许开发者在请求/响应层面注入统一的处理逻辑，包括认证校验、内容过滤、异常捕获和自定义业务规则。Python 和 .NET 均提供标准化的中间件编写接口，中间件可按需组合成链式管道，实现高度的定制化。

声明式智能体定义

MAF 支持通过 YAML 文件声明式地定义智能体行为，包括名称、指令集、可用工具和技能库引用。这种方式将智能体配置与代码解耦，便于非开发人员维护和版本化管理智能体行为，特别适合需要频繁调整提示词的业务场景。

Foundry 托管智能体

MAF 提供与 Microsoft Foundry 的深度集成，开发者只需额外添加两行代码即可将本地开发的智能体一键部署到 Foundry 托管基础设施上，省去自建推理服务的运维工作。Python 和 .NET 均有对应的示例项目。

Agent Skills 技能系统

MAF 内置的 Agent Skills 机制允许为智能体构建领域知识库，支持从文件、内联代码和类库等多个来源汇聚知识，供智能体在运行时动态发现和调用。这一能力使智能体能够在专业领域（如法律、医疗、金融）提供更精准的问答和推理服务。

安装配置

Python 环境安装

MAF Python 包可通过 pip 一键安装，安装命令为 pip install agent-framework，该命令会同时安装标准包集合。如果需要实验性功能（如基准测试、强化学习等），可单独安装 agent-framework-lab 包。Windows 环境下首次安装可能需要稍作等待。

.NET 环境安装

在 .NET 项目中使用 MAF，只需通过 dotnet add package 命令添加核心包 Microsoft.Agents.AI。如果需要 Foundry 集成能力，还需额外添加 Microsoft.Agents.AI.Foundry、Azure.AI.Projects 和 Azure.Identity 三个依赖包。

Go 环境配置

MAF 的 Go SDK 托管在独立仓库 microsoft/agent-framework-go 中，包含完整的文档、示例代码、贡献指南和问题追踪入口。Go 开发者应访问该独立仓库获取安装和使用说明。

LLM 提供商配置

以 Azure OpenAI 为例，需要在环境变量或代码中配置 FOUNDRY_PROJECT_ENDPOINT（项目终端节点）、FOUNDRY_MODEL（模型部署名称）和 api_version。Python 端可通过 FoundryChatClient 构造函数直接传入，也支持通过环境变量自动读取。

使用步骤

第一步：安装框架包

根据项目语言选择对应的包管理工具完成框架安装。Python 项目执行 pip install agent-framework；.NET 项目执行 dotnet add package Microsoft.Agents.AI，并按需添加 Foundry 相关包。

第二步：初始化智能体客户端

以 Python 为例，首先从 agent_framework 导入 Agent 类，然后选择合适的 ChatClient（支持 FoundryChatClient、AzureOpenAIClient 或任何兼容 OpenAI API 的第三方客户端）。使用 AzureCliCredential() 或其他凭证类型完成身份验证。

第三步：定义智能体指令

通过 Agent 构造函数的 instructions 参数为智能体设定角色和行为描述。例如：instructions="你是一个热情助手，负责撰写关于 Microsoft Agent Framework 的优美文案"。支持在声明式 YAML 中定义，以实现配置与代码分离。

第四步：构建工作流（可选）

对于多智能体协作场景，使用工作流 API 定义各智能体之间的调用关系。MAF 支持顺序、并发、交接等多种编排模式，开发者可参考官方示例（python/samples/03-workflows 或 dotnet/samples/03-workflows）快速上手。

第五步：部署与托管

本地开发完成后，可选择两种部署路径：一是将智能体部署到 Microsoft Foundry 托管基础设施（仅需两行额外配置），二是自建服务进行部署。框架提供完整的 OpenTelemetry 集成，确保生产环境下的可观测性。

适用场景

企业级 AI 智能体平台建设

MAF 的多语言支持、生产级可观测性和 Foundry 托管能力，使其成为企业构建统一的 AI 智能体平台的首选技术栈。大型组织可在 MAF 基础上同时服务 Python、.NET 和 Go 团队，降低跨团队协作成本。

多智能体协作业务流程

需要多个 AI 智能体分工协作的复杂业务流程（如客户服务中同时处理售前咨询、订单查询和售后支持三个智能体的协作场景），可利用 MAF 的图结构工作流编排能力精确管理智能体间的调用顺序和数据传递。

AI 智能体开发框架迁移

已使用 Semantic Kernel 或 AutoGen 的团队，可参考 MAF 官方提供的从 Semantic Kernel 和 AutoGen 的迁移指南，在保留原有投入的基础上平滑过渡到 MAF，获得更完善的多语言和生产级支持。

专业领域知识增强型智能体

借助 MAF 的 Agent Skills 机制，为智能体注入法律条文、医疗指南、金融规则等专业领域知识库，使其能够在特定垂直领域提供合规、精准的 AI 服务，适用于法律咨询、医疗助手、金融分析等场景。

适用人群

MAF 主要面向以下开发者群体：一是需要构建生产级 AI 智能体系统的软件工程师和技术架构师；二是有多语言开发需求的团队（同时使用 Python、.NET 或 Go 的企业）；三是已使用 Semantic Kernel 或 AutoGen、希望迁移到更完整框架的 AI 应用开发者；四是希望将 AI 智能体快速部署到 Microsoft Foundry 生态的企业用户。

工作原理

MAF 的核心架构分为三层：智能体层（Agent）、工作流层（Workflow）和托管层（Hosting）。智能体层负责与 LLM 提供商通信、管理对话历史和调用工具；工作流层基于有向图引擎编排多智能体间的协作逻辑，支持顺序、并发、交接和群组四种模式；托管层提供本地开发和云端部署的统一抽象，通过 OpenTelemetry 实现全链路可观测性。框架通过中间件系统将横切关注点（认证、日志、异常处理）统一注入请求管道，实现业务逻辑与基础设施逻辑的清晰分离。

官方链接

• GitHub 仓库：https://github.com/microsoft/agent-framework
• Python 包（PyPI）：https://pypi.org/project/agent-framework/
• .NET 包（NuGet）：https://www.nuget.org/profiles/MicrosoftAgentFramework/
• 官方文档：https://learn.microsoft.com/en-us/agent-framework/
• 官方博客：https://devblogs.microsoft.com/agent-framework/
• Go SDK 仓库：https://github.com/microsoft/agent-framework-go