Agent Harness 手册

外观

子代理与多智能体编排 ​

子代理（subagent）回答的问题是：当一个任务超出了单个上下文窗口的承载能力，或者包含多个可以同时推进的独立方向时，harness 如何把工作分出去，又不让自己被分出去的工作淹死？

先给出本文的核心命题：子代理的本质是上下文隔离与并行化，是上下文工程的一种空间换时间的手段——而不是"多个 AI 开会"。市面上大量多智能体框架把卖点包装成"模拟一个团队"：产品经理 agent、程序员 agent、测试 agent 围坐讨论。这是用人类组织的隐喻遮蔽了真正的工程变量。真正决定多智能体系统成败的只有三件事：每个 agent 的上下文里有什么、它们之间交换什么、以及谁来为冲突的结论负责。

为什么需要子代理：三个真实动机 ​

剥掉"AI 团队"的叙事，子代理存在的理由可以归约为三条，全部指向同一个稀缺资源——主上下文窗口。

动机一：保护主上下文 ​

这是最朴素也最普遍的理由。一个调研型任务——"搞清楚这个仓库的鉴权模块怎么工作"——可能需要读几十个文件、跑十几条搜索，产生数万 token 的原始材料。如果全部塞进主对话，主 agent 还没到真正干活的阶段，上下文就已经被中间产物占满了，随后触发压缩、丢失早期细节（上下文管理的困境详见上下文工程）。

子代理把这堆中间产物隔离在自己的上下文窗口里：它读完所有文件，只把几百字的结论返回给主 agent。主上下文看到的不是勘探过程，而是勘探报告。这和记忆系统里的压缩是同一个思想——用摘要换空间——只不过压缩发生在代理边界上，而不是会话内部。

动机二：任务分治与关注点分离 ​

一个子代理可以被赋予自己的系统提示、自己的工具子集、甚至自己的（更便宜或更专精的）模型。这让"代码审查"、"测试编写"、"日志分析"这类角色固定、边界清晰的任务可以被封装成可复用的专家单元。注意：这里的价值不在"角色扮演"，而在每个单元携带不同的上下文配置和权限面——审查 agent 可以只给只读工具，这同时是一个权限决策。

动机三：并行探索 ​

单线程 agent 的探索是串行的：查完 A 方向才能查 B 方向。对于宽度优先的任务（"找出 S&P 500 所有科技公司的董事会成员"），串行意味着总耗时等于各方向耗时之和，而且早期方向的选择会路径依赖地污染后续判断。多个子代理并行铺开，每个带着独立上下文独立探索，总耗时约等于最慢的那个方向。Anthropic 的实测（下文详述）表明，这类任务上多智能体架构的收益是压倒性的。

text
┌─────────────────────────── 主 Agent 上下文 ───────────────────────────┐
│  用户任务                                                              │
│  子任务 A 的描述 ──────────────┐                                       │
│  子任务 B 的描述 ──────────┐   │   ← 只进：任务描述（几百 token）        │
│                            ▼   ▼                                       │
│                     ┌────────────┐ ┌────────────┐                      │
│                     │ 子代理 A    │ │ 子代理 B    │  ← 各自独立的上下文    │
│                     │ 独立窗口    │ │ 独立窗口    │    窗口，可并行执行    │
│                     │ 读 20 个   │ │ 跑 15 条   │                      │
│                     │ 文件……     │ │ 搜索……     │                      │
│                     └─────┬──────┘ └─────┬──────┘                      │
│  结论摘要 A ◄─────────────┘              │                             │
│  结论摘要 B ◄────────────────────────────┘   ← 只回：摘要（几百 token）  │
│                                                                        │
│  数万 token 的中间产物留在子代理上下文里，随其结束而丢弃                   │
└────────────────────────────────────────────────────────────────────────┘

看清这张图，就能理解子代理的全部经济学：主上下文是稀缺资产，子代理是消耗品。委托出去的是意图，收回来的是结论，过程就地焚毁。

Claude Code 的子代理机制：委托-返回摘要 ​

Claude Code 的子代理是这一思想最干净的工程实现，值得逐层拆解（机制依据其官方文档，产品层面的完整剖析见 Claude Code 案例）。

独立上下文窗口 ​

每个子代理在一个与主对话完全隔离的上下文窗口中运行。它不继承主对话的历史——没有用户的闲聊、没有之前的工具输出、没有 todo list。它看到的只有：自己的系统提示 + 主 agent 写给它的任务描述。这是隔离的彻底之处，也是隔离的代价所在（后面 Cognition 的批评正中这一点）。

配置即 Markdown ​

子代理不是代码，而是带 YAML frontmatter 的 Markdown 文件，放在项目的 .claude/agents/ 目录下：

