---
url: /antigravity/subagents.md
description: >-
  了解 Antigravity 2.0 异步子 Agent（Asynchronous Subagents）的启动方式、生命周期状态、Agent
  间通信、内置与自定义子 Agent，以及多 Agent 协同体系。
---

# 异步子 Agent (Asynchronous Subagents)

子 Agent（Subagents）是并行化复杂任务并保留主 Agent 上下文的极佳方式。与其串行执行每个步骤，Agent 可以将一些任务（如运行测试或进行广泛的代码库搜索）委派给专门的子 Agent。这种架构释放了父 Agent，使其能够并行继续处理其他任务，并防止其上下文窗口被子 Agent 工作中的琐碎细节所污染。

## 启动子 Agent (Invoking Subagents)

父 Agent 通过调用 `invoke_subagent` 工具来启动一个新的并发会话，该会话具有专属的角色定位和初始 Prompt。

* **工作空间选项**：子 Agent 可以继承与其父级相同的工作空间，也可以创建一个隔离的 Git 工作树（worktree）。
* **上下文隔离**：子 Agent 使用与其父级相同的模型运行，但不继承父级现有的对话历史记录（上下文窗口），以便在一个干净的环境中启动。
* **执行任务**：一旦被调用，子 Agent 就会立即开始执行其任务。父 Agent 可以随时调用多个子 Agent。
* **监控状态**：您可以通过子 Agent 面板点击进入子 Agent 的对话，以直接监控其进度。

## 子 Agent 的生命周期与状态 (Subagent Lifecycle and States)

子 Agent 在后台异步运行，允许父 Agent 委派任务并立即恢复自己的工作。在任何时候，子 Agent 都处于以下三种状态之一：

### 1. 运行中 (Running)

子 Agent 正在积极执行其任务、调用工具并生成响应。

* **取消**：您可以通过点击子 Agent 面板中的 **“Stop Subagent”**（停止子 Agent）按钮来取消运行中的子 Agent。这将立即取消其生成并使子 Agent 过渡到空闲状态。
* **父级控制**：父 Agent 也可以中断子 Agent（通过发送消息）或将其彻底杀掉 (kill)。

### 2. 空闲 (Idle)

子 Agent 已完成其任务，向其父 Agent 发送了包含结果的消息，并停止了执行。

* **重新唤醒**：在收到来自另一个 Agent（不一定是其父级）的消息时，空闲的 Agent 可以被唤醒并返回至“运行中”状态。
* **保留上下文**：被唤醒时，Agent 会保留其先前工作中的所有上下文。

### 3. 已终止 (Killed)

子 Agent 被永久终止，无法再被重新唤醒。

* **清理**：为该子 Agent 生成的任何临时 Git 工作树都会被自动清理。
* **可见性**：您和其他 Agent 仍然可以查看已终止子 Agent 的历史对话日志（transcript.jsonl）。

## Agent 间通信 (Inter-Agent Communication)

Agent 之间通过使用唯一的 Agent ID 发送消息来进行通信。

* **灵活的路由**：Agent 不仅可以与直接的父级或子级进行通信，还可以与 ID 已知的任何其他活动 Agent 进行通信。
* **自动唤醒**：如果空闲的 Agent 收到消息，它会被自动重新唤醒以处理新信息。
* **共享日志**：Agent 之间可以查看彼此的对话日志，从而全面了解协作工作流的细节。

## 内置子 Agent VS 自定义子 Agent

### 内置子 Agent (Built-In Subagents)

Antigravity 预先封装了几个专门的子 Agent：

* **research**：针对代码库研究、导航和探索进行了优化。
* **browser**：操作沙箱化的浏览器以执行网页交互任务（仅通过 `/browser` 斜杠命令调用）。
* **self**：调用端 Agent 的直接克隆版，共享完全相同的系统 Prompt 和工具集。

### 自定义子 Agent (Custom Subagents)

Agent 可以使用 `define_subagent` 工具动态定义自己的自定义子 Agent。

* **配置方式**：定义自定义的系统 Prompt，以及只读、写入（包括运行终端命令）和子 Agent 委派能力的特定工具集。
* **使用范围**：一旦定义，该自定义子 Agent 就可以在当前对话的剩余时间内被重复调用。

## 委派层级与限制 (Delegation Hierarchy and Limits)

子 Agent 也可以调用自己的子 Agent，从而实现多层委派和分层团队结构。

> \[!WARNING]
> **嵌套深度限制**：为防止资源失控枯竭，系统严格限制子 Agent 的最大嵌套深度为 10 层（主 Agent 下方的子 Agent 层数）。

## 权限与配置继承 (Permissions and Configuration Inheritance)

子 Agent 继承其父级的安全配置，以维持稳固的安全边界：

* **继承的作用域**：子 Agent 会自动继承父级允许的终端命令前缀和文件读写目录范围。子 Agent 无法执行任何用户尚未为父级批准的操作。
* **工作空间访问**：父级 Agent 保留对其子 Agent 工作空间的完全访问权限，包括在隔离的 Git 工作树上运行的子 Agent。
* **权限气泡**：如果子 Agent 遇到需要明确用户确认的工具调用，该请求会自动气泡化（bubble up）并显示在子 Agent 面板 UI 中，等待您的批准。

## 多 Agent 协同工作 (Multi-Agent Teamwork)（仅限 Ultra 订阅方案）

Antigravity 2.0 为处理极度复杂的任务引入了高级的多 Agent 编排能力。

> \[!NOTE]
> **Ultra 方案专属**：`/teamwork-preview` 斜杠命令目前处于预览阶段，并且是 Ultra 订阅方案（$200/月）用户的专属功能。

使用 `/teamwork-preview` 会促使主 Agent 启动协同的多 Agent 框架。该框架具有内置的错误恢复、自动重试 and 协调逻辑，允许您只需定义高层目标，而平台将负责管理合作 Agent 团队运行的全部开销。