s04 子智能体：Subagent - Harness Engineering - 后端

# 三行速读

子智能体的本质不是并发，而是上下文隔离。
父级负责主目标，子级负责支线探索，回流的是摘要不是全量噪音。
这章在给后续多智能体能力打 “信息边界” 地基。

# 先修知识

已掌握 s03 的主线推进思维。
理解 “消息历史越长，模型注意力越分散” 的现实。

# 读完后你应该能做到（可检验清单）

解释 fresh context 为什么能提升主线稳定性。
设计一个适合委派给 subagent 的支线任务。
比较 “父级直做” 和 “子级委派” 的上下文体积差异。

# 本篇要解决什么

多步骤任务里，经常有 “支线探索” 会污染主上下文：查资料、跑对比、试错过程全塞进主会话，最后主目标反而看不清。s04 用子智能体解决这个问题。

核心目标：把探索任务隔离到新上下文中，主线程只接收摘要结果。

# 用一个类比先理解

把主 Agent 当项目经理，子 Agent 当临时调研员：

经理下发调研问题；
调研员在独立会议室工作；
最后只带 “结论摘要” 回来。

这样经理的主会议记录不会被大量中间细节淹没。

# 为什么这一步必须现在做

因为从这章开始，系统会逐渐并行化。若没有上下文隔离，能力越强、噪音越多。s04 先把隔离边界立住，后续多 Agent 才不会失控。

# 关键代码怎么读

# 1) 子任务从 fresh messages 启动

def run_subagent(prompt: str) -> str:
    sub_messages = [{"role": "user", "content": prompt}]
    for _ in range(30):
        response = client.messages.create(...)
        ...

关键点不是 “再调用一次模型”，而是 “上下文重新开始”。

# 2) 子工具池与父工具池分离

1 2	CHILD_TOOLS = ["bash", "read_file", "write_file", "edit_file"] PARENT_TOOLS = CHILD_TOOLS + ["task"]

教学版故意不让子 Agent 再递归调用 task ，先控制复杂度，避免无穷委派。

# 3) 父级通过 task 路由委派

1
2
3

if block.name == "task":
    prompt = block.input.get("prompt", "")
    output = run_subagent(prompt)

父 loop 不关心子任务内部细节，只关心输入任务和输出结果。

# 4) 子结果以摘要返回

1	return "".join(b.text for b in response.content if hasattr(b, "text")) or "(no summary)"

只回摘要是为了控制主上下文体积与聚焦度。

# 你可以怎么复现

给主 Agent 一个 “编码 + 调研” 混合任务。
让它把调研部分通过 task 下发子 Agent。
观察主上下文是否明显更干净。

# 常见误区

误区 1：把 subagent 当并发线程模型。这里重点是上下文隔离。
误区 2：子任务返回原始日志而非摘要，主上下文仍会膨胀。
误区 3：委派边界不清晰，父子职责混乱。

# 一句话总结

s04 的核心不是 “多开一个 Agent”，而是用上下文隔离保护主目标可见性。

# 补充解读：s04 的关键是 “边界管理”

很多文章讲 subagent 会过度强调并发，其实这章最核心的是：通过 fresh context 防止主线被支线信息淹没。

# A. `AgentTemplate` 提示了后续可配置方向

class AgentTemplate:
    def _parse(self):
        text = self.path.read_text()
        match = re.match(r"^---\\s*\\n(.*?)\\n---\\s*\\n(.*)", text, re.DOTALL)
        ...

这部分在教学里像 “预告片”：后续可以把子代理定义做成外部模板，而不写死在代码里。

# B. 子代理工具池刻意受限

1 2	# Child gets all base tools except task (no recursive spawning) CHILD_TOOLS = [...]

这是非常务实的设计。先把递归委派关掉，可以避免新手阶段出现 “代理套娃” 问题。

# C. 子代理循环也遵循同一 tool_use 模式

for _ in range(30):
    response = client.messages.create(...)
    if response.stop_reason != "tool_use":
        break
    ...

即使是子代理，执行协议仍和父代理一致。这种一致性会让系统更容易维护。

# D. 只把摘要回给父级

1 2	# child context is discarded return "".join(b.text for b in response.content if hasattr(b, "text"))

这句可以直接当设计原则：主上下文保存决策信息，不保存所有中间推理痕迹。

# 进阶练习

在 run_subagent 增加 max_turns 入参，观察子任务稳定性。
给 task 工具加 description 必填校验，提升委派可读性。
对同一任务分别用 “父级直做” 和 “子级委派” 对比上下文体积。

# 你会收获的工程习惯

把探索和决策分层。
保持父子协议一致。
用摘要而不是原始噪音回流主线。

# 统一术语口径（本章）

Subagent ：带独立消息上下文的一次性委派执行单元。
Fresh Context ：子任务从空白消息历史启动的隔离环境。
Summary Return ：子任务仅返回摘要，不回流全部过程。

# 章节衔接（从易到难）

本章解决 “主线与支线的信息隔离”。
下一章 s05 解决 “知识能力如何按需注入而不爆上下文”。

Harness Engineering