Microsoft Agent Framework 官方源码文档学习

colhan

371人浏览 · 2026-04-05 11:30:15

colhan · 2026-04-05 11:30:15 发布

1. 项目是什么

Agent Framework 是微软提供的多语言（.NET 与 Python）框架，用于构建、编排和部署 AI Agent：从简单对话 Agent 到基于图的工作流、持久化与会话恢复等。官方入门与教程以 Microsoft Learn 上的 Agent Framework 文档为主；仓库内 docs/ 主要记录架构决策（ADR）、与 Foundry/Azure SDK 的对齐规格和部分功能深读。

包与入口（.NET）：核心 NuGet 为 Microsoft.Agents.AI；按场景再选 OpenAI、Azure AI、AG-UI、Durable Task、Azure Functions 托管等包。夜间构建可通过 GitHub Packages 配置 NuGet 源（见 docs/FAQS.md）。

2. 和 Foundry SDK 的关系（规格 `001-foundry-sdk-alignment`）

两者能力有重叠，但定位不同：

	Foundry SDK	Agent Framework
性质	面向 Agent 服务的薄客户端，多由 REST 自动生成	通用 Agent 应用框架，抽象可组合本地与云端、异构 Agent
典型用途	访问服务上的一切能力	编排多 Agent、工作流、统一运行模型

目标包括：可同时使用两套 SDK 且摩擦小；能用到 Foundry 全能力；能在多 Agent 编排里纳入 Foundry Agent。

.NET 上的关键桥接：在 PersistentAgentsClient 上提供扩展方法，用服务的 Agent 构造或获取框架中的 AIAgent（实际常为 ChatClientAgent），例如 GetAIAgentAsync / CreateAIAgentAsync，从而在 Agent Framework 里 RunAsync，并用 AgentThread 做对话状态，或用 SequentialOrchestration 等多 Agent 编排。规格中的示例代码路径是：Foundry 侧建客户端 → 创建/获取持久 Agent → 框架侧运行与清理。

关于扩展方法放在哪个包（ADR 0004）：为避免给 Azure.AI.Agents.Persistent 增加对 Agent Framework 的依赖，倾向将上述扩展放在 Microsoft.Extensions.AI.Azure 一类包中，而不是塞进 Persistent 包本体。

3. Foundry 在 .NET 上的公开面（ADR `0020`）

决策：公共面以 ChatClientAgent 为中心，不引入 FoundryAgent / FoundryVersionedAgent 等平行类型层次。

直接 Responses 场景：常用 AIProjectClient.AsAIAgent(...) 等便捷重载，代码优先、不一定创建服务端持久 Agent。
服务端版本化 Agent：用原生 AIProjectClient.Agents API 管理 AgentVersion 等资源，再对 AgentRecord / AgentVersion 做 AsAIAgent(...) 包装。

CreateAIAgentAsync / GetAIAgentAsync 等可作为迁移期的兼容垫片，长期推荐上述两种路径之一。

4. 核心抽象与 Microsoft.Extensions.AI（MEAI）

AIAgent：Agent 的基类抽象；运行产生 AgentResponse / 流式 AgentResponseUpdate。
ChatClientAgent：基于 IChatClient 的实现，是 .NET 侧最常见的具体 Agent，与 MEAI 生态对齐。
会话：用 AgentThread / AgentSession（文档与 ADR 中在不同语境下强调线程状态、序列化、历史存储等）承载多轮与工具调用状态。
工具：统一在 AITool 等 MEAI 抽象上扩展；ADR 0002 讨论过从纯 RawRepresentationFactory、各厂商派生类型到通用工具类型等，结论倾向混合策略：常见能力用通用 AITool 派生、厂商特有工具在厂商包中扩展、极少数用 RawRepresentationFactory 兜底。

5. 一次「运行」返回什么（ADR `0001`）

问题：一次运行既有要给用户/调用方的结果（Primary），也有进度类信息（Secondary），还有流式、长运行引用等。

决策要点（简化理解）：

非流式：在尽量保证 TextContent 表示主结果的前提下（进度类用合适的 AIContent 子类型，避免污染 Text 聚合），沿用 ChatResponse / ChatResponseUpdate 这一路，使 response.Text 对入门场景友好。
AgentResponse 可独立于底层 Chat Client 演进（自定义响应类型设计取 Option 2 方向）。
结构化输出：不在基类上承诺「每次调用都可配 Schema」；具体实现可在构造期支持；并在 AgentResponse 上提供便于反序列化/解析结构化结果的辅助（与后续 0016 中 ResponseFormat、RunAsync<T>、Deserialize<T> 等讨论一致）。

