CodeAgent 子代理实战:delegate 派发后台任务,让 AI 同时干多份活

原创2026-11-05 11:40:051,882 阅读

CodeAgent 子代理实战:delegate 派发后台任务,让 AI 同时干多份活

用 CodeAgent 这个终端 AI 编程助手干活,你很快会发现一个瓶颈:主对话一次只能干一件事。长任务一跑,你就只能干等。其实 CodeAgent 内置了子代理(subagent)机制——通过 subagent 工具派生独立的 AI 分身,支持同步、后台、批量并行三种派发模式,主对话不用原地干等,多个任务可以同时推进。这篇文章带你从零搞懂 CodeAgent 子代理:怎么派、怎么等、怎么打断、怎么复用。

CodeAgent 子代理主界面:流式回答框中展示子代理后台任务派发与结果回收的交互过程

为什么需要子代理:主对话的"分身术"

先建立一个直觉:CodeAgent 里的子代理,就是主对话临时派出去帮忙的独立 AI 实例。它有自己的上下文、自己的工具集,干完活只把结果带回来,不共享主对话的聊天记录。

这个设计带来三个直接好处:

  • 🧹 隔离上下文:探索代码、翻日志这类"信息轰炸"型工作交给子代理,主对话只接收结论,不会被几万 token 的中间过程撑爆
  • ⚡ 真并行:多个独立任务同时跑,总耗时从"逐个排队"变成"最慢那个任务的耗时"
  • 🔒 权限隔离:子代理拿不到主对话的全部工具,比如默认的 leaf 角色就调不了 subagent、clarify、memory 这些敏感工具

核心调度逻辑就在 tools/delegate_tool.py,它在工具注册表 tools/registry.py 里注册为 subagent 工具,属于 core 工具集,开箱即用。

三种派发模式:同步、后台、批量

subagent 工具支持三种运行模式,对应日常三类场景:

模式 触发方式 主对话行为 适用场景
同步(默认) 直接调用 原地等子代理干完 需要立即用结果的单任务
异步 background=True 立刻继续,结果稍后送达 耗时的独立任务,不阻塞主流程
批量 tasks=[...] 线程池真并行 多个独立子任务同时推进

同步模式:派出去,原地等

最常用的形态。你描述任务,CodeAgent 派出子代理,主对话暂停等待,子代理返回后主对话接着干活。适合"必须立刻拿到结果才能继续"的环节,比如让 plan 类型的子代理先调研并给出实施计划。

后台模式:发走任务,各干各的

加上 background=True,调用会立刻返回一个任务 ID(del_xxx 格式的 delegation_id),主对话继续处理你的下一条指令,子代理在后台线程独立运行。

后台干完活后,结果会放进一个线程安全的信箱——代码里的 DelegationCompletionQueue(tools/delegate_tool.py)。主对话每轮循环开始时来"取件",把完成通知消化掉;更妙的是 CLI 注册了 idle wake 机制:如果你在后台任务完成时正处于空闲状态,主对话会自动醒来跑一轮,把结果接住,你根本不用盯着。

后台模式有两道安全限制,值得了解:

  1. 工具白名单管控:bg_start、team_spawn、subagent 等有全局副作用的工具会被禁用,防止后台任务再开新的"分叉"
  2. 审批自动拒绝:用户不在场时不能弹审批面板,所有需审批的操作一律拒绝(fail-closed),宁可任务失败也不做越权的事

批量模式:一次派出一个"任务组"

需要同时派多个子代理时,必须用 tasks=[...] 一次批量调用——内部用线程池真并行。工具说明里明确警告:发多个独立的 subagent 调用是串行执行的,会逐个等待,浪费大量时间。

典型用法是并行探索多个模块:一个子代理查认证逻辑,一个查数据库访问层,一个梳理 API 路由,三管齐下,几分钟后主对话同时收到三份报告。

两种角色与内置子代理类型

leaf 与 orchestrator:防"套娃"设计

派发时可以指定角色(role 参数):

  • leaf(默认):执行者,有 terminal、read_file 等干活工具,但不能再往下派人
  • orchestrator:协调者,可以继续派自己的子代理,但受 max_spawn_depth(默认 2 层)限制,防止无限套娃

项目里还内置了一个 coordinator 子代理(agent/builtin_agents/coordinator.md),就是"纯编排者"角色:自己不直接改代码,只把目标拆成可独立执行的工作单元派给 leaf 工人干,并用 scratchpad 涂鸦区做跨 worker 的共享状态。

四个内置类型,各管一摊

