用 Microsoft Agent Framework 构建 SubAgent（Multi-Agent）：settings.json 配置与验证

1. 为什么 SubAgent 编排总在 settings.json 上翻车Microsoft Agent FrameworkMAF里的 SubAgent 和 Multi-Agent 协作本质是把一个主 Agent 拆成多个职责单一的执行器再通过 Workflow 把它们串起来。听起来很美好但真正落地时大多数人卡住的地方不是 C# 代码而是settings.json——模型通道、SubAgent 注册、路由边、超时参数全挤在这一个文件里错一个字段就是启动即报错。我见过最常见的三种翻车姿势第一种是把 SubAgent 的id写成中文或带空格WorkflowBuilder 在绑定执行器时直接抛Executor not found第二种是模型通道的endpoint和apiKey分开配结果 SubAgent 调用时拿不到统一凭证报 401第三种是maxSuperSteps没设多智能体互相触发形成死循环进程跑满 CPU 也不退出。这篇就围绕一个可复制的settings.json骨架把 SubAgent 注册、Multi-Agent 调用链、TaoToken 统一 Key 接入、以及验证请求的完整动作走一遍。适合已经在本地工程里跑通单 Agent、想进一步做多智能体编排的开发者。读完之后你应该能拿到一份能直接粘进项目、改改路径就能跑的配置并且知道每一步报错该往哪查。2. TaoToken 前置统一 Key 与 API 通道在配 SubAgent 之前先把模型通道这件事解决掉。MAF 的每个 SubAgent 本质上都要调一次大模型如果每个 SubAgent 各配一套 Keysettings.json会迅速膨胀而且轮换凭证时得改十几个地方。更合理的做法是用一个统一的 API 通道所有 SubAgent 共享同一组endpointapiKey。TaoToken 在这里扮演的就是这个统一通道的角色。它的 API 地址是https://taotoken.net/api兼容 OpenAI 风格的请求格式MAF 的模型客户端可以直接指向它。你只需要在 TaoToken 控制台创建一个 Key然后在settings.json里把这个 Key 配到全局模型节点所有 SubAgent 通过modelRef引用同一个通道即可。具体操作路径是这样的先到控制台创建 API Key地址是https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentsubagent_settings。创建完之后Key 只在创建时完整显示一次记得立刻复制到安全的地方。如果你还没决定用哪个模型可以先到模型对话页面试一下https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentsubagent_settings确认模型能正常响应再写进配置。这里有个细节要注意MAF 的模型客户端在初始化时会读取settings.json里的models节点如果你的 SubAgent 数量多建议把models抽成独立节点用modelRef引用而不是在每个 SubAgent 里内联apiKey。这样轮换 Key 时只改一处。3. 可复制的 settings.json 骨架下面这份骨架是我在实际项目里跑通过的版本字段名和 MAF 的配置约定对齐。你可以直接复制把apiKey换成你自己的路径按项目实际情况调整。{ agentFramework: { version: 1.0, models: { default: { provider: openai-compatible, endpoint: https://taotoken.net/api, apiKey: sk-your-taotoken-key, model: gpt-4o-mini, timeoutSeconds: 60, maxRetries: 2 } }, workflow: { name: subagent-orchestration, startExecutorId: router, maxSuperSteps: 20, checkpointEnabled: true, checkpointStore: local }, executors: [ { id: router, type: SubAgent, modelRef: default, systemPrompt: 你是任务路由根据用户输入决定调用哪个子智能体。, routes: [ { target: researcher, condition: intent research }, { target: coder, condition: intent code } ] }, { id: researcher, type: SubAgent, modelRef: default, systemPrompt: 你是资料检索智能体负责收集和整理信息。, routes: [ { target: summarizer, condition: always } ] }, { id: coder, type: SubAgent, modelRef: default, systemPrompt: 你是代码生成智能体负责输出可运行代码。, routes: [ { target: summarizer, condition: always } ] }, { id: summarizer, type: SubAgent, modelRef: default, systemPrompt: 你是汇总智能体把上游结果整理成最终答复。, routes: [] } ], edges: [ { kind: Direct, source: router, sink: researcher }, { kind: Direct, source: router, sink: coder }, { kind: Direct, source: researcher, sink: summarizer }, { kind: Direct, source: coder, sink: summarizer } ], outputExecutors: [summarizer] } }这份配置里有几个关键点值得展开说。models.default里的endpoint指向 TaoToken 的 API 地址apiKey是你在控制台创建的那把 Key。workflow.maxSuperSteps设成 20是防止 SubAgent 之间互相触发形成无限循环——Multi-Agent 最容易踩的坑就是这个两个 Agent 互相觉得对方该先说话SuperStep 一直涨。checkpointEnabled打开后每个 SuperStep 结束会存一次状态调试时可以从任意检查点重放。executors数组里每个 SubAgent 都有id、type、modelRef、systemPrompt和routes。id必须是英文、数字、连字符组合不能有空格和中文否则 WorkflowBuilder 绑定时会找不到。routes里的condition是路由条件MAF 支持表达式判断always表示无条件转发。edges数组定义的是执行器之间的连接边kind可以是Direct、FanOut、FanIn这里用的都是直连。如果你需要并行分发任务可以把router到researcher和coder的边改成FanOut这样两个 SubAgent 会在同一个 SuperStep 里并行执行汇总节点用FanIn收口。改法是把edges里对应的kind换成FanOut然后在summarizer前面加一条FanIn边。4. 验证请求与成功结果配置写完之后别急着跑完整流程先用一个最小请求验证模型通道和 SubAgent 注册是否正常。MAF 的验证方式通常是写一个控制台入口加载settings.json构建 Workflow然后发一条测试消息。using Microsoft.AgentFramework; using Microsoft.AgentFramework.Workflow; var config WorkflowConfig.LoadFromFile(settings.json); var workflow new WorkflowBuilder(config) .WithName(config.Workflow.Name) .Build(); var run await workflow.StartAsync(帮我查一下 MAF 的 SubAgent 怎么注册); await foreach (var evt in run.OutgoingEvents) { if (evt is ExecutorInvokedEvent invoked) { Console.WriteLine($[调用] {invoked.ExecutorId}); } if (evt is ExecutorCompletedEvent completed) { Console.WriteLine($[完成] {completed.ExecutorId}); } if (evt is WorkflowOutputEvent output) { Console.WriteLine($[输出] {output.Data}); } }跑起来之后如果配置正确你会看到类似这样的输出[调用] router [完成] router [调用] researcher [完成] researcher [调用] summarizer [完成] summarizer [输出] MAF 的 SubAgent 通过 settings.json 的 executors 数组注册...事件顺序反映了 SuperStep 的执行节奏router先跑判断意图后把消息发给researcherresearcher完成后转发给summarizer最后summarizer产出输出。每个ExecutorInvokedEvent和ExecutorCompletedEvent成对出现说明执行器正常进出。如果你只想验证模型通道是否通可以跳过 Workflow直接调一次模型对话接口。在 TaoToken 的模型对话页面发一条消息确认返回正常再回来跑 Workflow。这样能把「模型通道问题」和「Workflow 配置问题」分开排查。5. 本篇常见错排查5.1 Executor not found报错信息通常是Executor xxx not found in workflow bindings。原因有两个一是executors数组里没有这个id二是edges里引用的source或sink拼写和executors里的id不一致。排查动作把edges里所有source和sink的值抄出来和executors的id列表逐个比对大小写敏感。5.2 401 Unauthorized模型调用返回 401说明apiKey无效或没传对。检查models.default.apiKey是否是你从 TaoToken 控制台复制的那把 Key注意前后不要有空格。如果 Key 是在环境变量里确认settings.json里引用环境变量的语法正确。另外确认endpoint是https://taotoken.net/api不要多写或少写路径。5.3 SuperStep 超过上限报错Max super steps exceeded说明 SubAgent 之间形成了循环触发。检查routes里的condition是不是两个 Agent 互相把对方设为无条件转发目标。解决办法是给其中一条路由加上明确的终止条件或者把maxSuperSteps调小让它在有限步内停下来。调试阶段建议设成 10 以内快速暴露循环问题。5.4 输出为空Workflow 跑完了但没有WorkflowOutputEvent通常是outputExecutors没配对。检查outputExecutors数组里的id是不是最终产出结果的那个执行器。如果summarizer的routes是空数组它不会往下转发但需要被标记为输出节点否则结果会被丢弃。5.5 检查点恢复失败如果开了checkpointEnabled但恢复时报Checkpoint not found检查checkpointStore的路径是否可写。local模式下默认存在项目根目录的.checkpoints文件夹如果这个文件夹被清理或权限不足恢复就会失败。调试阶段可以先关掉检查点等流程跑通再打开。6. 下一步从验证到长期编码配置跑通、验证请求返回正常之后你手里就有了一份可复现的 Multi-Agent 骨架。接下来如果要把这套东西用到长期编码或 Agent 场景里建议把模型通道换成 Coding Plan这样在频繁调用 SubAgent 时额度和稳定性更有保障入口在https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentsubagent_settings。如果你在接入过程中遇到 Key 或通道相关的问题可以直接到 API Keys 页面重新生成一把地址是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentsubagent_settings。接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentsubagent_settings里面有完整的请求格式和参数说明。最后提醒一句settings.json里的maxSuperSteps和checkpointEnabled这两个参数在开发阶段和上线阶段的取值应该不一样。开发时把maxSuperSteps设小、检查点打开方便快速定位问题上线时把maxSuperSteps调到合理上限、检查点按需开启避免状态存储拖慢执行。这个细节我在实际项目里踩过配置改一行排查效率差很多。