yaml
---
name: code-reviewer
description: 资深代码审查专家。在完成一段代码修改后主动使用。
tools: Read, Grep, Glob, Bash
---

你是一位资深代码审查者。收到代码变更后：
1. 检查正确性、安全漏洞与项目规范符合度；
2. 按严重程度组织反馈；
3. 不修改代码，只输出审查意见。

三个设计细节值得注意：

  • description 是路由依据。 主 agent 是否把任务委托给某个子代理，靠的就是匹配任务与这个字段。description 写得含糊，委托就会错乱——这和工具系统里"工具描述决定工具使用率"是同一条规律。
  • tools 字段是权限边界。 子代理可以被限制为只读工具集，harness 层面就堵死了它改文件的可能。隔离的上下文 + 收窄的工具面，让子代理成为天然的权限沙箱。
  • 正文是完整系统提示。 子代理的行为完全由这段提示塑造，它不知道、也不需要知道主对话里发生过什么。

委托-返回摘要的协议 ​

主 agent 通过一个 Task 工具发起委托：传入子代理类型和一段自足的任务描述（"自足"是关键——子代理看不到主对话，任务描述里没写的信息对它不存在）。子代理跑完自己的完整 agent loop 后，只有最终一条消息回到主上下文，中间几十轮工具调用全部留在子代理的窗口里。

这个协议的含义是双面的：

  • 收益：主上下文为一次可能消耗数万 token 的勘探，只支付了"任务描述 + 结论摘要"的成本。
  • 代价：主 agent 对子代理的执行过程完全不可见。摘要错了、漏了、过度乐观了，主 agent 没有原材料去复核——它必须信任一份二手报告。这是所有委托式架构的共同软肋。

Anthropic 的多智能体研究系统：orchestrator-worker 的正面证据 ​

Claude Code 的子代理解决的是"上下文保护"，Anthropic 2025 年 6 月发表的工程博客《How we built our multi-agent research system》则展示了子代理在"并行探索"上的规模化形态——Claude 的 Research 功能背后的架构。

架构：lead agent + 并行 subagents ​

这是一个教科书式的 orchestrator-worker 结构（谱系上对应 Anthropic 在《Building effective agents》中定义的 orchestrator-workers 模式）：

text
        用户查询："找出 X 领域的所有重要公司"
                        │
                        ▼
              ┌───────────────────┐
              │   LeadResearcher   │  ← 制定研究策略，把计划写入
              │   (orchestrator)   │     Memory 防止上下文截断丢失
              └─────────┬─────────┘
        ┌───────────────┼───────────────┐
        ▼               ▼               ▼
  ┌───────────┐   ┌───────────┐   ┌───────────┐
  │ Subagent 1 │   │ Subagent 2 │   │ Subagent 3 │  ← 并行执行，各自
  │ 方向 A 搜索 │   │ 方向 B 搜索 │   │ 方向 C 搜索 │     独立上下文窗口
  └─────┬─────┘   └─────┬─────┘   └─────┬─────┘
        └───────────────┼───────────────┘
                        ▼
              LeadResearcher 汇总发现，
              决定是否需要追加研究（可再开子代理）
                        │
                        ▼
              CitationAgent 核对引用来源 → 最终报告

文章解释了这个架构为什么适合研究任务：搜索的本质是压缩——从海量语料中蒸馏出洞见。子代理各自在大语料的不同切片上并行压缩，把最重要的 token 浓缩后返回给 lead agent。独立上下文还带来关注点分离（不同的工具、提示、探索轨迹），降低了路径依赖。

实测数据：提升巨大，烧钱也巨大 ​

这篇文章的可贵之处在于给出了罕见的量化数据：

  • 性能：以 Claude Opus 4 为 lead agent、Claude Sonnet 4 为 subagents 的多智能体系统，在内部研究评测上比单 agent 的 Opus 4 高出 90.2%。宽度优先型查询（需要同时追踪多个独立方向）收益最大——例如"找出 S&P 500 信息技术板块所有公司的董事会成员"，单 agent 串行搜索慢且漏，多智能体分解后找到了正确答案。
  • 性能来源：在 BrowseComp 评测（考察浏览型 agent 定位难找信息的能力）的分析中，三个因素解释了 95% 的表现方差，其中 token 用量单独解释 80%。多智能体架构的本质作用由此揭晓：它是一台 token 扩展机器——把推理预算分摊到多个并行上下文里，突破单 agent 的窗口与串行限制。
  • 成本：普通 agent 的 token 用量约为聊天交互的 4 倍，多智能体系统约为 15 倍。结论很直白：只有任务价值高到值得为性能付出这个溢价时，多智能体才在经济上成立。

踩过的坑：协调复杂度的爆发 ​

