CowAgent 子代理(Sub Agent)类型深度指南:内置类型、自定义模板与上下文隔离机制

原创2026-10-09 21:47:491,330 阅读
文章标签:人工智能AI AgentAgent 框架多智能体工具调用MCP 服务AI 技能Agent 记忆RAG本地部署语音后端桌面应用前端即时通讯

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 秒;
  • 越界或非法值会记录告警并回退到默认值。

还有两个动态性值得注意:

  1. 实时开关:SubagentTool.is_available() 每次调用都重新读取配置(subagent.py),所以关闭子代理后下一轮工具就被移除,无需重启。
  2. 模板每轮重读:模板在每个 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 承载子代理需要却查不到的一切(文件路径、报错文本、已做的决定、不要碰的东西)——它看不到你的对话,你漏掉的就是丢失的。

验证与更多参考

掌握以上内容后,你就能为 CowAgent 定制任意形态的临时工作者:从只读调查、撰写带来源的报告,到覆盖内置类型的专属风格,再到通过 config.json 精确控制并发与超时预算,让主 Agent 的上下文始终专注于它真正该做的事。

登录后查看全文
CowAgent