Microsoft Agent Framework (MAF)

一、框架定位与演进背景

Microsoft Agent Framework（MAF）是微软推出的面向 .NET 和 Python 的开源智能体开发框架，定位为构建 AI 代理（Agent）和多代理工作流（Multi-Agent Workflow）的统一底座。2026 年 4 月，MAF 1.0 正式发布，标志着 API 稳定并承诺长期支持（Long-Term Support）。

二、核心架构

2.1 技术分层

MAF 建立在 Microsoft.Extensions.AI（MEAI）的抽象层之上。MEAI 定义了基础抽象（主要是 IChatClient），允许开发者在不修改应用代码的前提下切换 LLM 提供商。MAF 在 IChatClient 之上提供 Agent 级别的原语，包括持久化对话上下文、工具/函数调用、系统提示词管理和流式 API。关系可类比为：IChatClient 之于 MAF，如同 HttpClient 之于 REST 客户端库。

2.2 两大核心构建块

Agents（代理） ：利用 LLM 进行推理的独立实体，可集成上下文（来自知识库或历史记录），并通过调用工具（函数、API、MCP 服务器）执行操作。可针对特定任务（如分析、合成）进行专门化。

Workflows（工作流） ：将复杂目标结构化为步骤序列或图结构，协调代理、工具或子工作流的执行。工作流提供显式控制，支持非线性进展、子任务拆分和人机协同交互。

2.3 核心抽象（四大核心接口）

IAIAgent：MAF 的核心接口，代表一个 AI 代理——能够接收提示词并产生响应，可选择使用工具并维护对话状态。定义了两个关键方法：RunAsync（运行代理并返回响应）和 RunStreamingAsync（流式执行）。

AgentSession：框架管理的对话状态容器，由 MAF 自动管理，提供持久化会话和上下文恢复能力。

AIContextProvider：为代理记忆和上下文提供注入点的服务提供者，可用于将外部数据（如 RAG 检索结果）注入代理的上下文窗口。

Middleware：拦截代理行为的中间件管道，支持在代理执行前后插入自定义逻辑（如日志、审计、安全校验）。

2.4 Workflow 核心概念体系

MAF Workflow 提供了一套基于图结构的工作流编排框架，核心概念如下：

概念	说明	类比
Workflow	工作流定义	流程图
Executor	执行器/处理节点，最小工作单元	工人
Edge	连接边，定义执行流向	传送带
SuperStep	超步/批量处理	处理周期
WorkflowContext	工作流上下文，共享状态容器	工作台
WorkflowEvent	工作流事件	通知
Run	运行实例	一次执行
Checkpoint	检查点，支持断点续跑和状态恢复	存档点

Executor 类型层次：

• Executor<TInput>：处理消息，无返回值（日志记录、通知发送）
• Executor<TInput, TOutput>：处理消息，有返回值（数据转换、AI 调用）
• FunctionExecutor<T>：委托函数快速创建简单处理逻辑
• StatefulExecutor<TState>：需要维护状态的执行器（会话管理、计数器）

三、核心功能模块

3.1 模型接入与多提供商支持

MAF 1.0 内置一级连接器，支持以下模型提供商：Microsoft Foundry、Azure OpenAI、OpenAI、Anthropic Claude、Amazon Bedrock、Google Gemini 以及 Ollama。通过 IChatClient 抽象层，开发者可以无缝切换模型提供商而无需修改业务代码。

3.2 工具调用（Function Tools）

MAF 通过 AIFunctionFactory.Create() 提供极简的工具注册方式——将任何 C# 方法（Lambda、静态方法、实例方法）转换为 AIFunction，无需属性标注或插件基类继承。AIFunctionFactory 自动对委托的参数类型进行自省，生成 JSON Schema 供 LLM 理解函数签名。

3.3 多代理编排模式

MAF 1.0 支持以下编排模式：

