谢丽鹿用 Microsoft Agent Framework 做 Multi-Agent 系统，很多人第一反应是让多个 Agent 围在一起自由聊天、互相纠正。这种设计 Demo 很唬人，但一上真实业务就崩：上下文互相污染、Token 消耗失控、排查问题像大海捞针。我跑过几个版本之后，最终稳定下来的是主从模式，也就是 SubAgent 模式，而且从架构实现上看，这本质上就是把 SubAgent 当成一种特殊的 Tool 来回调。这篇就基于 Microsoft Agent Framework 的实践，聊聊我是怎么拆 Agent、怎么写指令、怎么控制并发和超时，以及哪些坑是真的会咬人的。
这套方案适合谁？如果你们团队正在做一个稍复杂的 AI 应用：既要查资料、又要算数据、还要生成格式化文案，一个 Agent 的 Prompt 已经写到三页纸还老是顾此失彼，那 SubAgent 拆分基本是必经之路。如果你只是做一个简单的问答机器人，后面内容可以不用看，单体 Agent 反而更省事。
1. 从“一个 Agent 包打天下”到子代理拆分：我为什么改用主从模式
1.1 单体 Agent 的瓶颈：上下文膨胀和意图纠缠
先说我踩过的单体 Agent 方案。最初我用一个 ReAct 风格的 Agent，把所有技能都塞进同一个指令：既让它理解自然语言，又让它掌握数据库表结构，还要它懂内容平台的排版规范，最后还得能调用搜索 API。表面看功能齐全，实际跑起来全是问题。
第一个问题是上下文膨胀。每一轮对话都要把完整指令、历史消息、搜索摘要、数据库结果全部放进上下文里。用户多聊几句，Token 消耗就指数级上升。尤其当工具返回结果比较长时，模型需要在非常长的上下文里定位关键信息，准确率明显下降。
第二个问题是意图纠缠。用户说一句“帮我查一下最近一周的内容数据，然后润色成周报”，单体 Agent 要先做意图分析，再决定调哪个工具，然后还要处理工具返回的数据，再执行润色。这中间每一步都可能出现偏差：它可能在查数时把润色规则也当成输入，或者在做润色时把数据库字段当成正文内容输出。Prompt 之间互相干扰，排查起来非常痛苦。
第三个问题是权限控制。单体 Agent 一旦拿到全部工具，它就可以自由调用一切东西。你只想让它查一个只读视图，它却可能去调用写接口。虽然可以通过工具描述和 Prompt 约束，但只要模型输出一个错误的工具调用，风险就出来了。把写操作和读操作放在同一个 Agent 里，等于把运维权限交给了模型临场发挥。
1.2 主从模式与“子代理即工具”的设计视角
后来我转向主从模式，效果明显好转。所谓主从模式，就是有一个主 Agent 负责接收用户请求、拆解任务、调度各个 SubAgent，而真正干活的 SubAgent 只负责自己那一小片领域。最初我总把 SubAgent 想象成“另一个对话方”，但实际写代码时发现，更顺手的建模方式是：把 SubAgent 当成一种特殊 Tool 调用。
为什么这样说？因为从主 Agent 的视角看，它不需要关心 SubAgent 内部用了什么模型、调了什么服务、经过了几个步骤。它只需要知道：有一个工具叫“内容检索子代理”，输入是查询条件，输出是搜索结果；有一个工具叫“文案优化子代理”，输入是草稿和风格要求，输出是优化后的文案。主 Agent 要做的事情和调用普通 Function Tool 没有本质区别——它其实只是发起了一次“高级工具调用”。
这个视角带来的好处很直接。一是主 Agent 的指令不用堆砌业务细节，只要描述清楚“什么时候调用哪个子代理”，逻辑简单了，准确率自然上来。二是 SubAgent 可以复用，不同主 Agent 都能挂同一个检索子代理，就像不同流程复用同一个函数。三是方便降级——如果某个子代理超时或报错，我可以像处理工具异常那样处理它，主 Agent 可以换一条路径继续执行，而不是整个对话崩溃。
1.3 什么时候值得引入 SubAgent
不是说所有场景都该拆。我自己的判断标准很简单：如果主 Agent 的指令超过一页纸，或者工具数量超过五个，或者出现了“同一段数据需要被多个不同流程处理”的情况，那就值得拆。如果只是调两三个 API，拆了反而增加延迟和复杂度。
我建议从三个角度判断：
| 判断维度 | 单体 Agent 更合适 | SubAgent 更合适 |
|---|---|---|
| 工具数量 | 少于 5 个 | 超过 5 个，且职责跨越多个领域 |
| 上下文压力 | 工具返回结果短，历史对话短 | 工具返回大量文档、表格，需要长期对话 |
| 权限边界 | 所有工具同一安全级别 | 有只读、写操作、管理操作等不同等级 |
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 搭建 Microsoft Agent Framework 基础环境与项目骨架
2.1 运行时准备：版本选择和包引入
Microsoft Agent Framework 目前主流是 .NET 9 和 TypeScript 两套实现。我个人习惯用 .NET，因为团队里后端是 C#，和 MAF 的集成更顺。如果你更熟 Node，TS 版本也能跑，只是