6. 用户审批与人机协同（ADR `0006`，已接受）

要支持：本地与远程、服务端工具/MCP 审批、用户不一定在线等。

不推荐把「是否执行函数」完全交给调用方手动执行 FunctionCallContent（破坏封装，且远程 Agent 不适用）。
纯回调（如 AgentRunOptions.ApprovalCallback）在远程、跨进程恢复场景下难以挂起/恢复。

选定方案（Option 5）：引入 UserInputRequestContent / UserInputResponseContent 基类，其下再分 FunctionApprovalRequestContent、TextApprovalRequestContent、StructuredDataInputRequestContent 等。Agent 返回请求后本轮结束；调用方收集用户决策后，带着 UserInputResponseContent 再次 RunAsync，在同一对话线程上继续。
AgentResponse 上提供类似 UserInputRequests 的聚合属性（与 Text 并列），便于 UI 层处理。

7. 可观测性（ADR `0003`，提议）

采用 OpenTelemetryAgent 包装器（类比 MEAI 的 OpenTelemetryChatClient）：可选、不污染核心 Agent 类型；通过 .WithOpenTelemetry() 等扩展包装任意 AIAgent。Span/指标覆盖 agent.run / agent.run_streaming、token、错误等。

8. 运行期扩展：`FeatureCollection`（ADR `0014`）

问题：有些能力并非所有 Agent 都支持，不宜全部做成 AIAgent 上的强类型参数。

做法：在 AgentRunOptions 上通过 Features（特性集合）传递松散类型配置；支持的栈（如某装饰器、某 ChatMessageStore）在运行时取出使用，不支持的则忽略。典型场景：托管库按会话 ID 注入自己的 ChatMessageStore、结构化输出通过 feature 声明并由支持它的 Agent/装饰器处理。

9. `AIAgent` / `AgentSession` 上的附加属性（ADR `0017`）

结论：不在基类上增加 AdditionalProperties，而采用外部包装/容器承载元数据（协议卡片、托管标签等），且仅元数据、默认不下发到 IChatClient，以免与 AgentRunOptions.AdditionalProperties 语义混淆。

10. 会话序列化（ADR `0018`）

问题：原先强依赖 AIAgent.SerializeSession / DeserializeSession，行为分散、难用标准序列化、难批量处理。

选定：Option 2 — 行为与状态分离：AgentSession 侧重可序列化状态（如 StateBag）；行为（如 ChatMessageStore、AIContextProvider）挂在 Agent 侧，通过 agent.GetService<...>() 访问。
好处：可用 System.Text.Json 等标准路径序列化会话；反序列化后会话即完整。过渡期仍可能保留部分 SerializeSession / DeserializeSession，直到各实现迁完。

11. 长运行操作（ADR `0009`，已接受）

对齐 OpenAI Responses、Foundry Agents、A2A 等模式：Chat Client / Agent 既要支持短请求，也要支持异步长跑（启动得 ID、查状态、取结果、可选取消/更新等）。设计与 MEAI 的 IChatClient 扩展协同，采用增量、非破坏方式让各实现逐步支持。

12. AG-UI 协议（ADR `0010`，.NET，已接受）

.NET 包：Microsoft.Agents.AI.AGUI（客户端消费远程 AG-UI）、Microsoft.Agents.AI.Hosting.AGUI.AspNetCore（ASP.NET Core 托管、SSE）。

设计要点：AG-UI 事件类型内部化，对外仍用 AgentResponseUpdate、ChatMessage 等框架类型；用 ConversationId / ResponseId、ErrorContent 等表达生命周期；MapAGUIAgent 采用 factory 按请求构造 Agent（多租户）。线程 ID 多由应用持久化；首版侧重文本流式。

13. 聊天历史持久化与服务端一致（ADR `0022`）

背景：带工具的 FunctionInvokingChatClient 会多轮调服务；服务端（如 Responses store=true）往往是每次服务调用后落库，而框架的 ChatHistoryProvider 可能整轮结束才写；且循环被中止时，尾随的 FunctionResultContent 可能从未再发给服务，与服务端存储不一致。

决策：默认保持按 run 批量持久化（原子、简单）；新增 RequirePerServiceCallChatHistoryPersistence 可选为 true 时，改为每次服务调用后持久化，从而与服务端行为对齐并利于中断恢复；代价是失败中途可能留下不完整历史，需调用方理解语义。

