Microsoft Agent Framework

为什么选择 Microsoft Agent Framework？

Microsoft Agent Framework 专为那些超越了简单“提示-响应”模式的应用而设计。当 Agent 需要维护状态、调用多个工具、等待人工审批、委派任务、在中断后恢复，或者协调确定性代码与模型驱动的决策时，该框架的价值便得以体现。

该框架是 Microsoft 早期 AutoGen 和 Semantic Kernel Agent 工作的直接继任者。Microsoft 不再为实验性的多智能体协作和企业级应用集成维护独立的抽象层，而是将这些理念整合到了一个适用于 Python 和 .NET 的统一编程模型中。

这种定位对于现有的 Microsoft 用户至关重要。.NET 团队可以利用熟悉的依赖注入、Microsoft.Extensions.AI 抽象、ASP.NET Core 托管、托管身份（Managed Identity）、Azure Functions 和 OpenTelemetry。而 Python 团队则可以在不强制使用 C# 运行时的前提下，获得平行的 Agent 和工作流概念。

该框架在 Azure 之外同样可用。应用程序可以连接多个模型供应商、本地使用 Ollama、选择自定义数据库、暴露标准协议端点，并在自托管的基础设施上运行。虽然 Microsoft Foundry 是集成度最高的部署路径，但它并非核心 SDK 的必要条件。

Microsoft 文档中的一个重要设计原则是：如果普通函数能可靠地解决问题，就避免使用 Agent。Microsoft Agent Framework 的强大之处在于，它允许开发者精确决定哪些部分属于概率推理，哪些部分应保持由普通代码控制。

核心工作流

实际落地通常从单个 Agent 开始，而非完整的多智能体系统。开发者先选择模型客户端，定义精简的指令集，添加少量类型化的工具，并确定对话状态的存储方式。这建立了一个基准，以便衡量其行为、延迟、Token 消耗和失败模式。

工具契约比 Agent 的“人设（Persona）”更值得关注。每个工具都应具备精确的描述、验证过的参数、受限的权限、明确的超时机制以及可预见的错误结果。如果一个专用操作就能完成任务，就不应给模型提供通用的数据库或 Shell 接口。

下一步是决定额外的行为应放在同一个 Agent 内部，还是放在明确的工作流中。开放式委派可以保持模型驱动，但受监管或可重复的业务流程在表示为图（Graph）时通常更易于审查。确定性执行器可以在 Agent 步骤之间验证数据、应用策略或计算结果。

人工参与应作为执行设计的一部分，而非在部署后补全。在涉及资金交易、账户变更、外部消息、破坏性文件操作或其他具有重大后果的行为之前，设置审批门槛是合适的。工作流可以暂停并保留状态，待操作员响应后继续。

可观测性和评估完成了开发闭环。追踪（Traces）应显示模型调用、工具调用、路由决策、Token 使用情况、延迟和错误。随后，通过可重复的评估集测试模型、指令、工具或工作流拓扑的变更是否真正改善了预期结果，而不仅仅是产生了更流利的回答。

Agent vs. 显式工作流

当任务属于对话性质、可用操作有限且模型能合理决定下一步行动时，使用单个 Agent 是合适的。例如：基于知识源回答问题、在多个检索工具中进行选择，或从用户处收集缺失信息。

当应用程序有固定阶段、固定审批、分支业务规则或不能仅凭模型判断的义务时，工作流则更为理想。例如理赔流程：可能使用一个 Agent 来解读非结构化描述，使用确定性代码验证保单数据，再由第二个 Agent 起草建议，最后在支付前经过人工审批门槛。

多智能体编排不应被视为单个 Agent 的自动升级。每增加一个参与者都会引入更多的 Prompt、状态转换、延迟、模型调用以及潜在的分歧。只有当不同的 Agent 需要独立的权限、上下文、模型、评估标准或所有权边界时，分离 Agent 才是最合理的。

图模型有助于使这些边界可视化。顺序执行适合审核流水线；并发执行适合独立的调研任务；移交（Handoffs）适合在专家之间进行路由；经理式编排适合事先不知道所需子任务的问题。选择哪种模式取决于应由代码还是模型掌握路由控制权。

适用场景

企业流程自动化： 该框架可以协调分类、文档分析、策略查询、审批和记录更新，同时将确定性的业务规则保留在语言模型之外。

客户支持编排： 分拣 Agent 可以将对话路由给专门处理退款、账单或技术支持的 Agent。在员工批准相应的工具调用之前，敏感的账户操作可以保持锁定状态。

