核心概念：Subagents（子代理）是 Claude Code 中的轻量级子任务执行单元，由主代理（Parent Agent）通过 Agent 工具创建。每个子代理拥有独立的上下文窗口和状态，可以并行或串行执行任务，并在完成后返回结果给主代理。理解子代理的生命周期是构建高效多代理系统的关键。
在 Claude Code 中，主代理通过 Agent 工具 创建子代理。Agent 工具是主代理与子代理通信的核心接口，提供了多种创建和管理子代理的能力。
最基本的创建方式是通过 Agent 工具传入 description 和 prompt 两个核心参数。description 参数描述子代理的任务目标，用于帮助子代理理解上下文；prompt 参数则是具体的指令内容，子代理将根据 prompt 执行具体操作。
子代理的创建模式分为前台和后台两种。前台创建时，主代理会等待子代理完成任务并返回结果，期间主代理处于阻塞状态。后台创建通过设置 run_in_background: true 实现，主代理可以在子代理执行任务的同时继续自己的工作，子代理完成后通过回调或轮询获取结果。
通过 subagent_type 参数可以指定子代理的类型，不同类型的子代理拥有不同的能力和行为模式。例如，可以指定子代理使用不同的模型或具备不同的工具权限。这使得主代理可以根据任务需求灵活选择合适的子代理类型，实现资源的最优配置。
在创建子代理时为其指定一个唯一的名称，主代理可以通过名称识别和通信。命名机制使得主代理可以在多子代理环境中精确控制每个子代理，向特定的子代理发送新任务或查询其状态。
子代理从被创建到最终关闭，经历一系列明确定义的阶段。理解这些阶段有助于精确控制子代理的行为和资源使用。
主代理调用 Agent 工具创建子代理实例。在创建阶段，系统分配子代理所需的资源，包括上下文窗口、工具权限和内存空间。创建成功后，子代理进入初始化阶段。
子代理根据创建时传入的 description 和 prompt 进行初始化配置。在这阶段，子代理加载系统提示词（system prompt），配置可用的工具集，并准备执行环境。初始化完成后，子代理开始执行首次任务。
子代理正在执行具体任务的阶段。子代理可以使用分配给它的各种工具来完成任务，包括文件读写、代码执行、网络请求等。工作阶段可能涉及多轮工具调用，子代理根据中间结果调整执行策略。
子代理完成当前任务后进入空闲状态。在空闲状态下，子代理保持资源占用但不再执行任何操作。主代理可以向空闲子代理发送新任务，将其唤醒并重新进入工作状态。空闲子代理在一定时间无操作后可能被自动回收。
子代理成功完成了所有分配的任务。在完成状态下，结果已经返回给主代理，子代理等待最终的关闭指令。完成状态与空闲状态的区别在于：空闲子代理还可以接收新任务，而完成状态的子代理即将被关闭。
子代理的生命周期终点。在关闭阶段，子代理释放所有占用的资源，关闭上下文窗口，清理临时文件。关闭可以是优雅的（完成所有清理工作后退出）或被强制终止的。
子代理在生命周期中会处于不同的状态，每种状态反映了子代理当前的运行情况。主代理可以通过查询子代理的状态来了解任务进度，并做出相应的调度决策。
| 状态 | 英文名称 | 说明 | 可转换状态 |
|---|---|---|---|
| 运行中 | Running | 子代理正在执行任务，占用 CPU 和上下文资源 | 空闲、已完成、错误 |
| 空闲 | Idle | 等待接收新任务，保留上下文但无活动 | 运行中、已关闭 |
| 已完成 | Completed | 所有任务成功完成，结果已返回 | 已关闭 |
| 错误 | Error | 任务执行过程中发生不可恢复的错误 | 已关闭或重置 |
| 已关闭 | Shutdown | 子代理已停止，资源已释放 | 不可转换（终态） |
子代理正在积极执行任务。在此状态下，子代理消耗计算资源，上下文窗口中的内容不断更新。运行中的子代理无法处理新的外部请求，主代理需要等待其完成当前任务或强制中断。
子代理已完成当前任务，处于待命状态。空闲子代理保留了上下文和状态信息，可以快速响应新任务。设计良好的系统会利用空闲子代理减少创建开销，提高响应速度。
所有任务已成功执行完毕。已完成状态表示子代理的工作完全结束，结果已可用。主代理在确认获取结果后应关闭已完成状态的子代理以释放资源。
子代理在执行任务时遇到无法恢复的错误。错误状态可能由多种原因引起：prompt 格式错误、工具调用失败、上下文窗口溢出或系统资源不足。处于错误状态的子代理需要被重置或关闭。
子代理的生命周期已结束，所有资源已被释放。已关闭是最终状态，不可逆转。如果需要再次执行任务，主代理必须创建一个新的子代理。
子代理的启动和停止是生命周期管理中最频繁的操作。正确的启动和停止策略直接影响系统的稳定性和资源利用效率。
空闲状态的子代理可以通过发送新消息自动唤醒。主代理无需重新创建子代理即可分配新任务，这种方式称为"热唤醒"。唤醒后子代理自动从空闲状态转换为运行中状态，利用已有上下文继续工作。热唤醒的优势在于保留了之前的上下文信息，减少了重新初始化的开销。
优雅关闭是最推荐的方式。主代理向子代理发送 shutdown_request 信号，子代理收到信号后执行清理操作：保存中间结果、关闭打开的文件、释放占用的资源，然后安全退出。优雅关闭确保数据完整性和资源正确释放。
当子代理因为各种原因（如死循环、无限等待、系统故障）无法响应时，主代理可以执行强制停止操作。强制停止会立即终止子代理进程，释放所有资源，但可能导致数据丢失或状态不一致。强制停止应作为最后的兜底手段。
无论以何种方式停止子代理，都必须确保资源被正确释放。资源清理包括：关闭上下文窗口、删除临时文件、释放内存占用、清理 worktree（如使用隔离模式）。建议在应用层面建立子代理资源监控机制，定期检查异常存活的子代理并执行清理。
资源管理是子代理生命周期中容易被忽视但至关重要的环节。合理的资源管理策略决定了系统的稳定性和可扩展性。
每个子代理拥有独立的上下文窗口，窗口大小由模型决定。上下文管理策略包括：合理设置 max_tokens 避免上下文溢出；定期清理不再需要的上下文内容；在子代理进入空闲状态时压缩上下文以节省空间。上下文溢出是子代理错误的常见原因之一，需要在设计时充分考虑。
后台运行的子代理可能产生大量输出文件。需要建立文件管理规范：为每个子代理分配独立的输出目录；使用时间戳或子代理 ID 命名文件；定期清理不再需要的输出文件；设置磁盘空间告警机制。
对于需要修改代码或配置的任务，应使用隔离模式创建独立的 worktree。子代理在独立的 worktree 中操作，不影响主仓库。任务完成后需要及时清理 worktree，包括：删除分支、移除工作目录、清理相关引用。未清理的 worktree 会累积占用磁盘空间。
多个子代理同时运行时需要有效的资源隔离机制。资源隔离包括：文件系统隔离（各自独立的临时目录）、上下文隔离（互不干扰的上下文窗口）、工具权限隔离（限制子代理可使用的工具范围）。良好的资源隔离防止子代理之间的意外干扰，提高系统整体的可靠性。
要点总结：掌握子代理的创建与生命周期管理是构建复杂多代理系统的基石。通过合理使用创建参数、理解生命周期各阶段、精确管理状态转换、规范启动停止操作以及严格执行资源管理策略，可以构建高效、稳定、可扩展的 Claude Code 多代理系统。