14. 评估体系与 Foundry Evals（ADR `0023`）

方向：与厂商无关的评估协议 + 共享编排 — Python 为 Evaluator 协议，.NET 为 IAgentEvaluator；Foundry 作为一种实现，结果可进 Foundry 门户。支持单次与多轮、工作流、多评估器组合、对历史日志做离线评估等。

15. Agent Skills（ADR `0021`，提议，偏 .NET 设计）

技能可来自文件系统（SKILL.md）、内联 C#、类库等；对模型暴露为**渐进式工具**：load_skill、read_skill_resource、有条件时的 run_skill_script。核心抽象包括 **AgentSkill、AgentSkillResource、AgentSkillScript、AgentSkillsSource`** 等，并支持过滤与多源组合。

16. 运行上下文 `AgentRunContext`（ADR `0015`，提议）

解决嵌套调用（如 Agent 作为 AIFunction）时需要父运行的 session、options、消息等。选定：显式参数进入 RunCoreAsync + AsyncLocal 环境上下文（类似 HttpContext.Current），便于中间件、工具、子 Agent 访问 AIAgent.CurrentRunContext，同时核心逻辑仍可测。

17. Agent 过滤中间件（ADR `0007`，提议）

对标 SK Filters、AutoGen 中间件等：需要在 run / 函数调用 / 审批 / 错误等多阶段可插拔；支持流式与非流式、DI 与手动注册。文档处于设计比较阶段，具体 API 以最终实现为准。

18. 结构化输出（ADR `0016`，提议）

现状与方向：ChatClientAgent 上 ResponseFormat + 手动反序列化与 RunAsync<T> 并存；前者适合运行时类型未知、仅创建期可配 Schema、AIProjectClient 等；后者开发体验更好但受装饰器/基类限制（如包了一层 OpenTelemetryAgent 可能拿不到 RunAsync<T>）。文档主张两路互补，而非单一万能 API。

19. Create/Get Agent API 跨语言对齐（ADR `0011`，提议）

.NET：各厂商客户端上 CreateAIAgent / GetAIAgent 扩展方法较完整，可在首次调用即创建远程 Agent 或按 ID/名称拉取后包装为本地 ChatClientAgent。
Python：历史上多为 create_agent 且偏本地，远程创建时机与状态ful client 等有差异；ADR 讨论向 .NET 能力对齐（get_agent、远程 create 等）。阅读时记住：语言之间仍有演进中的对齐项。

20. Durable Agents（`docs/features/durable-agents/README.md`）

在 Durable Task / Durable Entities 上持久化会话与执行状态，支持故障恢复、扩缩容、长时间等待人工输入等。

.NET 包：

Microsoft.Agents.AI.DurableTask：DurableAIAgent、AgentEntity、DurableAgentSession、AgentSessionId 等。
Microsoft.Agents.AI.Hosting.AzureFunctions：ConfigureDurableAgents、HTTP/MCP/实体触发器等。

编排内用 DurableAIAgent（经 context.GetAgent），外部 HTTP 等用 DurableAIAgentProxy。详细教程链到 Learn 上的 Azure Functions (Durable) 集成。

21. Python 侧（简略）

包模型：pip install agent-framework --pre 会拉齐多个子包；核心抽象在 agent-framework-core，Foundry/Azure/OpenAI 等拆包（见 ADR 0021：核心变轻、OpenAI 独立包、命名以 Provider 为先，如 OpenAIChatClient 对应 Responses API 等）。
与 .NET 的共性：同样的产品叙事（Agent、工作流、可观测性、多提供商）；文档中大量 ADR 明确写了 cross-language parity 目标。
向量存储与嵌入（docs/features/vector-stores-and-embeddings/README.md）：当前文档以 Python 移植 Semantic Kernel 抽象为主（Protocol + Base、连接器列表、工具生成等）；若你做 .NET，只需知道 AF 在 Python 侧有一套统一的向量/RAG 工具化路径即可。

22. 仓库内 `docs` 目录怎么用

docs/decisions/README.md：ADR 流程（编号、模板、proposed → accepted）。
按主题读 ADR：上文的编号（如 0001、0006、0010、0020、0022）即文件名前缀，可与 docs/decisions/ 下文件一一对应。
功能深读：docs/features/durable-agents/、docs/features/vector-stores-and-embeddings/。