主从模式与SubAgent设计：为什么子代理本质上是另一种Tool调用

1. 为什么 Multi-Agent 设计里，主从模式正在变成“默认答案”

做 Agent 应用做得越久，越能体会一个趋势：当任务稍微复杂一点，单 Agent 很难稳定把活干完。你给它一个“全知全能”的角色，它要么在长上下文里迷失重点，要么把工具调用链条拉得巨长，最后结果看起来像模像样，细看全是幻觉。这也是我为什么在 Microsoft Agent Framework 的项目里，越来越倾向于用 SubAgent 把任务拆开——不是赶时髦，是被逼的。

1.1 主从模式到底解决了什么问题

先说个最简单但最核心的判断：Multi-Agent 不是为了“让多个模型聊天”而存在的，它存在的理由是职责分离。

单 Agent 在面对一条复杂链路时，指令越长，冲突越多。比如让同一个 Agent 既做行业调研，又做数据分析，还要写总结，它会在这几件事之间来回横跳。你把提示词写得再详细，也很难保证每一次输出的格式和深度都一致。而主从模式（master-subagent）等于在最外层放一个“调度大脑”，让子 Agent 各自只做一件事。主控 Agent 负责判断“这件事该找谁”，子 Agent 负责“把这件事做透”。

把任务拆给子 Agent 后，还有两个隐性收益：

• 上下文长度被摊薄了。子 Agent 只需要接收与自身任务相关的上下文，不需要把整段历史都背在身上。
• 失败影响被隔离了。某一路子 Agent 跑偏，主控 Agent 可以把它的结果打回重做，而不是整条链路从头再来。

在 Microsoft Agent Framework 这样的框架里，实现主从模式并不复杂。真正让人容易绕晕的，是下面这个问题：SubAgent 和最常见的 Tool 函数调用，到底应该怎么分？

1.2 子 Agent 不是“再开一个聊天窗口”

很多人在刚上手时会犯一个理解性错误：把 SubAgent 当成“嵌套聊天框”。主 Agent 问一句，子 Agent 回答一句，再把回答拿回来拼进主对话。这种方式不是不行，但在真实项目里你会很快发现，它会出现三个问题：

1. 缺少明确的输入输出边界。主 Agent 不知道子 Agent 需要什么格式的输入，也不知道返回的结果可信度如何。
2. 上下文越滚越大。每次子 Agent 的完整对话记录都被塞回主线程，主 Agent 的上下文快速膨胀。
3. 框架没法替你兜底。一旦子 Agent 调用链比较深，错误和 token 消耗都会翻倍。

如果你把 SubAgent 当成一种调用单元，而不再是一个“聊天对象”，问题会瞬间清晰很多。这也是目前社区里讨论最多的观点：本质上就是把 SubAgent 视作另一种 Tool，用同一套接口去注册、去调用、去接收结果。

把这个心智模型理清了，后面搭什么架构都顺。

2. 看透本质：SubAgent 就是另类 Tool 的调用

做 Agent Framework 相关开发，最难的不是怎么写代码，而是怎么理解 Agent 和 Tool 的边界。官方文档里通常会把 Tool 定义成“可以被模型调用的外部能力”，把 Agent 定义成“具备记忆、规划、工具调用能力的执行体”。听起来像是两种完全不同的东西，但在主从模式下，你完全可以换个视角：

SubAgent 就是一个 Tool，只不过这个 Tool 的执行引擎是一个完整的 Agent。

这个视角不是我发明的，而是很多多 Agent 设计里的通行做法。Microsoft Agent Framework 这类框架在设计底层抽象时，也遵循了类似的逻辑：无论是普通的 Function Call，还是拉起一个 SubAgent，都需要走“给模型暴露调用入口 -> 模型决定何时调用 -> 框架执行并把结果返回给模型”这条闭环。

2.1 从函数签名看它们的共同点

先看一个最普通的工具定义。假设你有一个查天气的函数：

json复制{
  "type": "function",
  "function": {
    "name": "get_weather",
    "description": "查询指定城市的当前天气",
    "parameters": {
      "type": "object",
      "properties": {
        "city": {
          "type": "string",
          "description": "城市名称"
        }
      },
      "required": ["city"]
    }
  }
}

模型在推理时，会看到这样一段 schema。它不需要真正执行 Python 或 C# 代码，只需要产出一次具名参数调用：

