企业官网建设流程全解析

1. 为什么 SubAgent 编排总在 settings.json 上翻车

Microsoft Agent Framework（MAF）里的 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 各配一套 Key，settings.json会迅速膨胀，而且轮换凭证时得改十几个地方。更合理的做法是用一个统一的 API 通道，所有 SubAgent 共享同一组endpoint+apiKey。

TaoToken 在这里扮演的就是这个统一通道的角色。它的 API 地址是https://taotoken.net/api，兼容 OpenAI 风格的请求格式，MAF 的模型客户端可以直接指向它。你只需要在 TaoToken 控制台创建一个 Key，然后在settings.json里把这个 Key 配到全局模型节点，所有 SubAgent 通过modelRef引用同一个通道即可。

具体操作路径是这样的：先到控制台创建 API Key，地址是https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=subagent_settings。创建完之后，Key 只在创建时完整显示一次，记得立刻复制到安全的地方。如果你还没决定用哪个模型，可以先到模型对话页面试一下https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=subagent_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先跑，判断意图后把消息发给researcher，researcher完成后转发给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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=subagent_settings。

如果你在接入过程中遇到 Key 或通道相关的问题，可以直接到 API Keys 页面重新生成一把，地址是https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=subagent_settings。接入文档在https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=subagent_settings，里面有完整的请求格式和参数说明。

最后提醒一句：settings.json里的maxSuperSteps和checkpointEnabled这两个参数，在开发阶段和上线阶段的取值应该不一样。开发时把maxSuperSteps设小、检查点打开，方便快速定位问题；上线时把maxSuperSteps调到合理上限、检查点按需开启，避免状态存储拖慢执行。这个细节我在实际项目里踩过，配置改一行，排查效率差很多。