Microsoft Agent Framework 官方源码文档学习

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 SDKAgent 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 → 框架侧运行与清理。关于扩展方法放在哪个包ADR0004为避免给Azure.AI.Agents.Persistent增加对 Agent Framework 的依赖倾向将上述扩展放在Microsoft.Extensions.AI.Azure一类包中而不是塞进 Persistent 包本体。3. Foundry 在 .NET 上的公开面ADR0020决策公共面以ChatClientAgent为中心不引入FoundryAgent/FoundryVersionedAgent等平行类型层次。直接 Responses 场景常用AIProjectClient.AsAIAgent(...)等便捷重载代码优先、不一定创建服务端持久 Agent。服务端版本化 Agent用原生AIProjectClient.AgentsAPI 管理AgentVersion等资源再对AgentRecord/AgentVersion做AsAIAgent(...)包装。CreateAIAgentAsync/GetAIAgentAsync等可作为迁移期的兼容垫片长期推荐上述两种路径之一。4. 核心抽象与 Microsoft.Extensions.AIMEAIAIAgentAgent 的基类抽象运行产生AgentResponse/ 流式AgentResponseUpdate。ChatClientAgent基于IChatClient的实现是 .NET 侧最常见的具体 Agent与 MEAI 生态对齐。会话用AgentThread/AgentSession文档与 ADR 中在不同语境下强调线程状态、序列化、历史存储等承载多轮与工具调用状态。工具统一在AITool等 MEAI 抽象上扩展ADR0002讨论过从纯RawRepresentationFactory、各厂商派生类型到通用工具类型等结论倾向混合策略常见能力用通用AITool派生、厂商特有工具在厂商包中扩展、极少数用RawRepresentationFactory兜底。5. 一次「运行」返回什么ADR0001问题一次运行既有要给用户/调用方的结果Primary也有进度类信息Secondary还有流式、长运行引用等。决策要点简化理解非流式在尽量保证TextContent表示主结果 的前提下进度类用合适的AIContent子类型避免污染Text聚合沿用ChatResponse/ChatResponseUpdate这一路使response.Text对入门场景友好。AgentResponse可独立于底层 Chat Client 演进自定义响应类型设计取 Option 2 方向。结构化输出不在基类上承诺「每次调用都可配 Schema」具体实现可在构造期支持并在AgentResponse上提供便于反序列化/解析结构化结果的辅助与后续0016中ResponseFormat、RunAsyncT、DeserializeT等讨论一致。6. 用户审批与人机协同ADR0006已接受要支持本地与远程、服务端工具/MCP 审批、用户不一定在线等。不推荐把「是否执行函数」完全交给调用方手动执行FunctionCallContent破坏封装且远程 Agent 不适用。纯回调如AgentRunOptions.ApprovalCallback在远程、跨进程恢复场景下难以挂起/恢复。选定方案Option 5引入UserInputRequestContent/UserInputResponseContent基类其下再分FunctionApprovalRequestContent、TextApprovalRequestContent、StructuredDataInputRequestContent等。Agent 返回请求后本轮结束调用方收集用户决策后带着UserInputResponseContent再次RunAsync在同一对话线程上继续。AgentResponse上提供类似UserInputRequests的聚合属性与Text并列便于 UI 层处理。7. 可观测性ADR0003提议采用OpenTelemetryAgent包装器类比 MEAI 的OpenTelemetryChatClient可选、不污染核心 Agent 类型通过.WithOpenTelemetry()等扩展包装任意AIAgent。Span/指标覆盖agent.run/agent.run_streaming、token、错误等。8. 运行期扩展FeatureCollectionADR0014问题有些能力并非所有 Agent 都支持不宜全部做成AIAgent上的强类型参数。做法在AgentRunOptions上通过Features特性集合 传递松散类型配置支持的栈如某装饰器、某ChatMessageStore在运行时取出使用不支持的则忽略。典型场景托管库按会话 ID 注入自己的ChatMessageStore、结构化输出通过 feature 声明并由支持它的 Agent/装饰器处理。9.AIAgent/AgentSession上的附加属性ADR0017结论不在基类上增加AdditionalProperties而采用外部包装/容器承载元数据协议卡片、托管标签等且仅元数据、默认不下发到IChatClient以免与AgentRunOptions.AdditionalProperties语义混淆。10. 会话序列化ADR0018问题原先强依赖AIAgent.SerializeSession/DeserializeSession行为分散、难用标准序列化、难批量处理。选定Option 2 — 行为与状态分离AgentSession侧重可序列化状态如StateBag行为如 ChatMessageStore、AIContextProvider挂在 Agent 侧通过agent.GetService...()访问。好处可用System.Text.Json等标准路径序列化会话反序列化后会话即完整。过渡期仍可能保留部分SerializeSession/DeserializeSession直到各实现迁完。11. 长运行操作ADR0009已接受对齐 OpenAI Responses、Foundry Agents、A2A 等模式Chat Client / Agent 既要支持短请求也要支持异步长跑启动得 ID、查状态、取结果、可选取消/更新等。设计与 MEAI 的IChatClient扩展协同采用增量、非破坏方式让各实现逐步支持。12. AG-UI 协议ADR0010.NET已接受.NET 包Microsoft.Agents.AI.AGUI客户端消费远程 AG-UI、Microsoft.Agents.AI.Hosting.AGUI.AspNetCoreASP.NET Core 托管、SSE。设计要点AG-UI 事件类型内部化对外仍用AgentResponseUpdate、ChatMessage等框架类型用ConversationId/ResponseId、ErrorContent等表达生命周期MapAGUIAgent采用 factory 按请求构造 Agent多租户。线程 ID 多由应用持久化首版侧重文本流式。13. 聊天历史持久化与服务端一致ADR0022背景带工具的FunctionInvokingChatClient会多轮调服务服务端如 Responsesstoretrue往往是每次服务调用后落库而框架的ChatHistoryProvider可能整轮结束才写且循环被中止时尾随的FunctionResultContent可能从未再发给服务与服务端存储不一致。决策默认保持按 run 批量持久化原子、简单新增RequirePerServiceCallChatHistoryPersistence可选为 true 时改为每次服务调用后持久化从而与服务端行为对齐并利于中断恢复代价是失败中途可能留下不完整历史需调用方理解语义。14. 评估体系与 Foundry EvalsADR0023方向与厂商无关的评估协议 共享编排 — Python 为Evaluator协议.NET 为IAgentEvaluatorFoundry 作为一种实现结果可进 Foundry 门户。支持单次与多轮、工作流、多评估器组合、对历史日志做离线评估等。15. Agent SkillsADR0021提议偏 .NET 设计技能可来自文件系统SKILL.md、内联 C#、类库等对模型暴露为**渐进式工具**load_skill、read_skill_resource、有条件时的run_skill_script。核心抽象包括 **AgentSkill、AgentSkillResource、AgentSkillScript、AgentSkillsSource** 等并支持过滤与多源组合。16. 运行上下文AgentRunContextADR0015提议解决嵌套调用如 Agent 作为AIFunction时需要父运行的 session、options、消息等。选定显式参数进入RunCoreAsyncAsyncLocal环境上下文类似HttpContext.Current便于中间件、工具、子 Agent 访问AIAgent.CurrentRunContext同时核心逻辑仍可测。17. Agent 过滤中间件ADR0007提议对标 SK Filters、AutoGen 中间件等需要在 run / 函数调用 / 审批 / 错误 等多阶段可插拔支持流式与非流式、DI 与手动注册。文档处于设计比较阶段具体 API 以最终实现为准。18. 结构化输出ADR0016提议现状与方向ChatClientAgent上ResponseFormat 手动反序列化 与RunAsyncT并存前者适合运行时类型未知、仅创建期可配 Schema、AIProjectClient等后者开发体验更好但受装饰器/基类限制如包了一层OpenTelemetryAgent可能拿不到RunAsyncT。文档主张两路互补而非单一万能 API。19. Create/Get Agent API 跨语言对齐ADR0011提议.NET各厂商客户端上CreateAIAgent/GetAIAgent扩展方法较完整可在首次调用即创建远程 Agent 或按 ID/名称拉取后包装为本地ChatClientAgent。Python历史上多为create_agent且偏本地远程创建时机与状态ful client 等有差异ADR 讨论向 .NET 能力对齐get_agent、远程create等。阅读时记住语言之间仍有演进中的对齐项。20. Durable Agentsdocs/features/durable-agents/README.md在 Durable Task / Durable Entities 上持久化会话与执行状态支持故障恢复、扩缩容、长时间等待人工输入等。.NET 包Microsoft.Agents.AI.DurableTaskDurableAIAgent、AgentEntity、DurableAgentSession、AgentSessionId等。Microsoft.Agents.AI.Hosting.AzureFunctionsConfigureDurableAgents、HTTP/MCP/实体触发器等。编排内用DurableAIAgent经context.GetAgent外部 HTTP 等用DurableAIAgentProxy。详细教程链到 Learn 上的 Azure Functions (Durable) 集成。21. Python 侧简略包模型pip install agent-framework --pre会拉齐多个子包核心抽象在agent-framework-coreFoundry/Azure/OpenAI 等拆包见 ADR0021核心变轻、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.mdADR 流程编号、模板、proposed→accepted。按主题读 ADR上文的编号如0001、0006、0010、0020、0022即文件名前缀可与docs/decisions/下文件一一对应。功能深读docs/features/durable-agents/、docs/features/vector-stores-and-embeddings/。