json复制{
  "function": "get_weather",
  "arguments": "{\"city\": \"杭州\"}"
}

现在你再来看一个子 Agent 的注册信息，例如一个负责对标分析的子代理：

json复制{
  "type": "subagent",
  "agent": "competitive_analyst",
  "description": "分析竞品的定价、功能与市场定位，返回结构化洞察",
  "input_schema": {
    "type": "object",
    "properties": {
      "product": {
        "type": "string",
        "description": "需要分析的产品名称"
      },
      "competitors": {
        "type": "array",
        "items": { "type": "string" }
      }
    },
    "required": ["product"]
  },
  "output_schema": {
    "type": "object",
    "properties": {
      "summary": { "type": "string" },
      "risk_points": { "type": "array", "items": { "type": "string" } }
    }
  }
}

看到没有？在模型眼里，这两者几乎一模一样。它只需要知道：

• 这个名字代表什么能力
• 什么时候该用
• 调用时需要传什么参数
• 调用后能拿到什么格式的结果

模型不关心你的 tool 是一个 def 函数还是一个带 System Prompt 的 Agent。它对所有可调用的东西一视同仁，都当成“可执行的外部能力”去使用。正因如此，你的框架设计可以把 Tool 和 SubAgent 统一抽象成一个接口。

2.2 框架里的调度抽象：一个简化示例

在实际代码里，Microsoft Agent Framework 或类似 SDK 通常会给 Agent 提供 tools 数组。你可以在里面同时混装普通函数和 SubAgent。下面是一段偏抽象的演示代码，重点展示的是结构，不是某个 SDK 的小版本差异：

typescript复制import { Agent } from "./agent-framework";

// 定义子代理
const analystAgent = new Agent({
  name: "data_analyst",
  instructions: `
    你是一名资深数据分析师。
    输入：一份包含原始数据的 JSON。
    输出：一份包含统计结论、异常值、建议动作的 Markdown 报告。
    不要编造数据，只基于输入完成分析。`,
});

const reportAgent = new Agent({
  name: "report_writer",
  instructions: `
    你是一名商业报告撰写者。
    输入：data_analyst 的结构化分析结论。
    输出：面向高层管理者的完整行业报告。`,
});

// 主控代理：它把两个子代理当作两个可调用工具
const masterAgent = new Agent({
  name: "master",
  instructions: `
    请根据用户问题，先调用 data_analyst 获得数据洞察，
    再调用 report_writer 完成最终报告。
    如果用户问题本身与数据分析无关，则直接回答，不要调用任何代理。`,
  tools: [
    {
      type: "subagent",
      agent: analystAgent,
      description: "调用数据分析子代理，处理原始数据",
    },
    {
      type: "subagent",
      agent: reportAgent,
      description: "调用报告撰写子代理，生成商业报告",
    },
  ],
});

const result = await masterAgent.run("帮我分析这份销售数据，并输出一份周报");

这个例子最核心的地方在于：主 Agent 的 tools 数组里，没有区分“普通工具”和“子代理”。对调度层来说，子代理就是一个执行入口，子代理内部再走一遍自己的 System Prompt、工具调用和回复循环。子代理执行完，框架把最终输出以 tool result 的方式返回给主 Agent。

这一步想通了，整个 Multi-Agent 的架构就变得非常好维护。

2.3 这个抽象带来什么实际好处

把 SubAgent 视为 Tool，最大的实际收益是：它能无缝接入所有原本围绕 Tool 开发的调度、限流、权限和日志机制。

比如你想给一个子代理调用加上“审批流”，如果它是一个独立聊天窗口，审批逻辑得跑到业务系统里单独写。但如果它走的是统一的工具调用入口，你只要在调度层拦一道，校验权限、确认成本、记录调用日志，整条链路非常干净。

还有 error handling。普通函数调用失败后，框架抛异常，Agent 会读到错误信息。子代理如果也走这个模型，它可以返回一个结构化的错误结果，主 Agent 收到后可以决定是否重试、切换策略还是向用户解释。这种容错能力，直接决定了生产环境的稳定性。

此外，子代理的执行结果不会自动污染主线上下文。框架只把最终输出返回回来，不会把子代理内部的思考链、中间工具调用全部塞进去。这个行为就像普通工具只把返回值带回来一样。你在设计时就不容易碰到上下文爆炸的问题。

