Multi-Agent主从模式实践：SubAgent即Tool，用Microsoft Agent Framework构建稳定系统

用 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，拆了反而增加延迟和复杂度。

我建议从三个角度判断：

2. 搭建 Microsoft Agent Framework 基础环境与项目骨架

2.1 运行时准备：版本选择和包引入

Microsoft Agent Framework 目前主流是 .NET 9 和 TypeScript 两套实现。我个人习惯用 .NET，因为团队里后端是 C#，和 MAF 的集成更顺。如果你更熟 Node，TS 版本也能跑，只是有些示例代码更新速度略慢。下面的内容我按 .NET 的写法来，但设计思想完全通用。

先创建项目：

bash复制dotnet new console -n ContentOpsAgent
cd ContentOpsAgent
dotnet add package Microsoft.Agent.Framework

这里多说一句，MAF 的包名和版本迭代很快，如果你在 NuGet 上搜到的包名稍有出入，以官方仓库 README 为准。核心模块大致包括：

• AgentApplication：应用运行时，负责 Agent 调度、消息循环和配置管理。
• ReActAgent / ToolAgent：两种常用 Agent 类型，前者做推理与动作循环，后者用于把一组工具包装成可复用执行单元。
• FunctionTool：把普通 C# 方法包装成 Agent 可以调用的工具。
• ResourceMap：管理外部资源，比如知识库文件、数据库连接等。

2.2 最小可运行的主 Agent 代码是怎么组织的

先写一个最基础的主 Agent，不挂任何子代理，只挂一个普通工具，验证环境能通：

csharp复制using Microsoft.Agent.Framework;
using Microsoft.Agent.Framework.Tools;
using Microsoft.SemanticKernel;

var builder = new AgentApplicationBuilder()
    .WithChatUI()
    .WithModel(new OllamaChatClient("llama3.1"))
    .WithTools(tools =>
    {
        tools.Add(new FunctionTool(
            name: "get_current_time",
            description: "获取当前服务器时间",
            func: () => DateTime.Now.ToString("yyyy-MM-dd HH:mm:ss")));
    });

using var app = builder.Build();
await app.RunAsync();

这段代码干了几件事：创建一个带聊天界面的应用，接入模型，注册一个无参数工具。跑起来之后，你可以在聊天窗口问“现在几点”，它就会调用工具。你能看到工具调用的日志，说明 MAF 的基础链路已经通了。

很多新手会忽略 WithChatUI()，没有它，Agent 只在后台运行，你没法直观地看到调用过程。调试阶段我强烈建议保留这个界面，它能打印模型推理过程中每一步工具调用和消息记录，省去自己看日志的功夫。

2.3 把 SubAgent 注册为工具的第一版代码

环境通了之后，进入正题：怎么把 SubAgent 注册成工具。这里我用一个“内容检索子代理”举例。

csharp复制async Task<string> SearchContentAsync(string query, int topN = 5)
{
    var results = await contentSearchService.SearchAsync(query, topN);
    return string.Join("\n---\n", results.Select(r => $"{r.Title}\n{r.Snippet}"));
}

var searchSubAgent = ToolAgent.Create(
    kernel: kernel,
    instructions: """
        你是内容检索子代理。负责从内部知识库和搜索引擎中查找资料。
        输入是一个查询字符串和可选的返回条数。
        输出必须是一个文本列表，包含标题和摘要。
        如果搜索结果为空，请直接说"没有找到相关资料"，不要编造。
        """,
    tools: new[]
    {
        new FunctionTool(name: "search_content", description: "搜索内部知识库", func: SearchContentAsync),
    });

builder.WithTools(tools =>
{
    tools.Add(searchSubAgent); // 关键：把 SubAgent 当作工具注册
});

从代码看，searchSubAgent 本质上是一个 ToolAgent，它有独立的指令和工具集，但在 builder.WithTools 里，它跟普通 FunctionTool 地位一样。主 Agent 看到的是一个名叫“内容检索子代理”的工具，它会自己拼参数、调用内部搜索工具、整理结果，然后返回给主 Agent。

这就是我在开头说的“SubAgent 是另类的 Tool”。在 MAF 的设计里，这个洞察不是比喻，而是代码层面的现实。

3. SubAgent 的类型划分与典型职责边界

3.1 我常用的三类子代理：检索型、操作型、校验型

SubAgent 不是随便拆的，拆错了反而增加复杂度和不必要的模型调用。根据我这几个项目的经验，比较稳的分类是三种：检索型、操作型、校验型。

检索型子代理负责获取信息，比如查数据库、搜索网页、读文件。它的特点是有明确输入输出，基本不产生副作用，且返回结果要尽量结构化。这一类是最好拆的，也最容易复用。我的“内容检索子代理”就是典型的检索型。