CodeAgent 预置了几种专业子代理,定义在 agent/builtin_agents/ 下,每个就是一个带 frontmatter 的 Markdown 文件:

类型 职责 一句话定位
explore 只读探索:读文件、搜代码、抓网页 绝不改任何东西,只报带证据的发现
plan 调研 + 出实施计划 具体到文件、改动点、顺序、风险
verification 对抗性验证 目标是"把它弄坏",验证做完≠做对
coordinator 任务拆解与编排 不写代码,只派活

你也可以在 ~/.codeAgent/agents/*.md 或项目内 ./.codeAgent/agents/*.md 写自定义子代理(声明 name、model、tools、maxTurns 等字段),派发时直接按名字指定 subagent_type。

实战工作流:后台调研 + 前台改码

看一个贴近真实开发节奏的组合拳,体会"同时干多份活"的味道:

第 1 步:后台派调研。 你让 CodeAgent 重构某个模块,它先派一个 background=True 的 explore 子代理去摸清所有调用方,立刻拿到 delegation_id,然后继续和你讨论重构方向。

第 2 步:前台推进主任务。 调研还在后台跑,主对话已经开始写第一版改动。期间你可以随时用其他工具处理别的事。

第 3 步:结果自动回流。 后台子代理完成后结果进信箱,主对话空闲时自动醒来消化——这时你看到的是"调研完成,发现 3 处隐藏调用方,建议……"的完整汇报,而不是干等 10 分钟的进度条。

第 4 步:批量并行验证。 改动完成后,用 tasks=[...] 一次批量派出多个验证子代理:一个跑回归测试、一个做对抗性 verification、一个扫相关文档要不要同步更新。并行收口。

结果默认走摘要模式(summary_only=True),超长输出会由辅助模型压缩成摘要(默认 300 字),保护主对话的上下文预算。深度调研类任务建议把 summary_len 调到 800–1500,避免关键发现被压丢——这个参数就写在 tools/delegate_tool.py 的工具 schema 说明里。

任务失控怎么办:kill 与断点续跑

优雅中断:subagent_kill

后台任务跑偏了?用 subagent_kill 工具(tools/delegate_kill.py)传入 delegation_id 即可。它的实现很克制:协作式取消——按下取消信号旗,子代理在主循环每轮开头检查到信号后优雅退出,并保留已完成的部分结果,而不是粗暴杀线程。

另外,Ctrl+C 中断或退出时,CLI 会调用 cancel_all_subagents() 统一按下所有在跑子代理的取消旗,进程不必等它们跑完,体验很干净。

断点续跑:subagent_resume

子代理的对话记录会持久化到 ~/.codeAgent/.agent-sessions/<agent_id>.jsonl。万一任务中断了(比如上下文超长、会话结束),tools/subagent_resume_tool.py 提供恢复入口:把历史消息读回来,重建子代理从断点继续,往同一个 transcript 文件追加记录。注意恢复的是"对话历史"而非内存运行时状态——对多数任务来说这已经够用。

后台模式注意事项与最佳实践

几条来自工具 schema 和实现细节的实战建议:

  • 🔁 并行必须批量:多个独立任务用 tasks=[...] 一次调用,别发多个独立 subagent 调用(那是串行)
  • ⚠️ 后台任务别指望审批:需要人工批准的操作在后台一律自动拒绝,把"可无审批完成"作为后台任务的验收标准
  • 📦 隔离工作区:多个子代理要同时改文件时,给 isolated_workspace=True,自动创建独立 worktree 目录避免文件冲突,改完再合并
  • ✂️ 调摘要长度:常规任务默认 300 字摘要即可;深度调研、长任务调到 800–1500 字
  • 🚫 深度克制:orchestrator 默认最多派 2 层,别让"代理派代理"的链路超出你的心智模型

小结

子代理是 CodeAgent 从"单线程助手"升级为"多线程工程团队"的关键机制:

  • 同步模式保证结果的即时性,后台模式让主对话不被阻塞,批量模式实现真正的并行加速
  • 结果通过线程安全信箱回流,idle wake 让主对话自动消化,kill 与 resume 让任务可控、可续
  • 内置 explore / plan / verification / coordinator 四种专业分工,配合自定义子代理,基本覆盖"调研 → 计划 → 执行 → 验证"的完整闭环

相关的源码地图,方便想深入的同学按图索骥:

下一篇文章,我们聊聊团队模式(coordinator / worker / 消息总线):当子代理不够用,CodeAgent 还能拉起一整个"AI 团队"。

登录后查看全文
codeAgent