从工程维护角度讲，你也可以把每个子代理的版本、模型、提示词独立管理。主 Agent 根本不关心某个子代理内部是否换了模型，它只看到那个工具调用仍然存在。版本迭代风险被大大降低。

3. 实战拆解：搭一个能跑通的主从 Multi-Agent 项目

理解了“SubAgent 就是另类 Tool”这个心智模型之后，我建议你直接上手做一个小项目。这里我以“市场调研 + 竞品分析”为例，搭建一个有主控、有分工、能复用、可扩展的 Multi-Agent 应用。

3.1 这个项目的目标是什么

用户输入一句话：“帮我调研一下智能家居市场，重点看看 A 公司和 B 公司的产品差异。”

我希望系统可以自动完成三件事：

1. 把用户的需求拆解成市场调研和竞品分析两个子任务。
2. 分别调用两个子代理，一个处理公开行业资料的摘要，一个做产品层面的对比分析。
3. 主控代理收集两边结果后，合成一份最终结论，并明确指出信息来源和置信度。

这个场景非常适合 SubAgent：它同时具备“跨领域知识检索”和“结构化输出”两个特征，单 Agent 做很容易混，主从模式做起来很自然。

3.2 一个可以落地的代码骨架

下面我给出一个更完整一点的示例。为了不依赖某个具体 SDK 的私有 API，代码里我会用面向接口的写法，注释写明每个关键点在真实框架中对应的方法。你可以把它视为架构标准，再映射到 Microsoft Agent Framework 的具体绑定上：

python复制from dataclasses import dataclass, field
from typing import List, Callable, Dict, Any


@dataclass
class SubAgentSpec:
    name: str
    description: str
    instructions: str
    input_schema: Dict[str, Any]
    output_schema: Dict[str, Any]
    execute: Callable[[Dict[str, Any]], str]


@dataclass
class Orchestrator:
    """主控调度的简化实现"""
    name: str
    instructions: str
    subagents: Dict[str, SubAgentSpec] = field(default_factory=dict)
    fallback_tool: Callable[[str], str] | None = None

    def register(self, spec: SubAgentSpec) -> None:
        self.subagents[spec.name] = spec

    def run(self, user_query: str) -> str:
        # 真实框架中，这里会让主 Agent 决定调用哪一个 subagent。
        # 此处为了演示调度逻辑，用一个简单规则代替。
        first_step = self._decide_first_step(user_query)
        if first_step is None:
            if self.fallback_tool:
                return self.fallback_tool(user_query)
            return "无法处理该问题"

        # 第一步：调用市场研究子代理
        research_input = {"query": user_query, "depth": "medium"}
        research_result = self.subagents["market_researcher"].execute(research_input)

        # 第二步：把研究结果传给竞品分析子代理
        product_input = {
            "context": research_result,
            "target": "A公司 vs B公司",
        }
        analysis_result = self.subagents["competitor_analyst"].execute(product_input)

        # 第三步：在主控里做最终整合，此处简单拼接示意
        return self._compose_final(research_result, analysis_result)

    def _decide_first_step(self, query: str) -> str | None:
        # 实际项目应把该决策交给主 Agent，而不是硬编码规则
        if "市场" in query or "行业" in query:
            return "market_researcher"
        return None

    def _compose_final(self, research: str, analysis: str) -> str:
        return f"【市场洞察】\n{research}\n\n【竞品对比】\n{analysis}"

上面这段代码的抽象粒度不是最高级的，但它足以说明架构思路：主控只有一个，子代理各自封装了内部实现，对外只暴露 schema 和 execute。真实项目里你完全可以把 execute 换成对 Microsoft Agent Framework 中某个子 Agent 的调用。

3.3 子代理之间如何交换数据

你可能已经注意到了，子代理之间的数据交换本身就是有协议的。这与普通函数传参没有区别。这里有一个关键设计建议：每个子代理的输入输出都应该尽量使用结构化 schema，而不是随口说“随便给我段文本就行”。

结构化 schema 带来三个好处：

• 主控 Agent 更容易决定要不要调用某个子代理。
• 子代理自身不需要在长篇大论里提取有效信息。
• 后续你如果要做缓存、评估、审计，结构化数据比自然语言好处理得多。

