SubAgent子智能体架构：上下文隔离的核心实现方案

引言：为什么需要子智能体？

在构建AI Agent的过程中，一个不可回避的问题是上下文膨胀。当Agent与用户对话时间越长，执行的工具调用越多，messages数组就会变得越来越臃肿。每次读文件、跑命令的输入输出都会留在Agent的上下文中，严重影响模型的思维清晰度。

举个例子：当你问Agent"这个项目用什么测试框架"，它可能需要读取五个文件才能得出结论。在没有子智能体的架构下，这五个文件的完整内容都会堆积在主Agent的上下文里，造成极大的冗余。

上下文窗口与注意力稀释的深层问题

大语言模型（LLM）的"上下文窗口"（Context Window）是指模型在单次推理时能够处理的最大token数量。以Claude 3.5为例，其上下文窗口可达200K tokens，GPT-4o约为128K tokens。尽管窗口容量在不断扩大，但上下文膨胀带来的问题并不仅仅是"装不下"——更深层的问题是注意力稀释（Attention Dilution）。研究表明，当上下文过长时，模型对早期关键信息（如System Prompt中的核心指令）的关注度会显著下降，这一现象被称为"Lost in the Middle"效应。在Agent场景中，每次工具调用都会将输入输出追加到messages数组，长时间运行后，模型可能"忘记"最初的任务目标，或在海量中间信息中迷失方向。因此，上下文管理不仅是性能问题，更是Agent可靠性的核心挑战。

这就是SubAgent（子智能体）方案要解决的核心问题——上下文隔离。

SubAgent的架构设计

父Agent与子Agent的分工

SubAgent方案的核心思想可以用"导师与研究生"的关系来类比：

• 父Agent（导师）：负责接收用户问题，将大任务拆分为子任务，分派给子Agent执行，最终只接收任务结果的摘要
• 子Agent（研究生）：接收父Agent分派的具体任务，独立执行工具调用（读写文件、运行命令等），完成后将结果返回给父Agent

关键在于，子Agent执行过程中产生的所有中间信息（比如工具调用的报错、多次尝试的过程）都不会进入父Agent的messages。父Agent收到的仅仅是一段文本摘要，作为普通的tool result返回。

Tool Call机制与messages数组结构

理解SubAgent架构，需要先了解现代LLM的工具调用（Tool Call）机制。在OpenAI和Anthropic的API设计中，messages数组是一个有序的对话历史列表，每条消息包含role（user/assistant/tool）和content字段。当模型决定调用工具时，会生成一条包含tool_use块的assistant消息；工具执行完毕后，结果以tool_result的形式作为新消息追加到数组末尾。这种设计意味着每一次工具调用都会产生至少两条新消息（调用请求+执行结果），而工具的输出内容（如文件全文、命令输出）往往体积庞大。在一个复杂的编程任务中，Agent可能需要连续调用数十次工具，messages数组的token消耗会呈线性甚至指数级增长，这正是SubAgent方案要从架构层面解决的根本问题。

这意味着，即使子Agent跑了30次工具调用，父Agent的上下文依然保持干净。

SubAgent与TodoList、Agent Teams有什么区别？

很多人容易混淆SubAgent与其他Agent模式，下面做一个清晰的对比：

模式	核心目的	特点
TodoList	任务规划	做计划提醒，防止模型跑偏，本质是一个reminder
SubAgent	上下文隔离	独立的messages，防止对话被工具调用污染
Agent Teams	多Agent协作	多个持久性Agent长期存在，并行协作

子Agent的生命周期很短，只在执行任务过程中存在，任务完成后就被销毁。而Agent Teams中的每个Agent都是长期存在、持久性的。

SubAgent的代码实现解析

父子Agent的工具定义差异

实现上，父Agent和子Agent的工具集是不同的：

• 子Agent的工具（childTools）：包括读写文件、运行终端命令等基础工具
• 父Agent的工具（parentTools）：在子Agent工具的基础上，额外增加了一个task工具，用于分派任务

这样设计的巧妙之处在于，父Agent既了解子Agent拥有哪些能力（所有基础工具），又具备"领导能力"（task工具），能够合理地分派任务。

System Prompt的设计策略

两个角色的System Prompt有明确区分：

• 子Agent System Prompt："你是一个编程子智能体，在指定目录下完成父Agent指定的任务，并做摘要返回"
• 父Agent System Prompt："你是一个智能体，在工作目录下可以使用task工具来指派探索和子任务"

System Prompt设计与角色边界的工程意义