调研与审核流水线： 在审核 Agent 比较调查结果之前，多个 Agent 可以并行调研独立来源。确定性代码可以强制执行引用结构、去除重复证据并拒绝不完整的输出。

软件运维助手： Agent 可以收集诊断数据并提出修复建议，而工具则暴露窄限度范围的运维操作。审批和审计控制可以防止模型在无约束的情况下更改基础设施。

长周期后台工作： 当流程必须等待外部事件、在重启后恢复、请求额外信息或暂停数小时或数天后再继续时，持久化执行（Durable Execution）非常有用。

跨框架 Agent 网络： A2A 支持允许 Agent Framework 应用发现并与兼容的远程 Agent 通信。这在不同部门或供应商使用不同运行时实现 Agent 时非常有用。

智能体 Web 应用： AG-UI 集成可以将 Agent 活动、工作流状态、审批请求和工具进度流式传输到前端，为用户提供比纯聊天界面更丰富的上下文。

同类工具对比

LangGraph 是那些寻求有状态图编排和对执行路径进行显式控制的开发者的首选。它在 Python 和 JavaScript 生态中拥有极高的采用率。相比之下，Microsoft Agent Framework 与 .NET、Microsoft.Extensions.AI、Microsoft Foundry 以及从 AutoGen 和 Semantic Kernel 迁移的路径结合得更紧密。

CrewAI 强调以角色为导向的 Agent 团队和基于任务的协作。这种模型非常适合快速描述一组专家。而 Microsoft Agent Framework 在将 Agent 与确定性执行器、类型化路由、检查点、中间件和企业托管模式结合方面通常表现得更加显式。

OpenAI Agents SDK 提供了一种围绕 OpenAI 服务构建 Agent、工具、移交、护栏和追踪的专注方式。如果应用意在以 OpenAI 平台为中心，它会更简单。Microsoft Agent Framework 则提供了更广泛的供应商抽象，并与 Python 并行提供了一流的 .NET 实现。

Google Agent Development Kit 是以 Gemini 和 Google Cloud 为中心的应用的自然选择。这一决策类似于更广泛的平台选择：组织已经在利用哪套身份系统、模型目录、可观测性栈、部署环境和托管 Agent 服务。

PydanticAI 吸引了重视类型化输出、依赖注入、验证和紧凑编程模型的 Python 团队。Microsoft Agent Framework 涵盖了更大的编排和托管范围，但这种额外的能力范围也增加了团队需要理解的概念数量。

AutoGen 和 Semantic Kernel 仍是重要的对比目标，因为许多现有的 Microsoft Agent 应用都在使用它们。对于新的 Microsoft 项目，Agent Framework 是面向未来的选择。然而，迁移不一定是机械式的包替换；应根据新的统一 Agent 和工作流模型重新思考现有的对话模式和插件架构。

最佳配置建议

在应用的核心路径上使用稳定版程序包，并将预览版集成隔离在内部接口之后。框架的 1.0 版本 API 具有兼容性承诺，但较新的 harness、安全、UI、托管和研究包可能会演进得更快。

原型开发完成后，仅安装应用所需的供应商包。Python 元数据包（meta-package）便于探索，但更小的依赖集可以减少镜像体积、间接漏洞、启动开销，并避免误配置未使用的服务。

将供应商选择隐藏在应用自有的工厂类或配置层之后。通用的 Agent 接口可以减少迁移工作，但不同供应商在工具调用、结构化输出、托管工具、上下文限制、认证和错误语义方面仍存在差异。供应商特定的行为不应泄露到业务逻辑中。

赋予工具精简的能力，并使写操作具备幂等性。Agent 可能会在超时或工作流恢复后重试，因此重复的工具调用不应意外导致重复扣款、重复发信、重复创建工单或重复申请资源。

为关键操作使用“需要审批”的包装器。审批数据应包括提议的操作、相关参数、预期效果、发起请求的 Agent 以及工作流上下文，以便审核员能做出明智决策，而非盲目批准一个晦涩的函数名称。

按用途选择存储方案。短期对话历史、长期用户事实、工作流状态、检索文档和 Agent 生成的工作笔记属于不同的数据类别。将它们全部存入一个向量索引会增加保留策略、访问控制、删除和相关性调优的难度。

将 OpenTelemetry 数据导出到现有的可观测性后端，但除非有明确的调试需求，否则请禁用敏感的 Prompt 和响应捕获。启用内容日志记录时，应应用脱敏、访问控制、保留限制和环境隔离。

在本地使用 DevUI 检查消息流和工作流执行。但在生产环境中需构建独立的身份验证界面，因为 DevUI 只是开发示例，而非加固后的最终用户应用。