比如市场研究子代理的输出 schema 可以这样设计：

json复制{
  "market_size": {
    "level": "string",
    "description": "市场规模，例子：百亿级"
  },
  "growth_rate": "string",
  "key_trends": ["string"],
  "source_notes": "string"
}

竞品分析子代理接收的输入就包含这些字段，它没必要再去看完整的对话历史。这个设计模式和函数调用完全一致：函数有输入参数，有返回值，内部逻辑外部不可见。

3.4 什么样的情况需要把子代理包装成 Tool

在做这个项目的过程中，我遇到过一个问题：是直接在主 Agent 的工具列表里挂上两个子代理，还是把“市场研究 + 竞品分析”整体封装成一个更大的工具，只暴露给主 Agent？

这两种方式工作起来都行，区别在于粒度的把握：

• 如果主 Agent 需要独立判断“什么时候做市场研究”“什么时候做竞品分析”，那它应该同时看到两个子代理工具。
• 如果这两个子代理的组合总是被一起调用，很少分开出现，那不如用一个更上层的子代理把它们内部编排好，只对外暴露一个“调研一个行业并输出竞品报告”的工具。

粒度越粗，主 Agent 的决策负担越小，但灵活性也越低。粒度越细，主 Agent 拥有的调度自由度越高，但出错概率也越高。我一般建议采用一个原则：主 Agent 只负责它擅长的判断，不负责理解它不关心的中间过程。 简单说，把子代理的分工设计到业务语义边界清晰为止，不要为了拆而拆。

4. 实际开发中比写代码更值得注意的四个问题

在真实项目里，把 SubAgent 跑通只是第一步。真正耗时间的是调稳定性。下面这些坑，我在不同的 Multi-Agent 项目里都踩过，分享出来帮你少走弯路。

4.1 子代理“自作主张”越权

当你把 SubAgent 视作一种 Tool 后，容易产生一个错觉：只要它是个子代理，它就只会按你给它输入 schema 来处理。模型不是这样的。

子代理有着独立的 System Prompt。它内部的模型也会做“自由发挥”。如果你给它的指令是“根据输入数据输出分析报告”，它有时候会在报告里额外加上建议、加市场预测、加风险提示，这些东西可能是主 Agent 没要求的，甚至可能是它脑补出来的。

解决方案有两个：

1. 做输出约束。在提示词里明确“不要补充输入数据之外的信息”，并在解析时用 schema 校验，不符合结构就重试。
2. 不要把太宽泛的目标交给子代理。子代理越专注，它跑偏的可能性越低。一个只负责“提取关键数据”的子代理，远比一个“分析所有内容”的子代理可靠。

早期我在一个财务分析项目里吃过亏：子代理自己把没有依据的营收增长率写了进去，主代理不知道这是幻觉，直接引用到最终文档里。后来加了强制 JSON Schema 校验和必填字段检查，这类问题才被拦下来。

4.2 上下文污染比想象中更容易发生

很多框架在实现子代理调用时，返回给主 Agent 的内容是整个子代理的回复文本。如果子代理内部也调用了多个工具，那回复文本可能包含大量中间拼接结果。当主 Agent 再把这些文本当成“工具执行结果”继续推理时，它的上下文质量会受影响。

我推荐的实践是，在子代理返回结果给主控之前，先做一步“结果浓缩”。无论是用后处理代码，还是再加一个小模型做摘要，尽量让最终返回内容精炼到主控真正需要的信息维度。

你可以把它理解成项目管理：子代理向主负责人汇报时，不应该把团队里每天的聊天记录全发过去，应该给一份提炼过的状态报告。否则负责人很快就会被无效信息淹没。

4.3 子代理的失败需要显式处理

普通函数抛出异常，你可以用 try-catch 接住。但子代理内部是模型在跑，它的失败经常不是抛异常，而是“回复了一段看似正常但实际没完成任务的内容”。

所以你需要在子代理输出里加一层“质量闸门”。比如：

• 输出缺少必填字段时，让它重新生成一次。
• 输出结果低于某个长度阈值时，标记为失败。
• 输出内容里有明显的默认话术，例如“对不起，我无法完成”时，返回错误码给主控。

不要让主控去猜子代理结果是好是坏。子代理应该显式返回一个 success / failed / needs_more_input 之类的状态。这个状态可以用结构化的字段包在输出里。

