小可爱小猪chris1. 为什么需要 SubAgent：从单代理到多代理的转变
先聊一个很实际的感受。我最初用 Microsoft Agent Framework（MAF）搭应用时，习惯把所有逻辑塞进一个 Agent 里：写代码让主 Agent 直接生成代码，让它自己检查，自己修正。结果并不理想，不是模型能力不够，而是职责混在一起之后，提示词非常长，上下文很容易被中间步骤污染。一会儿模型忘了最初的格式要求，一会儿又把子问题无限放大，明明一个几百行的小功能，来回折腾好几轮，输出还不稳定。
后来我开始尝试把“子任务”拆给 SubAgent，也就是多代理架构里的“主从模式”，情况立刻不一样了。主 Agent 只负责理解用户需求、拆分任务、汇总结果；真正干活的 Coder、Reviewer、Searcher 都是独立 Agent，按需被主 Agent 唤起。这套思路用在 Microsoft Agent Framework 上尤其顺手，因为它把 Agent、Task、Thread 这些概念都抽象得比较干净，适合做多角色协作。
那 SubAgent 到底解决了什么问题？简单说，它解决了三类事：第一是职责隔离，每个子代理只维护自己领域的上下文和指令，不会互相干扰；第二是提示词工程从“一口大锅”变成“小灶单烧”，复杂需求可以被拆成多个小而专业的任务；第三是可扩展性，你想加一个新的专业角色，只写一个新 Agent 就行，改造主 Agent 的调度逻辑几乎不用动。
这篇文章适合谁？已经跑通过 MAF 单 Agent，想让架构更可控的人；正在做代码生成、文档处理、数据分析这类复杂任务的开发者；还有想理解 Multi-Agent 编排设计，但不想一上来就看源码的人。我会从 MAF 的基础概念开始讲，再落到一个可运行的 SubAgent 协作案例上，最后把容易踩的坑都列出来。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 认识 Microsoft Agent Framework 中的基础编排概念
2.1 Agent 不再只是“聊天封装”这么简单
MAF 底层把 Agent 抽象成了可执行单元，简单理解就是：Agent 是一个接收任务、内部调用模型和工具、最终产出结果的对象。这个抽象和以前我写“把 API key 和 system prompt 塞进函数里”完全不同，官方把 Agent 本身的运行生命周期、消息传递、终止条件都管了起来。
在实际代码里，常用的是 AgentBase 这个基类，你只需要在里面定义自己的处理逻辑，比如重写运行方法或者用声明式的方式配置模型。我最欣赏的设计是它引入了 Task 和 AgentThread，这个组合对应到生活里就是“需求和会话”：Task 描述你要 Agent 完成什么目标，AgentThread 负责实际跑一轮对话循环，管理模型调用、工具调用、终止判断这些繁琐过程。
python复制from microsoft.agent_framework.core import AgentBase
class ReportAgent(AgentBase):
def __init__(self, name: str):
super().__init__(name=name, system_message="你负责生成结构化报告")
async def run(self, task_description: str) -> str:
# 这里的执行细节可以自行封装
return await self._invoke_model(task_description)
这样说可能比较抽象，换个角度来看：传统代码里，如果你想让模型“先思考再调用工具再总结”，每个环节都要自己写状态机；用 MAF 之后，你告诉 AgentThread 用哪个 Agent 去完成哪个 Task，剩下的模型上下文组装、工具结果回填、是否还需要继续执行，由框架来承担。你可以把它当成一个更聪明的“for 循环”，而 Agent 就是循环体。
2.2 两种工作方式：声明式配置与代码优先
MAF 经常让人困惑的一点是它提供了两种使用路径。一种偏声明式，你可以在配置文件里定义 Agent 的模型、参数、工具，然后通过框架加载；另一种是纯代码方式，你直接实例化 Agent，用代码把编排逻辑写清楚。两种没有绝对优劣，主要看场景。
声明式的好处是变更快、复制简单，比较适合“Agent 角色相对固定”的团队协作场景。你定义一个 Coder Agent、一个 Reviewer Agent，把它们的提示词写在 yaml 或 json 里，其他人不需要读懂代码也能改角色设定。代码优先则适合需要动态生成 Agent 的场景，比如根据外部输入决定要不要增加一个额外的质检 Agent。
我个人的建议是：核心业务不建议全走声明式。因为 SubAgent 之间往往需要共享一些变量或做条件判断，纯声明式表达起来很别扭。比较好的折中是主调度用代码写清楚，角色配置抽成常量或配置文件，两头都不耽误。
2.3 Multi-Agent 与 SubAgent 的层级关系
做 Multi-Agent 时，系统里的结构不一定是一堆扁平化的 Agent 互相聊天。无约束的对等 Agent 群在真实项目里非常难控制，因为每个 Agent 都能看到别人的消息，为了