• Sequential（顺序）：代理按预定顺序依次执行
• Concurrent（并发）：多个代理并行执行，支持 Fan-Out / Fan-In 模式
• Handoff（交接）：代理将任务委托给更专业的代理
• Group Chat（群聊）：继承自 AutoGen 的群聊式协作模式
• Magentic-One：动态任务协调模式，源自 AutoGen 研究

在 SubAgent 架构中，可用 Executor + Workflow（DAG）模式实现并发 Fan‑Out/Fan‑In、消息路由与聚合策略。

3.4 声明式 Agent

MAF 支持通过 YAML 文件声明式定义 Agent，将系统提示词、模型参数、输出格式 Schema 等配置与代码分离。声明式定义可纳入版本控制，遵循 DevOps 最佳实践，提升协作效率和部署一致性。

3.5 Agent Skills（能力封装）

Agent Skills 是 MAF 1.0 补齐的关键能力，将“领域知识、操作说明、脚本资源、模板资产”从 Agent 本体剥离，封装为可移植、可复用、可审计、可按需加载的模块。典型结构包含：SKILL.md（核心指令）、可选的 scripts/、references/ 和 assets/。

Skills 的核心机制是 Progressive Disclosure（渐进式披露）：Advertise → Load → Read resources → Run scripts，逐层加载所需内容，有效优化上下文窗口管理和 Token 成本控制。

3.6 Agent 嵌套调用（Agent as Function）

MAF 提供两种方式将 Agent 转换为可复用工具：

• AsAIFunction()：应用内嵌套调用，进程内执行，性能高，适合层次化 Agent 架构
• MCP Tool：通过 Model Context Protocol 暴露为跨平台工具，支持任何 MCP 客户端调用

3.7 会话与记忆管理

MAF 通过 AgentSession 提供框架托管的对话状态管理，支持会话持久化、多轮对话上下文维护以及会话恢复。AIContextProvider 允许注入外部上下文（如向量检索结果），实现 RAG 增强。

3.8 可观测性

MAF 集成 OpenTelemetry，支持将追踪数据发送至 Azure AI Foundry 等可观测性平台，用于调试、评估和改进多代理系统在生产环境中的行为。

四、互操作与扩展

4.1 跨运行时互操作

MAF 1.0 通过以下标准协议实现跨运行时互操作：

• A2A（Agent-to-Agent）：代理间通信协议，支持跨语言、跨服务协同
• MCP（Model Context Protocol）：模型上下文协议，标准化上下文与工具生态接入
• AG-UI：Agent 用户界面协议

4.2 A2A Hosting

MAF 支持通过 ASP.NET Core 进行 A2A Hosting，实现服务内外协同、多实例、多租户模式部署。

五、开发实践与典型场景

5.1 典型开发流程

1. 创建 ChatClient：配置模型端点与 API 密钥
2. 创建 Agent：通过 AsAIAgent() 扩展方法包装 ChatClient，设置 Name、Instructions、Tools 等选项
3. 注册工具：使用 AIFunctionFactory.Create() 或 MCP 工具
4. 定义 Workflow：通过 WorkflowBuilder 构建 DAG
5. 执行与观测：调用 RunAsync() 或流式执行，通过 OpenTelemetry 观测

5.2 适用场景与不适用场景

适用场景：

• 客户支持系统
• 教育与辅导
• 代码生成
• 研究辅助
• 非结构化环境中的动态问题解决

不适用场景：

• 高度结构化、规则固定的任务
• 预期有明确定义输入类型和作业顺序的场景

5.3 典型应用案例

智能客服系统：通过多代理协作处理客户咨询，协调 Agent（路由请求）与专业 Agent（订单查询、物流跟踪）分工协作。

SubAgent 模式：将复杂任务拆解为职责单一的模块，用 Workflow/DAG 串联节点，支持并行处理和流水线扩展。

多代理研究系统：研究者代理 + 评审者代理 + 写作者代理通过修订循环持续优化输出质量。