对于长周期流程，将检查点持久化在工作进程之外。Azure Functions 及其 Durable Extension 提供了托管路径，而自备计算资源（BYOC）部署可以将持久化工作进程连接到外部调度器。无论哪种情况，都应通过故意重启和重复交付场景来测试恢复行为。

从 AutoGen 迁移

AutoGen 应用通常通过多个 Agent 之间的对话来编码协调逻辑。在迁移过程中，请识别哪些交互代表真正的自主协作，哪些实际上是固定的流程阶段（应转换为工作流的边）。

将供应商特定的 Agent 类映射到新的通用 Agent 抽象，然后在适当的地方将横切关注点（cross-cutting behavior）移入中间件。日志记录、验证、限流、安全检查、重试策略和内容过滤不应在每个 Prompt 中重复。

应针对现有的编排模式评估现有的群聊。例如，顺序审核流程作为显式序列进行测试，比作为一个“通常能产生相同顺序”的开放群聊更容易。

在更改实现之前保留行为测试。捕获代表性的输入、预期的工具调用、路由结果、审批点和失败案例。对比这些追踪记录比检查迁移后的应用是否产生措辞相似的文本更有用。

从 Semantic Kernel 迁移

Semantic Kernel 用户应预期程序包名称、消息类型、Agent 构建方式、调用方法、选项和工具注册方面的变化。Microsoft Agent Framework 依赖于通用的 Microsoft.Extensions.AI 内容抽象，并在受支持的聊天客户端中使用统一的 Agent 模型。

内核插件（Kernel plugins）通常可以转换为直接的函数工具。这能减少框架特定的属性和模板代码，同时也是精简过于庞大的插件、将读操作与修改外部系统的操作分离的好机会。

以前为不同供应商使用不同 Semantic Kernel Agent 类的应用可以转向统一的 Agent 抽象。供应商特定的配置仍存在于客户端层，但高层应用代码可以依赖共享接口。

托管对话语义需要特别注意。并非所有供应商都支持相同的服务端历史记录或删除行为，因此会话生命周期和保留策略应进行显式设计，而非沿用之前后端的假设。

建议一次迁移一个垂直工作流。针对同一套评估集运行旧版和新版实现，有助于识别由 Prompt、供应商版本、历史处理、工具 Schema 或框架本身引起的差异。

生产环境架构

将 Agent 层视为应用程序的一个组件，而非全部。身份验证、授权、计费、记录归属、策略决策和不可逆的状态变更应保留在具有显式接口的普通服务中。

Agent 指令不是安全边界。告诉 Agent 不要访问某些记录的 Prompt，其效力远弱于一个从不返回这些记录的工具。权限应在检索数据时执行，并在执行操作时再次校验。

将外部内容与可信指令分离。网页、检索到的文档、电子邮件、MCP 响应和远程 Agent 消息可能包含 Prompt 注入或误导性指令。在未经验证或审批的情况下，不应让不可信内容直接驱动敏感工具。

在切换模型之前建立评估套件。如果团队无法确定替代模型是否保持了路由准确性、工具选择、结构化输出、安全行为、延迟和成本，那么供应商灵活性就没多大价值。

预算应基于完整的工作流追踪，而非单次模型调用的价格。多智能体应用可能会调用多次模型、在工具执行后重复调用、检索文档、写入内存、发出遥测数据，并在多轮对话中保持活跃。

部署方案还应包括并发限制、超时、取消、熔断、限流、死信处理以及针对废弃工作流的操作员干预路径。Agent 特定的抽象并不能取代传统的分布式系统工程。

权衡与代价

供应商中立性减少了架构耦合，但并不意味着模型可以无缝互换。在一个供应商上测试过的工作流，由于工具调用格式、推理风格、上下文处理、安全过滤器或对托管能力支持的不同，在切换后行为可能会有所不同。

共享的 Python 和 .NET 设计对多语言组织很有价值，但两种实现并不总能同步获得每个集成功能。团队在承诺使用某个接口或部署特性前，应核实特定语言的文档。

持久化和多智能体执行提高了韧性，但也扩大了状态模型。开发者必须决定哪些消息、工具结果、检查点、文件、审批和记忆可以在部署变更后回放、删除或保留。

本地 Ollama 支持可以增强对数据流和实验成本的控制，但本地推理并不自动等同于企业级隐私或性能。组织仍需加固主机、选择合适的模型、管理更新、监控输出质量并提供充足的算力。

框架提供了有用的控制手段，但它并不保证生成的 Agent 必然安全、准确或合规。这些属性取决于所选模型、数据、指令、工具权限、评估体系、接口、部署架构和运维策略。