操作型子代理负责执行写操作或状态变更，比如创建文档、发送邮件、更新数据库记录。这类子代理需要特别小心权限设计，通常只暴露最小操作集，并且在指令里加“执行前必须确认参数完整”之类的要求。

校验型子代理负责把质量关卡。比如主 Agent 生成了一份周报，可以先给“校验型子代理”检查格式是否符合规范、数字是否和源数据一致。这样做的好处是让主 Agent 专注于生成，把挑错的任务交给另一个专门角色，两边互相制约，最终输出质量会稳定很多。

三类子代理在一个项目里可以同时存在，但职责必须边界清晰。如果某个子代理既查询又写入，那它就不能算单一职责了，后续维护很容易糊涂。

3.2 子代理的 Toolset 设计：每层只给最小权限

SubAgent 内部可以有自己的工具集，但工具集越精确，Agent 就越不容易跑偏。我见过有人给检索子代理挂了十几个工具，结果它经常在内部绕圈。正确做法是给每个子代理最小且充足的工具集。

拿我的“数据统计子代理”举例，它只挂三个工具：query_orders_summary、query_content_metrics、query_realtime_status。它不需要知道怎么发送邮件，也不需要知道搜索工具。主 Agent 把“查上周订单量”的任务交给它，它只能在这三个函数范围内完成，不可能越权去做别的事。

这种设计还有一层好处：安全。假设未来出现恶意输入，SubAgent 被诱导执行了工具，但它工具集里面根本没有危险操作，损失也被控制在最小范围内。如果你把写操作和读操作放在同一个子代理里，等于又回到了单体 Agent 的权限泥潭。

3.3 SubAgent 与普通 Function Tool 的选用对比

既然 SubAgent 本质上是一种 Tool，那什么时候应该用普通 FunctionTool，什么时候应该用 SubAgent？

我的经验法则：如果一次调用只需要同步查询一个数据源，用普通工具；如果这个任务需要“理解问题、规划步骤、多次调用、处理中间结果”，就需要 SubAgent。普通工具是单步执行，SubAgent 是一个多步推理单元。

比如“根据关键词搜索内容并总结”，普通搜索工具返回的是原始片段，主 Agent 拿到后还要自己做总结，这不难，但会占用主 Agent 的上下文窗口。如果我把“搜索 + 总结”封装成一个 SubAgent，它内部先搜索再调用总结模型，最后只返回一段精炼摘要，主 Agent 拿到的内容短而干净，上下文压力大大减轻。这就是 SubAgent 的核心价值：把内部过程的上下文开销隔离在子代理内部。

另外，SubAgent 还天然适合异步和超时控制。普通 FunctionTool 如果在主 Agent 的 ReAct 循环里运行，一旦耗时太长，整个对话流程都要等着。而 SubAgent 可以作为独立执行单元被调度，配合 MAF 的轮次控制，可以给不同子代理设定不同的超时策略。

4. 实际跑通多轮委托：事件循环、上下文传递与状态隔离

4.1 AgentApplication 如何调度 SubAgent 的轮次

当你把一个 SubAgent 注册为工具后，主 Agent 的推理过程大致是这样：模型根据用户输入生成一个工具调用，这个工具调用的名字指向某个 SubAgent，MAF 运行时接到这个调用后，启动一个子会话，把输入传给 SubAgent 的指令和工具集，让它在独立上下文里运行。SubAgent 跑完，返回一个字符串结果，再作为工具调用的输出交给主 Agent。

这里的关键词是“独立上下文”。主 Agent 和 SubAgent 不共享完整对话历史。SubAgent 只看到它自己的指令、它收到的输入、以及它内部工具返回的数据。这既是隐私设计，也是防止上下文互相污染的关键。

在代码层面，你可以通过事件日志观察这个过程。MAF 的 AgentApplication 会在每次工具调用和子代理执行时产生事件，你可以订阅这些事件来监控：

csharp复制app.OnToolCall += (sender, e) =>
{
    Console.WriteLine($"[ToolCall] {e.ToolName} => {e.Arguments}");
};

app.OnAgentTurn += (sender, e) =>
{
    Console.WriteLine($"[AgentTurn] {e.AgentName} 完成一轮推理");
};

我在实际调试中，就是靠这两类事件搞清楚主 Agent 什么时候发出了对子代理的调用，子代理内部执行了多久，以及最终结果是什么。

4.2 主 Agent 把任务“说清楚”的指令模板设计

SubAgent 之间的连接是否可靠，很大程度上取决于主 Agent 的 Prompt 能不能把任务描述清楚。我踩过很多坑，最后总结出一个实用的指令模板。

主 Agent 的指令至少应该包含三块内容：角色边界、可用子代理清单、调度规则。

