CowAgent 子代理(Sub Agent)类型深度指南:内置类型、自定义模板与上下文隔离机制
CowAgent 子代理(Sub Agent)类型深度指南:内置类型、自定义模板与上下文隔离机制
CowAgent 内置的 Sub Agent(子代理)机制允许主 Agent 把一个独立任务委托给一个"临时帮手":它在自己的上下文窗口里工作,只回传一份结论,沿途读取、运行、产生的所有中间内容都不会污染主 Agent 的上下文。本文以仓库中随附的 子代理类型指南 为核心,完整讲解两种内置类型、如何用 Markdown 文件定义自己的类型、frontmatter 字段、工具白名单与禁用工具,以及 config.json 中的开关和限额,并深入对应源码与测试验证每个结论,帮助你真正掌握 CowAgent 的子代理定制与调优。
什么是 Sub Agent:多一双手,而不是第二个 Agent
Sub Agent 是主 Agent 的"额外一双手"。它拿到一个任务,在自己的上下文里工作,最后回报一个答案——途中它读过、跑过的所有内容都会被丢弃,而不是灌进主 Agent 的上下文窗口。这在长对话场景中意义重大:研究类、采集类任务往往产生大量中间输出,而真正有用的只有结论,用子代理可以显著节省 token 并保持主模型的注意力。
需要特别强调:Sub Agent 不是第二个 Agent。从源码看,它没有自己的 IM 账号、没有自己的工作区、没有自己的记忆,生命周期只存在于任务期间。在 agent/subagent/runner.py 中,子代理被构造为"父 Agent 的一个兄弟"(sibling),共享模型与工作区,但 memory_manager=None、skip_context_files=True、没有消息历史,注释明确写着"它知道任务,除此之外什么都不知道"。
内置的两种类型
仓库随附两种开箱即用的类型:
| 类型 | 用途 | 工具范围 |
|---|---|---|
general-purpose |
需要"调查 + 行动"的多步工作 | 父 Agent 的全部工具(扣除禁用清单) |
explore |
只读调查:查找、搜索、收集事实 | 只读工具集 |
从 agent/subagent/templates.py 可以看到两者的定义:
general-purpose的 description 是"既需要调查又需要行动的多步工作:搜索、读取、运行命令、写文件。当你只知道目标、不知道要多少步时使用"。它的工具列表默认为["*"],即继承父 Agent 的一切(扣除禁用清单)。explore的 description 是"只读调查:找文件、搜代码或文档、从网上收集事实。当答案存在某处、只需要找到、且无需任何修改时使用"。它的工具被限定为READ_ONLY_TOOLS:read、ls、search_files、web_search、web_fetch、vision、memory_search、memory_get、time。
值得注意的是,explore 虽然只读,但仍允许 memory_search 和 memory_get——子代理可以读取共享记忆/知识库来佐证工作,但因为 memory_manager 为 None,它永远无法写入。
用 Markdown 文件添加自己的类型
"往这个目录里丢一个 Markdown 文件"就能定义自己的类型。仓库把指南和示例放在 agent/subagent/assets/,并在启动时把这两个文件种(seed)到每个已启用 Agent 的 subagents/ 目录(app.py 的 _scaffold_subagent_assets():仅当 subagent.enabled 为真时写入,且只写一次、不覆盖用户的修改)。
从示例模板起步
目录中的 example.md.template 是一个完整可用的类型。启用它只需:
cp example.md.template research-report.md # 立即生效,无需重启
.template 后缀正是让它保持"关闭"状态的机制——加载器只读取 .md 文件(见 templates.py 的 entry.endswith(".md") 判断),所以重命名,或复制一份再编辑,你就拥有自己的类型了。
测试 tests/test_subagent.py 专门验证了这一点:把 assets 目录整个复制进工作区时,example.md.template 不会变成类型;只有重命名为 research-report.md 后,才恰好产生一个新类型,且该类型必须带 description、必须解析出非 * 的工具列表、body 非空。
文件格式
每个 .md 文件都会成为一个类型。文件名由你决定(它只作为兜底名称使用),真正起作用的是 frontmatter:
---
name: research-report
description: Dig through many web sources on one topic and come back with a short sourced report.
tools: web_search, web_fetch, read, write
---
You are a research assistant. You are given one topic and you return one report.
...
Frontmatter 字段
| 字段 | 是否必填 | 含义 |
|---|---|---|
name |
必填 | Agent 如何称呼这个类型。缺省时回退到文件名 |
description |
必填 | 何时选择这个类型。见下文——这是最重要的字段 |
tools |
可选 | 逗号分隔的工具名。省略则继承 Agent 的全部工具 |
关键行为与源码印证:
- 覆盖内置类型:复用内置名(
general-purpose、explore)会替换它,这是定制内置类型而非绕开它的方式。加载器以templates<a href="https://link.gitcode.com/i/ffab038a8edfb98000bf41c76d32a437" target="_blank">template.name] = template覆写([templates.py),测试 test_user_template_can_replace_a_builtin 验证了这一点。 README.md被忽略:本指南文件本身不会成为一个类型。加载器显式跳过readme.md(templates.py),测试 test_the_shipped_guide_is_not_offered_as_a_type 也断言了这一点。- 三段缺一不可:
parse_template要求name、description和 body 三者都非空,否则返回None并告警忽略(templates.py)。原因很实在:没有 description,主 Agent 就没有依据路由到这个类型;没有 body,它就没有可执行的指令。
Body:只写"这个类型的不同之处"
Body 是子代理的指令,它会被追加到一个基础提示词之后——基础提示词已经覆盖了工作区路径规则、可用工具和回复语言,所以不要重复这些内容。你只需要写这个类型特有的部分:产出什么、检查什么、绝不能做什么。
另一个重要事实:子代理的 body 不会继承 AGENT.md、RULE.md 或 MEMORY.md。因为它向你的 Agent 汇报、而不是直接面对用户,所以"人格"属于你的 Agent。如果某条规则对工作本身很重要,就在 body 里重述它。从 runner.py 可以看到,子代理构造时传入了 skip_context_files=True,测试 test_skip_context_files_actually_keeps_the_persona_out_of_the_prompt 用真实 Agent 验证:写入 AGENT.md 的 "PIRATE-BOT" 人设不会出现在子代理的系统提示里。
写好 description:写"何时选我",不写"我是谁"
主 Agent 决定使用哪个类型时,只能看到每个类型的 description,看不到别的。所以请把它写成"何时应该触发我",而不是"我是什么":
# 好——描述了应该触发它的场景
description: Read-only investigation across code and docs. Use when the answer exists somewhere and needs finding, and nothing needs to change.
# 差——只是在描述子代理自己,Agent 无法据此匹配
description: A helpful research assistant.
工具说明里对每个类型的展示正是以 - 类型名: description 的形式拼装出来的(agent/tools/subagent/subagent.py),这条描述就是模型路由的全部依据。测试 test_description_lists_the_types_the_model_can_pick 验证了 description 会实时出现在工具描述中,文件删除后立即消失。
工具:禁用清单、技能继承与精确匹配
无论 tools 怎么写都拿不到的工具
以下工具对每个子代理一律禁用,与类型声明的 tools 无关:
subagent、send、scheduler、env_config、evolution_undo、memory_search、memory_get
它们在 templates.py 中定义,注释解释了各自的理由:send 和 scheduler 会以主 Agent 的名义给用户发消息、排任务,超出单个任务的边界;env_config 和 evolution_undo 会修改 Agent 自身的配置;subagent 自身被禁是为了让"全工具"类型也无法无限递归,真正的嵌套深度由 max_depth 控制。测试 test_the_shipped_guide_is_that_documents_the_real_format 专门断言:指南文档中列出的禁用工具集合与源码中的 BLOCKED_TOOLS 完全一致,防止文档与实现脱节。
关于 memory_search / memory_get 有一点需要澄清:上文提到它们可以被 explore 使用(只读共享知识库),但在 templates.py 的 BLOCKED_TOOLS 中它们其实并未被列入禁用——注释说明"记忆工具是有意不封锁的",子代理可以搜索和读取共享知识库来佐证工作,但因为它没有自己的记忆管理器,只能读、不能写。测试 test_template_tool_selection_subtracts_the_blocklist 验证了 "*" 绝不包含禁用清单中的任何工具。
声明了 tools 的类型就得不到技能
一个列出了 tools 的类型,同时也拿不到技能。原因是:技能是端到端编写的工作流,大多数以"写点什么"收尾;把它交给一个工具被削弱的子代理,只会让子代理花好几轮准备一个永远走不到的步骤。因此:
- 需要技能时省略
tools,并在 body 里限定工作范围; - 工具按
allows_all_tools()决定是否继承技能(templates.py)——"全套工具,全套技能;任何更窄的,都没有"。
测试 test_a_type_that_gives_up_tools_gives_up_skills_with_them 验证:explore 类型即使父 Agent 开启了技能,也不会获得 skill_manager;而 general-purpose 会完整继承。
显式列出工具的价值:"构造上"的只读
当某个类型绝不能修改任何东西时,显式列出工具是最可靠的约束:
tools: read, ls, search_files, web_search, web_fetch
上面这个集合按构造(by construction)就无法写入,而不是靠指令约束——即使模型发挥失常也无从写起。
精确匹配与 MCP 工具的边界
工具白名单按精确名称匹配,因此它不会包含 MCP 工具。需要 MCP 工具的类型请省略 tools。这一限制在 templates.py 的 select_tools 中体现:只有 tool.name in self.tools(或全量)才会被选中。
Settings:开关与限额
Sub Agent 默认开启。要在 config.json 中关闭它或调整限额:
"subagent": {
"enabled": true,
"max_depth": 1,
"max_concurrent": 3,
"timeout_seconds": 300
}
| 键 | 默认值 | 含义 |
|---|---|---|
enabled |
true |
Agent 是否获得 subagent 工具 |
max_depth |
1 |
1 表示只有主 Agent 可以派生;子代理不能再派生子代理 |
max_concurrent |
3 |
一次调用最多并行运行多少个子代理 |
timeout_seconds |
300 |
一次调用的总预算,覆盖其中所有并行任务 |
config-template.json 中的默认配置(config-template.json)只写了 enabled 和 max_concurrent,其余使用默认值。源码 runner.py 的 SubagentSettings.from_config() 做了完整的边界校验:
max_depth有效范围1~5(1表示只有主 Agent 可以派生,子代理不能递归派生);max_concurrent有效范围1~10;timeout_seconds有效范围10~3600秒;- 越界或非法值会记录告警并回退到默认值。
还有两个动态性值得注意:
- 实时开关:
SubagentTool.is_available()每次调用都重新读取配置(subagent.py),所以关闭子代理后下一轮工具就被移除,无需重启。 - 模板每轮重读:模板在每个 turn 都会重新读取(
SubagentTool.description属性每次读取都调用load_templates,见 subagent.py),所以新增的.md文件下一条消息就生效——无需重启。测试 test_description_lists_the_types_the_model_can_pick 正是验证了这一点。
源码级实现:一次委派调用背后发生了什么
加载管线
load_templates()(templates.py)从 subagents_dir()(见 common/state_dir.py,与技能共享同一套"共享优先、按 Agent 覆盖"的目录解析)加载用户类型,与内置类型按 name 合并为字典。parse_template() 复用技能系统的 parse_frontmatter(agent/skills/frontmatter.py)解析 YAML frontmatter,tools 字段支持逗号分隔字符串或列表(_parse_tools,templates.py)。
子代理的隔离构造
_build_child()(runner.py)构造一个与父 Agent 共享模型和工作区的"兄弟"Agent,但它:没有记忆管理器、没有 persona 文件、没有消息历史、skip_context_files=True,且 max_steps 只有父 Agent 的一半(至少 1 步)。工具实例通过 copy.copy 为每个并行任务创建私有副本(_private_tools,runner.py),避免并行子代理互相清除对方的 cancel_event、交叉上报进度。测试 test_siblings_do_not_share_tool_instances 和 test_a_sub_agent_gets_half_the_parents_step_budget 分别验证了这两点。
子代理同时继承父 Agent 的 project_dir 与 permission_mode——委派绝不能成为绕过会话权限的途径(runner.py)。
并行与超时
run_tasks()(runner.py)用 ThreadPoolExecutor(max_workers = min(任务数, max_concurrent))并发运行任务,所有任务共享同一个 timeout_seconds 预算。超时任务会被设置 cancel_event 并报告为 timeout,结果列表长度永远等于任务数——主 Agent 能区分"没找到"和"没跑完"。超时后 pool.shutdown(wait=False) 不等待被放弃的工作线程,避免调用本身超支预算。相关测试:test_a_task_that_overruns_its_budget_is_reported_not_dropped、test_a_timed_out_call_returns_without_waiting_for_the_worker。
深度计数通过 ContextVar(_depth)跨线程传递(contextvars.copy_context()),子代理运行在 depth+1,超过 max_depth 时 SubagentTool.execute 直接拒绝并提示"自己做这个任务"(subagent.py)。测试 test_child_runs_one_level_deeper_than_its_parent 验证计数器只存在于工作线程的上下文副本中,不污染调用方。
运行记录与可见性
每次派生都会以独立 run_id 在 identity_scope 下创建一条运行记录(父运行 ID 被记录为 parent_run_id,并标注 subagent_type),状态会回写为 done/cancelled/failed(runner.py),子代理读取的文件也会被收集进结果(subagent.py)。模型拿到的是 JSON 结构化结果,而观察者看到的是格式化 Markdown 结论(format_results,subagent.py);多个子代理并行时每个都有独立卡片,可单独跟踪。
委派工具的参数契约
SubagentTool 的参数(subagent.py)支持单任务 goal / context / subagent_type,也支持 tasks 数组一次并行派发多个任务。goal 必须是对"从未见过这段对话的人"的完整指令;context 承载子代理需要却查不到的一切(文件路径、报错文本、已做的决定、不要碰的东西)——它看不到你的对话,你漏掉的就是丢失的。
验证与更多参考
- 子代理的加载、隔离、守卫与开关逻辑有完整的测试覆盖,见 tests/test_subagent.py;
- 官方功能文档:docs/multi-agent/subagent.mdx 讲解触发时机与继承/隔离边界;docs/tools/subagent.mdx 讲解类型、配置与实现设计;
- 核心实现文件:agent/subagent/templates.py、agent/subagent/runner.py、agent/tools/subagent/subagent.py;
- 目录与播种逻辑:common/state_dir.py、app.py。
掌握以上内容后,你就能为 CowAgent 定制任意形态的临时工作者:从只读调查、撰写带来源的报告,到覆盖内置类型的专属风格,再到通过 config.json 精确控制并发与超时预算,让主 Agent 的上下文始终专注于它真正该做的事。