文章同样诚实记录了从原型到生产的教训，每一条都对 harness 设计者有直接价值：

  • 委托必须具体。 早期 lead agent 只会下"研究半导体短缺"这种模糊指令，结果一个子代理去研究 2021 年汽车芯片危机，另外两个重复调查 2025 年供应链——既重叠又留缺口。修法是要求每个子任务带目标、输出格式、工具指引和明确的边界。
  • 努力程度要定标。 早期 agent 会为一个简单查询开出 50 个子代理。修法是在提示里写入显式的努力标定规则：简单事实查询 1 个 agent、3–10 次工具调用；直接对比 2–4 个子代理；复杂研究才上 10 个以上。
  • 并行是免费的性能。 引入两级并行（lead 同时开 3–5 个子代理 + 每个子代理同时调 3 个以上工具）后，复杂查询的研究时间最多缩短 90%。
  • 同步执行是瓶颈。 当时的实现里 lead agent 同步等待每批子代理完成，期间无法纠偏、子代理之间无法协调，整个系统会被最慢的一个阻塞。异步执行是明确的方向，但会引入结果协调、状态一致性和错误传播的新难题。
  • 生产工程的老问题被放大。 长时运行的有状态 agent 需要断点恢复而不是从头重启；非确定性行为必须靠全链路 tracing 才能调试（呼应可观测性）；部署更新不能打断正在运行的 agent，要用彩虹部署（rainbow deployment）逐步切流。

反方观点：Cognition《Don't Build Multi-Agents》 ​

就在 Anthropic 文章发表的同一周（2025 年 6 月），Devin 的开发商 Cognition 发表了立场鲜明的反方文章《Don't Build Multi-Agents》（作者 Walden Yan）。考虑到 Cognition 做的是编程 agent——恰好多智能体最难啃的领域——这篇文章值得认真对待。

两条原则 ​

文章从"长时运行 agent 的可靠性理论"出发，提出 context engineering 的两条原则，并主张默认排除一切违反这两条原则的架构：

原则一：共享上下文，而且要共享完整的 agent 轨迹（trace），不只是消息。 经典反例："造一个 Flappy Bird 克隆"被拆成两个子任务——子代理 1 造"会动的游戏背景"，子代理 2 造"可以上下移动的鸟"。子代理 1 把背景做成了超级马里奥风格，子代理 2 的鸟根本不像游戏素材。最后负责合并的 agent 面对两份各自误解的产物无从下手。你以为把原始任务抄给子代理就能解决，但真实系统里，任务含义是在多轮对话和工具调用中逐步明确的——子代理拿到的静态任务描述，承载不了主对话里沉淀的全部语义。

原则二：行动承载隐式决策，冲突的决策导致坏结果。 即使两个子代理都正确理解了任务，它们各自动手时会做出大量没被规定的隐式选择——这次可能是鸟和背景的视觉风格完全不搭。两个局部正确的 agent，产出一个全局错误的系统。

结论：单线程优先 ​

Cognition 给出的默认架构是单线程线性 agent：上下文连续，任何决策都能被后续步骤看到。上下文溢出是真实约束，但解法应该是压缩与记忆技术（在长任务中维护连续的上下文），而不是把工作切碎分发给互不可见的执行者。

两条原则与子代理机制并不天然冲突

仔细看会发现，Cognition 批评的靶子是"并行分头干活、事后合并产物"的架构，而不是一切形式的委托。一个只读探索、返回摘要的子代理（比如 Claude Code 里"去看看这个模块怎么工作"）不产出需要合并的工件，隐式决策冲突无从谈起。真正危险的是多个子代理并行写入同一系统——代码、设计、配置。判断一个多智能体设计是否踩雷，就检查一件事：子代理的产物需不需要彼此一致？

适用边界：这场争论其实不矛盾 ​

把两篇文章放在一起读，会发现它们各自悄悄限定了论域，而且论域几乎不重叠：

维度Anthropic（多智能体研究系统）Cognition（Don't Build Multi-Agents）
任务类型开放式研究、宽度优先信息搜集编程、构建一个连贯的工件
子代理产物各自独立的信息摘要，汇总即完成需要拼装成同一系统的部件
并行性天然高：方向之间几乎无依赖天然低：部件之间接口耦合
上下文共享需求低：各方向不需要知道彼此发现了什么高：每个决策影响其他部分的解释
结论多智能体性能提升 90.2%，值得 15 倍 token违反两条原则，默认别做

Anthropic 自己也承认这个边界，原文写得很清楚："需要所有 agent 共享相同上下文、或 agent 之间存在大量依赖关系的领域，目前不适合多智能体系统。比如大多数编程任务中真正可并行的部分比研究少得多，而且 LLM agent 还不擅长实时地与其他 agent 协调和委托。"

所以正确的读法不是"Anthropic 说多智能体好，Cognition 说多智能体坏"，而是一条统一的原则：