4.4 token 消耗失控

SubAgent 会把一次请求拆成多次模型调用，token 消耗往往是单 Agent 模式的几倍。即便 Microsoft Agent Framework 这类框架也做了上下文管理，你仍然要面对一个现实：每次子代理调用，都是一次完整的推理链路。

为了控成本，我会做三件事：

• 在不同执行路径上加缓存。同样的输入不要反复调用子代理。
• 给子代理的 System Prompt 限制输出长度，尤其是中间步骤，不要让它长篇大论。
• 严格控制子代理可以调用的工具。子代理能看到的工具越少，它产生额外调用链的可能性就越低。

成本控制不应该是事后优化，而应该体现在子代理设计阶段。每多一个子代理，就意味着未来每次主任务都可能有一轮额外的推理开销。

5. 什么时候真别用 SubAgent：先想清楚再做选择

最后聊点反直觉的事。虽然这篇内容全程在讲 SubAgent 的好处，但实际工作里我依然会先拦一下：不是所有多步骤任务都需要用 SubAgent。选错架构比不选架构更难受。

5.1 SubAgent 和 Process/Tool 的分界线

建议你先做一个简单判断，逻辑顺序如下：

• 如果步骤是固定的，比如“先检索、再分析、最后写报告”，这本质上是一条确定性流水线。用流程编排（Process）或者普通代码就能实现，完全没必要启用多个 Agent。模型调用的数量少了，稳定性和成本都会更好。
• 如果步骤需要模型自由判断“做不做、怎么拆”，或者每一步的输入输出不可预测，那用 SubAgent 才是加分项。
• 如果只是单个动作需要外部数据，优先用普通 Tool。Tool 的延迟更低，可控性更强。

比如“查天气”这种事，无论嵌套多少层 Agent，最终结果都不如一个直接调用天气 API 的工具来得准确。你用 SubAgent 包一层，只会增加延迟和幻觉概率。SubAgent 的适用场景应该是“无法用一个函数表达，需要模型自主规划并产出复杂结果”的流程块。

5.2 主从模式的边界感如何把握

主从模式并不是银弹。当子代理数量超过一定阈值，主 Agent 的决策列表会变得很长。你可以想象一个工具清单里挂着二十个子代理，每个都有一段描述，主模型在调用时也可能“眼花缭乱”。

有一种改进思路是把子代理分组合并。比如所有跟数据获取相关的子代理合并成一个“research_agent”，所有跟写作相关的子代理合并成一个“writer_agent”。通过控制主 Agent 的可见范围，来降低它的决策复杂度和上下文占用。

另一条思路是使用层级式主从，而不是扁平式主从。某些子代理下面还可以有自己的子代理。这样上层主控永远只面对少数几个“部门负责人”，真正的一线执行细节下沉到下层。副作用是链路变长，定位问题时需要拿到的信息也更多。项目很复杂时才建议这么设计，日常小工具不要堆层级。

5.3 直接给一套选型参考

我自己在做技术选型时，会按这几个条件快速判断：

这个表格不是死的，但它能帮你避免最常见的过度设计。很多时候，开发者把项目做复杂，不是因为业务真的需要，而是因为“Multi-Agent”这个词听起来高级。我在第二个项目里就犯过这个错误，本来五个普通函数就能解决的问题，硬生生拆成了三个子代理，结果效果没有提升，反而多了一堆调试负担。

5.4 最后一条实在建议

如果你所在团队刚开始接触 Agent Framework 这类技术，我建议不要一上来就铺开很多 SubAgent。先把一个主 Agent 和一个子代理跑通，验证“SubAgent 作为 Tool”这一条路径稳定可靠，再逐步加第二个、第三个。每加一个子代理，都要有明确的不可替代理由。

架构设计的核心能力不是做加法，而是知道在什么地方省掉不必要的模型调用。主从模式只有在帮你把复杂任务真正拆清晰时，才会有价值。拆完之后，任何一个子代理如果无法比普通函数表现得更好，那就应该坚决换掉它。

我现在的习惯是，每次搭建 Multi-Agent 系统，都会在子代理的注释里写清楚它的失效场景和不可替代性。这看起来像是多余的文档，但在项目上线半年后回看，通常能帮我避免很多“这个 Agent 到底在干嘛”的灵魂拷问。