Subagents 子智能体¶
官方参考：Codex Subagents
1. 一句话理解¶
子智能体是主智能体临时派出去执行专项任务的隔离工作线程。
它适合复杂任务、并行任务和专业分工。
更口语一点说：
- 你当前正在对话的是主智能体。
- 主智能体可以按你的要求创建一个或多个子智能体。
- 每个子智能体专注处理一个子任务。
- 子智能体完成后，把结论汇报回主智能体。
- 主智能体再把多个结果整理成最终答案或后续行动。
2. 它和“新开一个会话”的区别¶
| 对比项 | 子智能体 | 新开一个会话 |
|---|---|---|
| 发起方式 | 主智能体按任务需要创建 | 用户手动新开聊天或线程 |
| 目标 | 服务当前主任务 | 开启一个独立任务 |
| 上下文 | 相对隔离，只围绕子任务展开 | 独立上下文，通常不自动回传 |
| 结果流向 | 汇报给主智能体，由主智能体汇总 | 留在新会话里 |
| 适合场景 | 并行探索、专项审查、分工验证 | 完全不同的话题或长期分支 |
3. 主智能体和子智能体的关系¶
主智能体¶
主智能体负责：
- 理解用户的总体目标。
- 拆分任务。
- 决定是否需要子智能体。
- 汇总子智能体结果。
- 继续执行最终修改、解释或决策。
子智能体¶
子智能体负责：
- 专注处理一个明确子任务。
- 在自己的上下文中读取资料、分析代码或执行检查。
- 把发现、结论、建议返回给主智能体。
子智能体适合做“局部深入”，主智能体适合做“全局编排”。
4. 为什么需要子智能体¶
子智能体主要解决三个问题：
4.1 隔离上下文¶
复杂任务会消耗大量上下文。把某些探索任务交给子智能体，可以避免主会话被大量中间信息塞满。
例如：
- 子智能体读取大量日志后只返回根因摘要。
- 子智能体遍历多个模块后只返回相关文件列表。
- 子智能体审查一批改动后只返回关键问题。
4.2 并行处理¶
多个子智能体可以分别处理不同方向，再由主智能体汇总。
例如：
- 一个看安全问题。
- 一个看性能问题。
- 一个看测试覆盖。
- 一个看文档和使用说明。
4.3 专项角色¶
子智能体可以带有更明确的职责，例如：
- 代码审查者。
- 测试生成者。
- 文档整理者。
- 迁移方案分析者。
- UI 验证者。
这种方式能让任务更像团队协作，而不是一个智能体在所有事情之间来回切换。
5. 适合使用子智能体的场景¶
适合：
- 大型代码库探索。
- 多角度代码审查。
- 多模块问题定位。
- 多步骤功能设计。
- 需要并行验证的任务。
- 需要不同专业视角的任务。
示例：
帮我审查当前分支。请创建 3 个子智能体：
1. 一个只看安全问题
2. 一个只看测试缺口
3. 一个只看性能和并发问题
等它们都完成后，汇总成一份中文 review 报告。
再比如：
请用子智能体并行分析这个项目：
1. 一个负责梳理目录结构
2. 一个负责找启动入口
3. 一个负责找核心业务流程
4. 一个负责总结测试和构建命令
最后由主智能体整理成项目上手文档。
6. 权限和成本¶
官方要点：
- 子智能体会消耗额外 token，因为每个子智能体都有自己的模型工作和工具调用。
- 子智能体继承当前 sandbox policy。
- 自定义 agent 可以配置更细的角色和权限边界。
- Codex 不应随意自动开子智能体；你可以明确要求它使用子智能体。
使用时要注意：
- 子智能体越多，成本越高。
- 子智能体越多，汇总质量越依赖主智能体的编排能力。
- 对敏感仓库或危险操作，仍然要依赖 sandbox、审批和明确边界。
7. 自定义 Agent¶
Codex 支持自定义 agent，用于给特定子智能体固定角色和指令。
常见位置：
~/.codex/agents/ # 个人 agent
.codex/agents/ # 项目 agent
一个简单的 reviewer agent 示例：
name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""
可以把它理解为：把“你希望某类子智能体怎么工作”沉淀成固定配置。
8 和 Skills、MCP 的关系¶
子智能体、Skills、MCP 经常一起使用，但职责不同：
| 能力 | 主要作用 |
|---|---|
| Subagent | 拆分任务、隔离上下文、并行处理 |
| Skill | 提供可复用流程、领域知识和操作规范 |
| MCP | 连接外部工具、数据源和系统 |
组合示例：
主智能体负责整体需求。
子智能体 A 使用 code-review Skill 审查代码。
子智能体 B 通过 MCP 查询线上错误日志。
子智能体 C 使用 docs Skill 整理变更说明。
最后主智能体汇总结果并给出修改方案。
9. 实用提示词模板¶
代码审查¶
请创建多个子智能体并行审查当前改动：
- reviewer-security：只关注安全和权限问题
- reviewer-tests：只关注测试缺口和回归风险
- reviewer-maintainability：只关注可维护性和复杂度
每个子智能体只返回关键发现，最后由主智能体汇总为中文 review。
项目理解¶
请用子智能体并行理解这个项目：
- 一个分析目录结构和模块边界
- 一个分析启动入口和配置加载
- 一个分析核心业务流程
- 一个分析测试、构建和部署命令
最后输出一份新人上手文档。
问题排查¶
请派出子智能体并行排查这个问题：
- 一个检查最近改动
- 一个检查日志和报错
- 一个检查配置和环境差异
- 一个检查相关测试
最后汇总最可能根因和建议修复步骤。