AI·系统·创造·人将如何自处

subagent（子代理）

9分钟阅读

一句话定义

Subagent 是在独立 context 里运行的 agent。
主会话把一个侧任务派给它，它自己去读文件、搜信息、跑检查，最后只把结论或摘要带回来。

一句人话: subagent 是“临时派出去干脏活的 worker”，不是一直坐在主桌上的那位。

为什么重要

本 wiki 对 subagent 的核心判断只有一句：

subagent 首先不是功能划分，而是 context 预算管理。

当一个侧任务会把主会话塞满时，subagent 才真正值钱。典型场景是：

  • 需要读很多文件再总结
  • 需要跑一轮专项检查但中间产物不值得留在主对话里
  • 需要只读探索，不想把大量搜索结果和日志塞回主上下文

Anthropic 官方文档和 Boris 的实际用法都指向同一个方向：把会“烧 context”的任务拆出去，让主线保持干净。

技术机制

在 Claude Code 里，subagent 的文件形态和普通 agent 很像，通常也放在：

.claude/agents/<name>.md

真正的区别，不在文件长相，而在运行方式：

  1. 主会话按 description 或显式指令把任务委派给它
  2. 它在自己的 context window 里工作
  3. 它有独立的 system prompt、工具和权限
  4. 它结束后只把结果或 summary 回给主会话

Anthropic 官方对 subagent 的最关键描述可以概括成一句话：

当一个侧任务会把主对话塞满搜索结果、日志或文件内容时，把它交给 subagent，让它在自己的上下文里做完，只带摘要回来。

还有两个容易忽略的机制点：

  • subagent 不会自动继承主会话的 skills，要显式 preload
  • 它可以只给少量工具，或者跑在 worktree 隔离里，缩小破坏半径

最小可跑通例子

最小 subagent 文件可以这样写：

---
name: repo-researcher
description: Read many files and return a concise summary. Use when exploration would flood the main conversation.
tools: Read, Grep, Glob
---
只读，不改文件。
先给结论，再给证据。

然后在主会话里显式委派：

Task(
    description="搜 API",
    prompt="检查 src/ 里所有 auth 相关实现，告诉我当前鉴权流程和明显风险。",
    subagent_type="repo-researcher",
)

执行时，大量读文件和中间推理都留在它自己的上下文里；主会话通常只拿回最后那段总结。

常见误解

  • subagent = agent。不完全对。subagent 不是另一种人格，而是把某个 agent 作为侧 worker 派出去的一种运行方式。
  • subagent 越多越快。不一定。分派、汇总、协调都有成本。Karpathy 的多 agent 失败案例正好提醒了这一点。
  • subagent 能读到主会话脑子里的全部状态。不能。你不显式传过去的上下文，它默认拿不到。
  • 任何步骤都该拆成 subagent。不对。只有当“上下文隔离收益”大于“分派和汇总开销”时，它才划算。

与其他术语的关系

  • [[agent]]：subagent 依然是 agent，只是被独立派出去执行。
  • [[上下文]]：subagent 的核心价值就是把高消耗任务隔离到独立 context 里。
  • [[workflow]]：在 workflow 里，subagent 最适合承接读得多、产物重、但最后只需要一个结论的步骤。
  • [[skill]]：subagent 可以调用 skill，但要注意 skill 不会默认继承到它的上下文里。
  • [[Harness]]：权限、工具、worktree、memory 这些配置决定了 subagent 是安全隔离器还是新的复杂度来源。

延伸阅读

  • [[agent]]
  • [[上下文]]
  • [[workflow]]
  • [[02-基建/平台/claude-code/subagent]]
  • [[02-基建/平台/claude-code/agent-teams]]
  • [[04-系统/03-案例/Karpathy 的 8-agent 实验为什么失败]]

🎬 3 个场景（读者最可能用到的情境）

场景 1 · 大 codebase 检索不污染主对话

写作者让 AI 在一个上千 md 的知识库里找”所有提到 X 概念的条目 + 出处 + 关联判断”。这种任务会读几百个文件。派 subagent 去跑，主会话只收一份结论清单，不被几百条 grep 结果堆死。

场景 2 · 并行跑 3 条思路再合并

散户想让 AI 同时用”技术面 / 基本面 / 情绪面”三个视角审一只股票。三个 subagent 并行，各自独立上下文，最后只把三段结论带回主会话做综合。

场景 3 · 跑专项检查但中间产物不值钱

HR 让 AI 把某个部门 20 份简历过一遍”硬性条件筛查”。读取 + 比对的中间过程根本不用留，只要一个 pass/fail 清单。派 subagent 做脏活，主会话干净。

⚖️ 和最像的邻居比

术语本质区别适用边界
subagent在独立 context 里跑的 agent侧任务会污染主对话时
agent角色定义不限定运行方式
workflow多步骤编排侧任务之上的整条流程
Task toolsubagent 的调用入口（Claude Code）写 Task(...) 显式派遣

🚫 反例（不该这么用）

反例 1 · subagent 再派 subagent 套娃

主会话派出一个 research subagent，这个 subagent 又派出 3 个子 subagent 并行。结果是主会话拿到的摘要是”摘要的摘要的摘要”，关键信息层层丢失。正确做法：一般只下一层；要并行就在主会话里并行派多个同级 subagent。

反例 2 · 什么任务都塞 subagent

“显得专业”，所以每个小问题都派 subagent。结果是分派 + 汇总的开销远大于隔离收益，主会话反而更慢。正确做法：只在”上下文隔离收益 > 分派开销”时才派，比如读得多/产物重/只要结论的任务。

❓ 常见误解

  • 误解 1：“subagent = agent 的子类” → 实际：subagent 是 agent 的一种”运行姿态”（独立 context），不是另一种人格，同一份 agent.md 可以被当 subagent 派出，也可以在主会话直接上场。
  • 误解 2：“subagent 能读到主会话的全部状态” → 实际：你不显式传过去的上下文，它默认拿不到；包括主会话加载过的 skill 也不自动继承。
  • 误解 3：“subagent 越多越快” → 实际：分派/协调/汇总都有成本，4 个以上 subagent 通常出现”协调税 > 并行收益”的拐点。

🧬 历史坐标（最早谁提 · 本质 · 分型 · git）

最早谁提

2025 年 7 月 · Anthropic 在 Claude Code 里正式引入 subagents，用 .claude/agents/<name>.md 落地”独立上下文窗口 + 独立 system prompt + 独立工具权限”的 isolated Claude instance。官方博客：https://claude.com/blog/subagents-in-claude-code

本质（一句话 · 20 字内）

独立上下文窗口里跑的 agent，只把结论带回主会话。

分型 / 演化（2-4 行主线）

  • 早期 · Unix subprocess / actor model 给了”独立执行体”的原型
  • 2023-10 · Microsoft AutoGen 把 multi-agent conversation 做成框架
  • 2025-07 · Claude Code subagents 发布，关键不是多 agent，而是 context 隔离——解决”context pollution”
  • 2025-10+ · 社群 awesome-claude-code-subagents 100+ 专用子代理沉淀

代表 git / 文档

关系图谱

反向链接