 实战：用 .NET 与 Python 构建多智能体工作流)
1. 从一次真实的多智能体踩坑说起如果你正在把 AI 代理接入已有的 .NET 或 Python 业务系统大概率会遇到这样的场景客服系统里需要一个代理判断用户意图一个代理查订单一个代理写回复但它们各自为战状态对不上、上下文丢失、错误没法回溯。我试过用纯 Prompt 拼接硬扛结果一到并发就乱套。Microsoft Agent FrameworkMAF就是为解决这类多智能体编排问题而生的开源框架它同时提供 .NET 和 Python 两套 API定位是构建 AI 代理和多代理工作流的统一底座。简单说MAF 能做什么它把「代理」和「工作流」拆成两个核心构建块Agent 负责用 LLM 推理、调工具、维护会话Workflow 负责把多个 Agent 或工具按图结构串起来支持顺序、并发、交接、群聊等编排模式。适合谁适合需要把 AI 能力嵌入现有业务系统、又不想被单一模型厂商锁定的开发者。MAF 1.0 已经稳定并承诺长期支持建立在 Microsoft.Extensions.AI 的 IChatClient 抽象之上换模型提供商不用改业务代码。下面我从项目骨架开始带你跑通一个最小可用的多智能体任务分发与结果回收示例。2. TaoToken 前置给 MAF 一个稳定的模型入口MAF 本身不绑定模型它通过 IChatClient 连接各种提供商。实际开发中模型端点的稳定性和密钥管理往往是第一个卡点。我习惯用 TaoToken 作为统一的模型接入层它兼容 OpenAI 风格的接口MAF 的 OpenAI 连接器可以直接指向它省去为每个提供商写适配代码的麻烦。在动手写代码前你需要先准备好三样东西Base URL、API Key、Model ID。这三件套在任何 MAF 配置里都会反复出现建议先记下来。Base URL 使用https://taotoken.net/api注意这个地址不带任何查询参数。API Key 需要到控制台创建路径是 API Keys 页面。Model ID 则根据你实际要调用的模型填写比如gpt-4o或claude-3-5-sonnet这类标识。如果你还没创建密钥可以按这个顺序操作先访问控制台进入 API Keys 管理页新建一个密钥并复制保存。密钥只在创建时完整显示一次丢了就得重建。创建完成后建议先用模型对话页面做一次最简单的连通性验证确认密钥和模型 ID 能正常工作再进入 MAF 项目配置。这一步能帮你排除掉大部分「代码没问题但请求失败」的情况。对于长期做编码和 Agent 开发的场景Coding Plan 提供了更稳定的配额和调用策略适合把 MAF 工作流跑在生产或持续集成环境里。而如果你只是想先验证模型是否可用模型对话页面是最轻量的入口。需要强调的是MAF 的 IChatClient 抽象让你可以在不改业务代码的前提下切换提供商。这意味着你完全可以在开发阶段用一套配置上线后换成另一套只要 Base URL、Key、Model ID 三件套对应调整即可。这种解耦正是 MAF 相比直接调 SDK 的优势所在。3. 可复制配置.NET 与 Python 双栈项目骨架这一节给出可以直接复制的配置片段。MAF 在 .NET 和 Python 下的项目结构略有不同但核心概念一致先建 ChatClient再包成 Agent最后用 WorkflowBuilder 串联。3.1 .NET 项目骨架与 appsettings.json先建一个控制台项目添加 MAF 相关包。项目文件里需要引用 Microsoft.Extensions.AI 和 Agent Framework 的包。下面是一个典型的appsettings.json把模型三件套放在配置里避免硬编码{ TaoToken: { BaseUrl: https://taotoken.net/api, ApiKey: sk-你的密钥, ModelId: gpt-4o }, Agent: { Name: RouterAgent, Instructions: 你是一个任务路由代理负责判断用户请求类型并分发给对应子代理。 } }注意 BaseUrl 不要带 UTM 参数保持干净的 API 根路径。ApiKey 建议通过环境变量注入配置文件里只留占位符生产环境用dotnet user-secrets或环境变量覆盖。3.2 Python 项目骨架与 settings.tomlPython 侧我用 TOML 管理配置结构更清晰[taotoken] base_url https://taotoken.net/api api_key sk-你的密钥 model_id gpt-4o [agent.router] name RouterAgent instructions 你是一个任务路由代理负责判断用户请求类型并分发给对应子代理。 [agent.order] name OrderAgent instructions 你负责查询订单状态调用订单查询工具并返回结构化结果。Python 项目建议用虚拟环境依赖里包含agent-framework和openai兼容包。配置文件放在项目根目录通过tomllib读取。3.3 代理注册与工作流串联.NET 下创建 Agent 的核心代码是这样先根据配置构造 ChatClient再用AsAIAgent()扩展方法包装成代理。工具注册用AIFunctionFactory.Create()把普通 C# 方法转成 AIFunction框架会自动生成 JSON Schema。var chatClient new ChatClientBuilder() .UseOpenAI(config[TaoToken:BaseUrl], config[TaoToken:ApiKey], config[TaoToken:ModelId]) .Build(); var routerAgent chatClient.AsAIAgent(new AgentOptions { Name RouterAgent, Instructions 判断请求类型并路由 }); var orderTool AIFunctionFactory.Create((string orderId) QueryOrder(orderId)); var orderAgent chatClient.AsAIAgent(new AgentOptions { Name OrderAgent, Instructions 查询订单, Tools [orderTool] });Python 侧逻辑对称用Agent类和ai_function装饰器注册工具。工作流用WorkflowBuilder构建把 Executor 节点和 Edge 连起来形成 DAG。顺序编排用AddEdge依次连接并发编排用 Fan-Out/Fan-In 模式一个节点输出连到多个下游再汇聚到一个聚合节点。这里的关键是 WorkflowContext 作为共享状态容器各 Executor 通过它读写中间结果。Checkpoint 机制支持断点续跑长流程任务中断后能从存档点恢复不用从头再来。4. 验证请求端到端任务分发与结果回收配置写完后必须做一次端到端验证确认任务能从路由代理分发到子代理再把结果回收聚合。这一步能暴露配置错误、模型不兼容、工具签名不对等问题。4.1 发起一次分发请求在 .NET 里调用RunAsync()启动工作流传入用户请求。工作流首先进入 RouterAgent它根据 Instructions 判断请求类型。比如用户问「我的订单 12345 到哪了」RouterAgent 识别为订单查询通过 Edge 把任务转给 OrderAgent。var workflow new WorkflowBuilder() .AddExecutor(routerExecutor) .AddExecutor(orderExecutor) .AddEdge(routerExecutor, orderExecutor) .Build(); var result await workflow.RunAsync(我的订单 12345 到哪了); Console.WriteLine(result.Output);Python 侧调用方式类似用await workflow.run(input)触发。执行过程中OrderAgent 会调用注册的订单查询工具拿到结构化数据后生成自然语言回复。4.2 观察结果回收成功的结果应该包含两部分一是最终回复文本二是工作流各节点的执行轨迹。MAF 集成 OpenTelemetry可以把追踪数据导出到可观测性平台看到每个 Executor 的耗时、输入输出、工具调用记录。如果一切正常你会看到 RouterAgent 输出路由决策OrderAgent 输出订单状态聚合节点把两者合并成最终回复。流式执行用RunStreamingAsync()适合需要边生成边展示的场景。验证时建议先用最简单的单代理工作流跑通再加第二个代理逐步增加复杂度。这样出问题时能快速定位是配置、工具还是编排逻辑的锅。5. 本篇常见错排查401、local proxy failed 与 OAuth实际跑 MAF 时报错集中在几个地方。下面按真实错误信息对照排查。401 Unauthorized最常见。先检查 API Key 是否正确、是否过期、有没有多余空格。再确认 Base URL 是否写成了带路径的形式MAF 的 OpenAI 连接器期望的是 API 根地址。如果密钥没问题检查请求头里的 Authorization 格式是否为Bearer sk-xxx。local proxy failed / connection refused这类错误通常出现在本地开发环境说明请求根本没发出去。检查网络配置、防火墙、以及 Base URL 是否可达。如果你在容器里跑确认容器网络能访问外部端点。注意不要配置任何非官方的网络转发工具直接用标准 HTTPS 请求即可。reading choices 相关报错这通常意味着响应体结构和预期不符。可能是 Model ID 填错了或者模型返回了非标准格式。先用模型对话页面单独验证该 Model ID 能否正常返回再回到 MAF 里排查。如果用的是兼容接口确认返回的 JSON 里有choices字段。OAuth / 认证失败如果你用的是需要 OAuth 的提供商检查 token 获取流程。MAF 的 IChatClient 抽象层对认证方式有约定OAuth 场景下需要确保 token 刷新逻辑正确。用 TaoToken 的 API Key 方式可以绕过这类复杂度直接走 Bearer 认证。工具调用签名不匹配AIFunctionFactory 自动生成 JSON Schema但如果参数类型复杂比如嵌套对象LLM 可能理解偏差。建议工具参数保持扁平用基础类型必要时加描述。排查时记住一个原则先隔离变量。用最小请求验证模型端点再加 Agent再加 Workflow。每加一层就验证一次比一次性搭完再 debug 高效得多。6. 把 MAF 接入你的业务系统跑通最小示例后下一步是把它接入真实业务。MAF 的 AgentSession 提供框架托管的对话状态支持持久化和上下文恢复这对多轮客服场景很关键。AIContextProvider 可以注入外部数据比如把向量检索结果塞进代理上下文实现 RAG 增强。多代理编排模式里Handoff 适合任务需要转交给更专业代理的场景Group Chat 适合多个代理协作讨论Magentic-One 适合动态任务协调。选择哪种取决于你的业务复杂度不必一上来就用最复杂的模式。跨运行时互操作方面MAF 支持 A2A 协议做代理间通信MCP 协议接入工具生态AG-UI 协议对接前端。这意味着你的 .NET 代理可以和 Python 代理协同工作也可以把代理暴露成 MCP 工具供其他系统调用。如果你打算长期做 Agent 开发建议把 Coding Plan 纳入考虑它能提供更稳定的调用配额适合持续集成和自动化测试。而日常调试和模型验证模型对话页面足够轻量。接入文档里有各语言连接器的详细参数说明遇到配置问题可以先查文档再排查。最后给一个实用建议把 Agent 的 Instructions、工具定义、工作流结构都纳入版本控制。MAF 支持声明式 Agent用 YAML 定义配置这样团队协作时变更可追溯部署一致性也有保障。声明式定义和代码分离是 MAF 相比手写编排逻辑的另一个优势。
1. 从一次真实的多智能体踩坑说起如果你正在把 AI 代理接入已有的 .NET 或 Python 业务系统大概率会遇到这样的场景客服系统里需要一个代理判断用户意图一个代理查订单一个代理写回复但它们各自为战状态对不上、上下文丢失、错误没法回溯。我试过用纯 Prompt 拼接硬扛结果一到并发就乱套。Microsoft Agent FrameworkMAF就是为解决这类多智能体编排问题而生的开源框架它同时提供 .NET 和 Python 两套 API定位是构建 AI 代理和多代理工作流的统一底座。简单说MAF 能做什么它把「代理」和「工作流」拆成两个核心构建块Agent 负责用 LLM 推理、调工具、维护会话Workflow 负责把多个 Agent 或工具按图结构串起来支持顺序、并发、交接、群聊等编排模式。适合谁适合需要把 AI 能力嵌入现有业务系统、又不想被单一模型厂商锁定的开发者。MAF 1.0 已经稳定并承诺长期支持建立在 Microsoft.Extensions.AI 的 IChatClient 抽象之上换模型提供商不用改业务代码。下面我从项目骨架开始带你跑通一个最小可用的多智能体任务分发与结果回收示例。2. TaoToken 前置给 MAF 一个稳定的模型入口MAF 本身不绑定模型它通过 IChatClient 连接各种提供商。实际开发中模型端点的稳定性和密钥管理往往是第一个卡点。我习惯用 TaoToken 作为统一的模型接入层它兼容 OpenAI 风格的接口MAF 的 OpenAI 连接器可以直接指向它省去为每个提供商写适配代码的麻烦。在动手写代码前你需要先准备好三样东西Base URL、API Key、Model ID。这三件套在任何 MAF 配置里都会反复出现建议先记下来。Base URL 使用https://taotoken.net/api注意这个地址不带任何查询参数。API Key 需要到控制台创建路径是 API Keys 页面。Model ID 则根据你实际要调用的模型填写比如gpt-4o或claude-3-5-sonnet这类标识。如果你还没创建密钥可以按这个顺序操作先访问控制台进入 API Keys 管理页新建一个密钥并复制保存。密钥只在创建时完整显示一次丢了就得重建。创建完成后建议先用模型对话页面做一次最简单的连通性验证确认密钥和模型 ID 能正常工作再进入 MAF 项目配置。这一步能帮你排除掉大部分「代码没问题但请求失败」的情况。对于长期做编码和 Agent 开发的场景Coding Plan 提供了更稳定的配额和调用策略适合把 MAF 工作流跑在生产或持续集成环境里。而如果你只是想先验证模型是否可用模型对话页面是最轻量的入口。需要强调的是MAF 的 IChatClient 抽象让你可以在不改业务代码的前提下切换提供商。这意味着你完全可以在开发阶段用一套配置上线后换成另一套只要 Base URL、Key、Model ID 三件套对应调整即可。这种解耦正是 MAF 相比直接调 SDK 的优势所在。3. 可复制配置.NET 与 Python 双栈项目骨架这一节给出可以直接复制的配置片段。MAF 在 .NET 和 Python 下的项目结构略有不同但核心概念一致先建 ChatClient再包成 Agent最后用 WorkflowBuilder 串联。3.1 .NET 项目骨架与 appsettings.json先建一个控制台项目添加 MAF 相关包。项目文件里需要引用 Microsoft.Extensions.AI 和 Agent Framework 的包。下面是一个典型的appsettings.json把模型三件套放在配置里避免硬编码{ TaoToken: { BaseUrl: https://taotoken.net/api, ApiKey: sk-你的密钥, ModelId: gpt-4o }, Agent: { Name: RouterAgent, Instructions: 你是一个任务路由代理负责判断用户请求类型并分发给对应子代理。 } }注意 BaseUrl 不要带 UTM 参数保持干净的 API 根路径。ApiKey 建议通过环境变量注入配置文件里只留占位符生产环境用dotnet user-secrets或环境变量覆盖。3.2 Python 项目骨架与 settings.tomlPython 侧我用 TOML 管理配置结构更清晰[taotoken] base_url https://taotoken.net/api api_key sk-你的密钥 model_id gpt-4o [agent.router] name RouterAgent instructions 你是一个任务路由代理负责判断用户请求类型并分发给对应子代理。 [agent.order] name OrderAgent instructions 你负责查询订单状态调用订单查询工具并返回结构化结果。Python 项目建议用虚拟环境依赖里包含agent-framework和openai兼容包。配置文件放在项目根目录通过tomllib读取。3.3 代理注册与工作流串联.NET 下创建 Agent 的核心代码是这样先根据配置构造 ChatClient再用AsAIAgent()扩展方法包装成代理。工具注册用AIFunctionFactory.Create()把普通 C# 方法转成 AIFunction框架会自动生成 JSON Schema。var chatClient new ChatClientBuilder() .UseOpenAI(config[TaoToken:BaseUrl], config[TaoToken:ApiKey], config[TaoToken:ModelId]) .Build(); var routerAgent chatClient.AsAIAgent(new AgentOptions { Name RouterAgent, Instructions 判断请求类型并路由 }); var orderTool AIFunctionFactory.Create((string orderId) QueryOrder(orderId)); var orderAgent chatClient.AsAIAgent(new AgentOptions { Name OrderAgent, Instructions 查询订单, Tools [orderTool] });Python 侧逻辑对称用Agent类和ai_function装饰器注册工具。工作流用WorkflowBuilder构建把 Executor 节点和 Edge 连起来形成 DAG。顺序编排用AddEdge依次连接并发编排用 Fan-Out/Fan-In 模式一个节点输出连到多个下游再汇聚到一个聚合节点。这里的关键是 WorkflowContext 作为共享状态容器各 Executor 通过它读写中间结果。Checkpoint 机制支持断点续跑长流程任务中断后能从存档点恢复不用从头再来。4. 验证请求端到端任务分发与结果回收配置写完后必须做一次端到端验证确认任务能从路由代理分发到子代理再把结果回收聚合。这一步能暴露配置错误、模型不兼容、工具签名不对等问题。4.1 发起一次分发请求在 .NET 里调用RunAsync()启动工作流传入用户请求。工作流首先进入 RouterAgent它根据 Instructions 判断请求类型。比如用户问「我的订单 12345 到哪了」RouterAgent 识别为订单查询通过 Edge 把任务转给 OrderAgent。var workflow new WorkflowBuilder() .AddExecutor(routerExecutor) .AddExecutor(orderExecutor) .AddEdge(routerExecutor, orderExecutor) .Build(); var result await workflow.RunAsync(我的订单 12345 到哪了); Console.WriteLine(result.Output);Python 侧调用方式类似用await workflow.run(input)触发。执行过程中OrderAgent 会调用注册的订单查询工具拿到结构化数据后生成自然语言回复。4.2 观察结果回收成功的结果应该包含两部分一是最终回复文本二是工作流各节点的执行轨迹。MAF 集成 OpenTelemetry可以把追踪数据导出到可观测性平台看到每个 Executor 的耗时、输入输出、工具调用记录。如果一切正常你会看到 RouterAgent 输出路由决策OrderAgent 输出订单状态聚合节点把两者合并成最终回复。流式执行用RunStreamingAsync()适合需要边生成边展示的场景。验证时建议先用最简单的单代理工作流跑通再加第二个代理逐步增加复杂度。这样出问题时能快速定位是配置、工具还是编排逻辑的锅。5. 本篇常见错排查401、local proxy failed 与 OAuth实际跑 MAF 时报错集中在几个地方。下面按真实错误信息对照排查。401 Unauthorized最常见。先检查 API Key 是否正确、是否过期、有没有多余空格。再确认 Base URL 是否写成了带路径的形式MAF 的 OpenAI 连接器期望的是 API 根地址。如果密钥没问题检查请求头里的 Authorization 格式是否为Bearer sk-xxx。local proxy failed / connection refused这类错误通常出现在本地开发环境说明请求根本没发出去。检查网络配置、防火墙、以及 Base URL 是否可达。如果你在容器里跑确认容器网络能访问外部端点。注意不要配置任何非官方的网络转发工具直接用标准 HTTPS 请求即可。reading choices 相关报错这通常意味着响应体结构和预期不符。可能是 Model ID 填错了或者模型返回了非标准格式。先用模型对话页面单独验证该 Model ID 能否正常返回再回到 MAF 里排查。如果用的是兼容接口确认返回的 JSON 里有choices字段。OAuth / 认证失败如果你用的是需要 OAuth 的提供商检查 token 获取流程。MAF 的 IChatClient 抽象层对认证方式有约定OAuth 场景下需要确保 token 刷新逻辑正确。用 TaoToken 的 API Key 方式可以绕过这类复杂度直接走 Bearer 认证。工具调用签名不匹配AIFunctionFactory 自动生成 JSON Schema但如果参数类型复杂比如嵌套对象LLM 可能理解偏差。建议工具参数保持扁平用基础类型必要时加描述。排查时记住一个原则先隔离变量。用最小请求验证模型端点再加 Agent再加 Workflow。每加一层就验证一次比一次性搭完再 debug 高效得多。6. 把 MAF 接入你的业务系统跑通最小示例后下一步是把它接入真实业务。MAF 的 AgentSession 提供框架托管的对话状态支持持久化和上下文恢复这对多轮客服场景很关键。AIContextProvider 可以注入外部数据比如把向量检索结果塞进代理上下文实现 RAG 增强。多代理编排模式里Handoff 适合任务需要转交给更专业代理的场景Group Chat 适合多个代理协作讨论Magentic-One 适合动态任务协调。选择哪种取决于你的业务复杂度不必一上来就用最复杂的模式。跨运行时互操作方面MAF 支持 A2A 协议做代理间通信MCP 协议接入工具生态AG-UI 协议对接前端。这意味着你的 .NET 代理可以和 Python 代理协同工作也可以把代理暴露成 MCP 工具供其他系统调用。如果你打算长期做 Agent 开发建议把 Coding Plan 纳入考虑它能提供更稳定的调用配额适合持续集成和自动化测试。而日常调试和模型验证模型对话页面足够轻量。接入文档里有各语言连接器的详细参数说明遇到配置问题可以先查文档再排查。最后给一个实用建议把 Agent 的 Instructions、工具定义、工作流结构都纳入版本控制。MAF 支持声明式 Agent用 YAML 定义配置这样团队协作时变更可追溯部署一致性也有保障。声明式定义和代码分离是 MAF 相比手写编排逻辑的另一个优势。