System Prompt（系统提示词）是LLM应用工程中最重要的设计决策之一。它在对话开始前注入，定义模型的角色、能力边界、行为准则和输出格式。在多Agent系统中，System Prompt的设计尤为关键——不同角色的Agent必须对自己的职责有清晰的认知，否则容易出现"越权"行为（如子Agent试图做全局规划）或"推诿"行为（如父Agent直接执行本应交给子Agent的细节任务）。从提示工程（Prompt Engineering）的角度看，父Agent的System Prompt需要强调"委托与汇总"的思维模式，而子Agent的System Prompt则需要强调"专注执行与精炼摘要"。这种角色分离的设计哲学，与软件工程中的单一职责原则（Single Responsibility Principle）高度契合，是将工程设计思想迁移到AI系统架构的典型实践。

通过不同的系统提示词，父子Agent各自明确自己的职责边界，避免角色混乱。

核心函数：run_subagent的工作流程

run_subagent函数是整个SubAgent方案的核心，其工作流程如下：

1. 接收父Agent通过task工具传来的prompt（任务指令）
2. 创建独立的submessages数组，与父Agent的messages完全隔离
3. 在一个限制为30轮的循环中执行任务（工具调用、读写文件等）
4. 任务完成后，提取最后一轮的文本块，通过join方法拼接成summary
5. 将summary作为tool result返回给父Agent

中间过程中的报错信息、多次尝试的记录，在子Agent解决问题后就不再需要保留，从而实现了上下文的精简。

循环结构的演进

从单Agent到SubAgent架构，Agent Loop的结构发生了本质变化：

• 单Agent架构：单个Agent的while循环
• SubAgent架构：父Agent的while循环（主循环）+ 子Agent的for循环（限制30轮）

父Agent每次调用task工具，就会触发一次run_subagent函数，创建一个临时的子Agent来执行任务。任务完成后子Agent即被销毁，不会占用父Agent的上下文空间。

当前方案的局限与改进方向

串行执行的性能瓶颈

当前实现存在一个明显的工程局限：子Agent只能串行执行，不支持并行。

具体来说，父Agent每次工具调用只能运行一个子Agent，必须等待该子Agent返回结果后，才能做进一步判断和思考，决定是否继续派发新任务。如果父Agent需要调用两次task，就会串行运行两次subagent。

串行与并行执行的工程权衡

当前SubAgent方案的串行执行限制，本质上是一个并发编程问题在AI Agent领域的映射。在传统软件工程中，串行任务（Sequential Task）意味着任务必须按顺序完成，前一个任务的输出是后一个任务的输入；而并行任务（Parallel Task）则允许多个独立任务同时执行，显著提升吞吐量。将SubAgent改造为并行执行，技术上需要解决几个挑战：首先是任务依赖图的构建，父Agent需要判断哪些子任务之间没有数据依赖，可以并发执行；其次是结果聚合，多个子Agent同时返回结果时，父Agent需要有序地整合这些信息；最后是资源竞争，多个子Agent同时读写同一文件时需要加锁机制。这也是为什么Claude Code、Devin等先进AI编程工具在架构上投入大量工程资源的原因——并行多Agent协作是提升复杂任务处理效率的关键路径。

这在需要同时探索多个方向的场景下效率较低，是后续可以优化为并行执行的方向。

子Agent之间缺乏共享记忆

另一个值得关注的限制是，多个子Agent之间没有共享对话记忆，它们只共享文件系统的读写。这意味着一个子Agent的发现无法直接传递给另一个子Agent，只能通过文件系统间接共享信息。

总结

SubAgent方案的核心价值在于上下文隔离，通过将高噪声的探索任务交给临时创建的子Agent执行，保护父Agent的系统提示和主目标不被稀释。这是一种在工程实践中非常实用的Agent架构模式，也是理解Claude Code等复杂AI编程工具内部机制的重要一环。

从单Agent到父子Agent的演进，本质上是将"一个人干所有事"变成了"领导分派任务、下属独立执行"的协作模式，这也为后续的Agent Teams多智能体并行协作奠定了基础。

核心要点

• SubAgent方案通过上下文隔离解决Agent对话中messages数组膨胀的问题，子Agent的中间过程不会污染父Agent的上下文
• 父Agent额外拥有task工具用于分派任务，子Agent执行完任务后仅返回文本摘要作为tool result
• SubAgent与TodoList（任务规划防跑偏）和Agent Teams（多持久Agent并行协作）有本质区别，SubAgent的生命周期短暂且专注于上下文隔离
• 当前实现的局限在于子Agent只能串行执行且彼此间不共享对话记忆，后续可改进为并行方案
• 整体架构从单Agent的while循环演变为父Agent主循环加子Agent限制30轮的for循环的嵌套结构