Sub-Agent Spawning

大型多文件任务会超出主Agent的上下文窗口，并耗尽其推理预算。你需要一种方法，将工作委派给具备独立上下文和工具的专用Agent。

让主Agent生成专注型子Agent，每个子Agent拥有独立的全新context，并行处理可拆分的子任务，完成后汇总结果。

核心要求：调用每个子Agent时必须指定清晰、明确的任务主题，确保可追溯性。空泛或模糊的主题会导致并行工作无法追溯，且难以汇总结果。详情请参考《主题规范》（Subject Hygiene）。

实现方案：

1. 声明式YAML配置

在配置文件中定义子Agent类型，为其指定专属的系统提示词、允许使用的工具以及context窗口：

# subagents/planning.yaml
name: planning
system_prompt: "将复杂任务拆解为步骤..."
tools:
  - list_files
  - read_file
  # 或设置为inherit: all（继承主Agent的所有工具）

# subagents/think.yaml
name: think
system_prompt: "分析并优化推理逻辑..."
tools:
  - read_file
  - search

主Agent通过专用工具调用子Agent：

subagent(agent_name, prompt, files)

该方案支持：

• 虚拟文件隔离：子Agent仅能访问显式传入的文件
• 工具范围控制：子Agent可继承主Agent的全部工具，或仅使用指定子集
• 专属系统提示词：每种类型的子Agent都有预定义的行为模式

2. 动态生成

根据任务需求动态生成子Agent，用于并行任务执行：

# 主Agent创建待办事项列表
files = glob("**/*.md")
batches = chunk(files, 9)

# 为每个批次**并行**生成子Agent
for batch in batches:
    spawn_subagent(
        task="更新Markdown文件的YAML前置元数据",  # 清晰、明确的主题
        files=batch,
        context=instructions
    )
# 所有子Agent并发运行，而非串行

并行委托最佳实践：

• 同时启动独立任务：不要按顺序依次处理A、B、C，需同时启动
• 使用清晰的任务主题：每个子Agent需要具备可追溯的身份标识（参考《主题规范》Subject Hygiene）
• 提前规划汇总逻辑：明确主Agent将如何整合子Agent的输出结果
• 控制子Agent数量在2-4个：从实际有效场景来看，这是最优上限；数量过多会增加协调成本

近期研究进展显示，Agent的状态外部化能力得到提升后，可帮助Agent更准确地识别适合委托的任务，以及如何向子Agent传递必要的context，从而让子Agent委托机制更具实用性。

子代理的应用场景

1. 上下文窗口管理：在子代理中处理大文件，避免污染主上下文

   • 向子代理上传文件
   • 提取特定数据
   • 向主代理返回摘要

2. 并发工作：并行运行多个子代理，完成后汇总结果

   • 减少I/O密集型工作流的耗时
   • 可同时发起网络API调用

3. 代码驱动的LLM调用：将控制权移交LLM进行特定决策

   • 代码工作流调用子代理
   • 子代理基于LLM做出决策
   • 控制权携结果返回至代码

4. 安全隔离：在相互隔离的子代理中分离工具/上下文

   • 外部资源检索与内部访问相互隔离
   • 缩小敏感操作的影响范围

声明式子代理配置

# agents.yaml
subagents:
  planning:
    file: subagents/planning.yaml
    allowed_in:
      - main_agent
      - research_agent

  think:
    file: subagents/think.yaml
    allowed_in:
      - main_agent

虚拟文件传递

# 主代理
result = subagent(
    agent_name="planning",
    prompt="分析这些文件并制定迁移计划",
    files=["file1.ts", "file2.ts", "file3.ts"]
)
# 仅这3个文件对planning子代理可见

递归架构要点

部分实现方案将所有代理都视为子代理，以此实现灵活的组合逻辑，并确保系统内行为的一致性。

优点：

• 上下文隔离：每个子Agent拥有独立干净的上下文窗口（context window）
• 并行执行：通过并发执行降低工作流延迟
• 专业化分工：针对不同任务（规划、思考、分析）设置不同类型的子Agent
• 虚拟文件：精准控制每个子Agent可见的内容范围
• 工具权限范围限定：为保障安全或简化架构，限制子Agent的工具调用能力
• 声明式配置：通过YAML实现可复用的子Agent定义

缺点：

• 额外开销：创建与协调子Agent会增加系统复杂度
• 成本上升：同时运行多个Agent会提升Token消耗
• 协调成本高：主Agent必须跟踪并汇总所有子Agent的执行结果
• 并非必需方案：作者提到“我们常常一开始觉得需要子Agent，后来却发现了更贴合场景的替代方案”
• 延迟可见性差：面向用户的延迟属于“隐性特性”，只有当它引发问题时才会被察觉

子Agent的核心适用场景：

• 上下文窗口管理（如大文件处理场景）
• I/O密集型工作流（如网络API调用场景）
• 需要LLM任务委派的代码驱动型工作流
• 大规模并行需求（如10个及以上并发Agent的场景）