text复制你是内容运营主控 Agent。你的职责是理解用户需求，把任务拆解为多个子代理调用，并把最终结果整理成自然语言回复。

可用的子代理如下：
1. content_search_subagent：用于从内部知识库检索资料。
2. data_summary_subagent：用于查询内容数据和业务指标。
3. copy_polish_subagent：用于文案润色和格式排版。
4. fact_check_subagent：用于校验回复中的数字和事实。

调度规则：
- 涉及数据和指标时，必须调用 data_summary_subagent 获取准确数字，不要凭记忆编造。
- 最终回复必须经过 copy_polish_subagent 润色，除非用户明确要求不要润色。
- 如果子代理返回结果为空，明确告诉用户，不要尝试自行推断。
- 所有子代理调用应并行执行，如果任务之间没有依赖关系。

这段指令比最初那个“包打天下”的版本短了不少，但效果更好。因为它不再告诉模型“数据表有哪些字段”“搜索工具怎么用”，这些细节被封装到了子代理自己的指令里。主 Agent 只需要知道“什么时候找谁”，相当于一个项目经理的角色。

4.3 SubAgent 的结果如何回传给主 Agent

SubAgent 的结果回传看起来简单，其实有个容易忽视的细节：返回类型。MAF 官方示例里，SubAgent 通常返回字符串，但字符串的格式会影响主 Agent 的后续判断。

我建议子代理返回结构化文本，而不是自由散漫的句子。例如“数据统计子代理”返回：

text复制指标: 周订单量
时间范围: 2025-06-01 至 2025-06-07
数值: 12890
环比上周: -12.3%
可能原因: 618大促结束后需求回落，主推新品点击率下降

这种格式让主 Agent 一眼看到关键数字和结论。如果返回的是大段自然语言“我查了一下发现上周订单量是12890，比再上一周下降了12.3%，我觉得可能是因为……”主 Agent 解析信息的效率会低很多。

你可以在子代理指令里直接规定输出模板：

text复制输出格式要求：
指标: xxx
时间范围: xxx
数值: xxx
环比: xxx
可能原因: xxx

这样保证了主 Agent 收到的工具结果是稳定可解析的。主 Agent 再基于这个结构化结果生成给用户的自然语言回复。

5. 我在生产环境踩过的坑：并发、超时和“子代理失控”

5.1 子代理被反复调用的死循环问题

刚开始上线时，我遇到一个很诡异的现象：主 Agent 会反复调用同一个子代理，就像陷入死循环一样。日志里显示子代理每次都成功返回，但主 Agent 一直不满意结果，然后再次发起调用。

后来发现问题出在主 Agent 的指令上。它被告知“如果子代理返回结果为空，明确告诉用户”，但实际运行时，子代理返回的结果是空字符串，主 Agent 认为“结果为空”是一个需要解决问题的状态，于是重新调用子代理。子代理再次返回空，主 Agent 再调用……直到触发最大轮次。

解决办法有两个。第一，子代理必须保证永远返回非空字符串，即使是“未找到相关资料”也要写成一段明确文字。第二，在主 Agent 指令中明确写一句“同一个子代理针对同一请求最多调用两次，不要重复调用同一个子代理”。

这类问题只有线上跑过才知道。模型毕竟不是代码，它在自由文本生成中很容易陷入语义上的“不满足感”。你要通过指令限制它的行为，而不是指望它自己学会“知难而退”。

5.2 Token 开销控制：子代理的上下文隔离与裁剪

SubAgent 的上下文隔离能减少主 Agent 的 Token 开销，但如果你不小心，子代理内部的 Token 开销反而会放大。

举个例子，检索型子代理从知识库返回了 20 条文档片段，每条 500 字，它还没做总结就直接把 10000 字返回给主 Agent。主 Agent 拿到一万字后还要再处理一遍，Token 成本立刻失控。正确做法是让检索型子代理先总结，再返回最核心的三到五条，每条控制在 100 字以内。

我在子代理指令里加了硬性约束：

text复制- 搜索结果最多保留 5 条。
- 每条摘要不超过 100 字。
- 必须去除重复内容。
- 只返回与查询最相关的内容。

这样设置之后，单次子代理调用的 Token 消耗下降了 70% 以上。另一个经验是，子代理内部如果有多轮工具调用，每轮之间没必要保留完整历史。MAF 支持通过 MaxTurns 或 ContextWindow 参数限制单个子代理的会话长度。我在数据统计子代理里设置最大轮次为 4，到第 4 轮还没有结果就直接放弃，返回“查询失败，请稍后重试”。

5.3 超时与降级：SubAgent 没回应时主 Agent 怎么办