子代理的收益 = 并行探索的收益 + 上下文隔离的收益 − 协调与上下文断裂的成本。

研究类任务前两项大、第三项小；编程类任务恰好反过来。这也解释了为什么 Anthropic 在 Research 产品里重度使用多智能体，而 Claude Code 的子代理被刻意设计成"隔离探索 + 摘要返回"的保守形态——同一个公司，在不同的任务结构上做了不同的选择。

决策框架：单线程强 agent 还是多智能体 ​

如果你在设计 harness，面对一个具体任务时按下面的顺序问四个问题：

1. 任务能否分解为低耦合的子任务？ 子任务的产物是否需要彼此一致？需要（同一份代码、同一个设计）→ 偏向单线程；不需要（各自独立的事实搜集、独立的代码库区域）→ 可以继续问。

2. 子任务之间需要多少上下文共享？ 完成子任务 B 是否需要知道子任务 A 的执行细节（而不只是结论）？需要 → 单线程，上下文断裂的代价会吃掉并行收益。

3. 单上下文窗口装得下吗？ 装得下且任务不宽 → 单线程，别引入不必要的复杂度（这条与 Anthropic《Building effective agents》"先找能用的最简单方案"的原则一致）。装不下 → 优先考虑压缩与记忆，仍装不下再考虑委托。

4. 任务价值付得起 token 溢价吗？ 多智能体 ~15 倍于聊天的 token 成本是 Anthropic 的实测数字，不是理论估计。日常任务用多智能体编排，大概率是在为组织结构图付电费。

text
                ┌─────────────────────────┐
                │      接到一个复杂任务      │
                └───────────┬─────────────┘
                            ▼
                  子任务产物需要互相一致？
                   （写同一套代码？）
                     │              │
                   是│              │否
                     ▼              ▼
              ┌───────────┐   单窗口装得下？
              │ 单线程     │      │        │
              │ 强 agent   │    是│        │否
              │ + todo/   │      ▼        ▼
              │ 记忆/压缩  │  单线程    子任务只读探索、
              └───────────┘            返回摘要？
                                        │        │
                                      是│        │否（需写同一系统）
                                        ▼        ▼
                                  委托式子代理   高风险区：
                                  （Claude Code  Cognition 警告的
                                   式，低并行）   并行写入架构
                                        │
                                  宽度优先 + 高价值？
                                        ▼
                              orchestrator-worker
                              （Research 式，大规模并行）

一条经验法则

只读委托安全，并行写入危险。 子代理去"看"、"查"、"试"、"评"，然后带着摘要回来——这类用途几乎总是净收益。子代理各自"写"同一份产物的一部分——这类用途必须先回答 Cognition 的两条原则，答不上来就退回单线程。这与规划里的经验法则同源：分解深度超过 todo list 承载能力时，才轮到子代理出场。

与 harness 其他组件的接缝 ​

子代理不是独立组件，它和 harness 的其他部分有几处关键接缝，设计时需要一起考虑：

  • 与 Agent Loop：每个子代理内部跑的是一个完整但通常更受限的 loop（更少的工具、更明确的停止条件）。编排层的 loop 则多了一种新动作：委托与等待。
  • 与上下文工程：子代理是上下文管理的"总量换质量"手段——烧更多总 token，保住主上下文的注意力预算。任务描述怎么写，决定了隔离是保护还是断裂。
  • 与权限：收窄子代理的工具面是成本最低的权限控制。一个只有只读工具的探索子代理，搞砸事情的上限天然低于主 agent。
  • 与记忆系统：Anthropic 的 Research 系统里，lead agent 把研究计划写入 Memory 防止上下文截断丢失——长任务中，跨子代理轮次的连续性仍然要靠外化记忆，子代理解决不了这个问题。
  • 与可观测性：多智能体系统的调试难度随 agent 数量爆炸，"用户报告 agent 没找到明显信息，但我们看不到为什么"是 Anthropic 的亲身经历。没有全链路 tracing，多智能体系统不可维护。

延伸阅读 ​

  • 上下文工程——子代理的隔离与摘要本质上是上下文管理的另一种形态
  • 规划与任务分解——todo list 与子代理的分工边界：分解深度超过两层时该选谁
  • Agent Loop——子代理内部运行的循环结构
  • 工具系统——description 路由与工具描述遵循同一条"描述决定行为"的规律
  • 权限与人机协作——子代理的工具面收窄作为权限沙箱
  • 记忆系统——跨子代理轮次的状态连续性靠什么维持
  • 可观测性——多智能体系统为什么离不开全链路 tracing
  • Claude Code 案例——委托-返回摘要机制的完整产品设计剖析
  • Devin 案例——反方观点提出者的产品实践对照

参考资料 ​