入门基础
适用读者：有 C# 和 .NET 开发基础，想系统学习微软 AI Agent 框架的开发者 更新日期：本文基于 2026 年 4 月发布的 Microsoft Agent Framework SDK
本教程带你从零到生产，走完 Microsoft Agent Framework 的完整入门路径。
学习路径
本教程分为 7 个章节，建议按顺序阅读：
| 章节 | 核心内容 | 预计用时 |
|---|---|---|
| Step 1：创建第一个 Agent | AIProjectClient、RunAsync、流式响应 | 20 分钟 |
| Step 2：工具调用 | Function Calling、工具注册、设计原则 | 30 分钟 |
| Step 3：多轮对话 | AgentSession、序列化与恢复 | 25 分钟 |
| Step 4：持久化内存 | ChatHistoryProvider、Context Provider | 20 分钟 |
| Step 5：工作流编排 | Executor、WorkflowBuilder、DAG | 30 分钟 |
| Step 6：托管部署 | ASP.NET Core 集成、A2A 协议、Docker | 25 分钟 |
| 常见问题 | FAQ、最佳实践、学习资源 | 15 分钟 |
前置准备
环境要求
- .NET 8 SDK 或更高版本
- Azure 订阅（可使用免费试用账户）
- 已部署的 Azure OpenAI 资源（或 OpenAI API Key）
- Visual Studio 2022 / VS Code + C# Dev Kit
官方 NuGet 包
Microsoft Agent Framework 的核心包：
| 包名 | 用途 |
|---|---|
Azure.AI.Projects | Azure AI 项目客户端，Agent 的入口点 |
Azure.Identity | Azure 身份认证（DefaultAzureCredential） |
Microsoft.Agents.AI | Agent 核心库（AIAgent 基类） |
Microsoft.Agents.AI.Workflows | 工作流引擎（可选） |
Microsoft.Agents.AI.Hosting | ASP.NET Core 托管（可选） |
MCP 开发助手
Microsoft Learn 提供了 MCP（Model Context Protocol）端点，可以让 AI 开发工具直接搜索官方文档：
# ~/.hermes/config.yaml
mcp_servers:
microsoft-learn:
url: "https://learn.microsoft.com/api/mcp"
timeout: 30配置后，AI 开发工具可以在编码过程中查询最新官方文档，覆盖日常开发中绝大部分的文档查询需求。
关于 Streamable HTTP 传输方式
Microsoft Learn 的 MCP 端点使用的是 Streamable HTTP 传输方式，而不是传统的 stdio 传输。这意味着客户端需要同时接受 application/json 和 text/event-stream 两种 Content-Type。第一次 POST 请求返回的是 SSE（Server-Sent Events）格式的响应，包含 JSON-RPC 2.0 格式的消息。Hermes Agent 的内置 MCP 客户端已经支持这种传输方式，你只需要把上面的配置添加到 config.yaml 中，重启后就能自动发现可用的 MCP 工具。
了解 Microsoft Agent Framework 的架构
Microsoft Agent Framework 由多层架构组成，理解这些层有助于你快速定位所需的功能：
┌─────────────────────────────────────────────────────────┐
│ 应用层（你的 App） │
├─────────────────────────────────────────────────────────┤
│ ┌──────────────────┐ ┌──────────────────────────────┐ │
│ │ 托管层 Hosting │ │ 协议层 A2A / OpenAI / AG-UI │ │
│ │ (DI注册/工作流) │ │ (对外暴露 Agent) │ │
│ └────────┬─────────┘ └──────────────┬───────────────┘ │
├───────────┴───────────────────────────┴─────────────────┤
│ ┌────────────────────────────────────────────────────┐ │
│ │ Agent 核心层 │ │
│ │ ChatClientAgent · AIAgent · AgentSession │ │
│ │ 工具调用 · 多轮对话 · 记忆 · 流式响应 │ │
│ └────────────────────────────────────────────────────┘ │
├─────────────────────────────────────────────────────────┤
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ │
│ │ OpenAI │ │ Azure │ │ Ollama │ │ Anthropic │ │
│ │ IChatClient│ │ IChatClient│ │ IChatClient│ │ IChatClient│ │
│ └──────────┘ └──────────┘ └──────────┘ └────────────┘ │
├─────────────────────────────────────────────────────────┤
│ 向量数据库 · 聊天历史 · Context Provider · 安全检查 │
└─────────────────────────────────────────────────────────┘这张图展示的是 MAF 的完整技术栈，从上到下分为四个层次。最上层是应用层，即你的 ASP.NET Core 项目或 Console 应用程序。第二层是托管与协议层，由 Microsoft.Agents.AI.Hosting 提供——它负责把 Agent 注册到 ASP.NET Core 的依赖注入容器中，并通过 A2A（Agent-to-Agent）协议、OpenAI 兼容端点或 AG-UI 协议对外暴露。第三层是 Agent 核心层，包含 AIAgent 基类、ChatClientAgent 实现、AgentSession 会话管理以及工具调用和流式响应等核心能力。最底层是基础设施层，包括不同 AI 提供商的 IChatClient 实现、向量数据库集成、聊天历史存储和安全检查机制。
理解这个分层架构很重要，因为你开发 Agent 时往往不会只用到某一层。举个例子：你定义了一个 ChatClientAgent（核心层），然后在 Program.cs 中用 builder.AddAIAgent() 注册到 DI（托管层），最后通过 app.MapA2A() 以 A2A 协议对外公开（协议层）。这三层是一起工作的，缺少任何一层 Agent 都无法真正服务于用户。
快速开始
准备好了？直接跳到 创建第一个 Agent 开始编码。