SubAgent 本身是模型驱动的，它的执行时间比普通工具长，也更不稳定。我在上线初期经常遇到子代理调用超时的情况，尤其是数据统计子代理要查多个数据库接口，偶尔会卡在某个慢查询上。

MAF 中可以为工具调用设置超时，但我建议不只是设全局超时，还要设计降级策略。我的做法是：

1. 给每个 SubAgent 设置独立的超时时间，比如检索型 15 秒，统计型 30 秒。
2. 在主 Agent 指令中添加降级规则：如果某个子代理超时，主 Agent 可以换用备选方案，比如调用备用工具，或者直接向用户说明部分数据暂时不可用。
3. 在主 Agent 的可用工具列表里，故意放一个“人工转接工具”，把超时的任务转给人工后续处理。

降级策略的代码并不复杂，核心在于你的指令设计。我会在指令里这样写：

text复制如果 data_summary_subagent 调用失败或超时，不要再反复重试，直接说明“数据查询暂时不可用”，并推荐用户稍后再次询问。

这样比默认的重试机制更稳健，因为模型重试往往是原样再调用一次，除了浪费时间外没有收益。

5.4 可观测性：怎么追踪哪条消息进了哪个子代理

多 Agent 系统调试起来，最大的难点不是写代码，而是搞清楚“为什么模型会这样调用”。我前几周排查一个延迟问题，翻了一上午日志，最后才定位到是某个子代理内部调用了另一个子代理，形成了嵌套链路。如果一开始就追踪好链路，这个问题半小时就能找到。

我在 MAF 的事件订阅里，给每个子代理调用补上了请求 ID 和父会话 ID：

csharp复制app.OnAgentTurn += (sender, e) =>
{
    using var scope = tracer.BeginNestedScope(
        parentId: e.ParentSessionId,
        childId: e.SessionId,
        agentName: e.AgentName);
    logger.LogInformation("Agent {AgentName} 开始执行，输入：{Input}", e.AgentName, e.Input);
};

有了这套追踪之后，你可以清楚看到一条用户请求经过哪些子代理，每个子代理耗时多少，哪一步出了问题。我强烈建议从第一天就加上，否则后期根本没法维护。

6. 从主从模式往外走：后续扩展和几个设计原则

6.1 更复杂拓扑的路线图

主从模式不是 Multi-Agent 的终点，但它是最容易掌控的起点。当你把 SubAgent 作为工具这套思路用顺之后，可以向两个方向扩展。

一是层级嵌套。主 Agent 下面是中层子代理，中层子代理再挂自己的子代理。比如数据统计子代理内部，可以再拆一个“订单数据子代理”和一个“内容数据子代理”。这种结构在刚开始不用做，但当你发现某个 SubAgent 的指令又开始膨胀时，就该考虑递归拆分了。

二是动态发现与注册。目前的子代理是静态注册的，主 Agent 启动时就知道有哪些子代理可用。如果系统很大，可以考虑让子代理通过配置中心动态注册，主 Agent 在每次请求时拉取最新的子代理清单。这在微服务化的 Agent 架构里是自然演进方向。

有一些研究者还提出了基于强化学习的多智能体协作机制，比如用交互奖励或贝叶斯动作解码来动态决定智能体之间的通信策略。这些方向在学术上很有意思，但在工程上可靠性还不高，我建议业务项目先不要碰。主从模式的确定性已经足够撑起大部分场景。

6.2 我沉淀下来的判断清单

最后分享几个设计原则，算是我做这个项目几个月以来沉淀出来的检查清单：

1. 先能用单体跑通业务，再拆 SubAgent。不要一上来就设计一个复杂的多级模型编排，你会被调试淹没。
2. 每个 SubAgent 必须能独立测试。我给每个子代理都写了一个命令行入口，输入一段文本，看输出是否符合预期。这样后续集成时，问题很容易定位到具体模块。
3. 子代理指令里必须有输出格式要求。没有格式约束的子代理，返回结果会让你在主 Agent 里花大量精力做信息提取。
4. 权限最小化。子代理的工具集越小，越安全，也越不容易跑偏。
5. 所有子代理调用必须可观测。请求 ID、主从会话链路、耗时，缺一不可。

我在实际使用中发现，把 SubAgent 当作“另类 Tool”来思考，是非常高效的心理模型。它不仅降低了主 Agent 的复杂度，也让整个系统更像一组可插拔的服务，而不是一堆模型的混乱对话。后面如果再扩展新的子代理，只需要写指令、挂工具、注册到主 Agent，代码复用率很高。

这套方案现在支撑着我们内容运营侧的周报生成、数据归因分析和文案优化三个场景，整体运行稳定。如果你也在折腾 Multi-Agent，建议从主从模式开始，先把一个 SubAgent 跑顺，再谈更复杂的拓扑。