---
title: "Subagents"
description: "基于 Cursor 官方 Subagents 文档解释上下文隔离、并行执行、内置 subagents、自定义文件、字段和调用方式。"
verifiedAt: "2026-05-09"
---

Subagents（子代理）是 Cursor Agent 可以委派任务的专门 AI assistants。官方文档说明，每个 subagent 都有自己的 context window（上下文窗口，模型一次能看到的总信息量），处理特定类型工作，并把结果返回给 parent agent（父代理，发起委派的主 agent）。

> [!NOTE]
> **阅读目标**：读完本章，你应该能判断什么时候用 subagent，什么时候改用 skill，并能写出一个 project-level verifier subagent。

## 1. 为什么需要 Subagents

官方给出四个核心价值。

| 价值 | 说明 |
| --- | --- |
| Context isolation | 长研究、探索和日志不会占满主 conversation |
| Parallel execution | 多个 subagents 可以同时跑不同工作流 |
| Specialized expertise | 可以配置 prompts、tool access、models |
| Reusability | 自定义 subagents 可以跨项目复用 |

```mermaid
flowchart TD
  Parent["Parent Agent"] --> TaskA["Explore codebase"]
  Parent --> TaskB["Run commands"]
  Parent --> TaskC["Verify result"]
  TaskA --> SubA["Explore subagent context"]
  TaskB --> SubB["Bash subagent context"]
  TaskC --> SubC["Verifier custom subagent"]
  SubA --> ResultA["Summary"]
  SubB --> ResultB["Command findings"]
  SubC --> ResultC["Pass / incomplete / issues"]
  ResultA --> Parent
  ResultB --> Parent
  ResultC --> Parent
```

Subagent 从 clean context 开始。它不会自动继承 prior conversation history，parent agent 需要在 prompt 里放入必要上下文。

## 2. Foreground 和 Background

官方把 subagent 运行模式分成两类。

| Mode | 行为 | 适合 |
| --- | --- | --- |
| Foreground | parent 等 subagent 完成，立即拿结果 | 后一步依赖前一步输出 |
| Background | parent 立即继续，subagent 独立工作 | 长任务、并行工作流 |

如果下一步实现必须等审计结果，使用 foreground。只是让另一个 agent 同时做文档、搜索或验证，用 background。

## 3. 内置 Subagents

官方内置三个 subagents，Agent 会在合适时自动使用，不需要你配置。

| Subagent | 用途 | 为什么隔离 |
| --- | --- | --- |
| Explore | 搜索和分析 codebase | 搜索会产生大量中间输出 |
| Bash | 运行一系列 shell commands | command output 通常很啰嗦 |
| Browser | 通过 MCP tools 控制浏览器 | DOM snapshot 和 screenshot 噪声大 |

这些内置 subagents 的目标是把噪声留在子上下文，只把最终 finding 返回给主对话。Explore subagent 默认使用更快模型，可以并行跑多次搜索。

## 4. Subagents 还是 Skills

官方给出的判断：

| 用 Subagents | 用 Skills |
| --- | --- |
| 需要单独 context window | 任务是单一用途 |
| 多个 workstreams 并行 | 快速、可重复 action |
| 需要多步骤专业角色 | 一次完成 |
| 需要独立验证 | 不需要分离上下文 |

比如“生成 changelog”更像 skill；“用独立上下文验证一个复杂实现是否真的完成”更像 subagent。

## 5. 文件位置和优先级

自定义 subagent 是 Markdown 文件，放在项目或用户目录。

| 类型 | 位置 | 作用域 |
| --- | --- | --- |
| Project | `.cursor/agents/` | 当前项目 |
| Project | `.claude/agents/` | 当前项目，Claude compatibility |
| Project | `.codex/agents/` | 当前项目，Codex compatibility |
| User | `~/.cursor/agents/` | 当前用户所有项目 |
| User | `~/.claude/agents/` | 当前用户所有项目，Claude compatibility |
| User | `~/.codex/agents/` | 当前用户所有项目，Codex compatibility |

优先级：

1. Project subagents 优先于 user subagents。
2. 同名冲突时，`.cursor/` 优先于 `.claude/` 或 `.codex/`。

## 6. 文件格式

每个 subagent 是一个带 YAML frontmatter 的 Markdown 文件。

```markdown
---
name: verifier
description: Validates completed work. Use after tasks are marked done to confirm implementations are functional.
model: inherit
readonly: true
---

You are a skeptical validator.

When invoked:
1. Identify what was claimed to be completed.
2. Check that the implementation exists and is functional.
3. Run relevant tests or verification steps.
4. Report what passed, what is incomplete, and what still needs work.
```

支持字段：

| Field | Required | Default | 用途 |
| --- | --- | --- | --- |
| `name` | No | filename 派生 | display name 和 identifier，建议 lowercase hyphen |
| `description` | No | none | Agent 读取它来判断是否委派 |
| `model` | No | `inherit` | 使用 parent model 或指定模型 ID |
| `readonly` | No | `false` | 限制写权限，不允许 file edits 和 state-changing shell commands |
| `is_background` | No | `false` | 是否后台运行，不阻塞 parent |

`model` 可以是 `inherit`，也可以是特定 model ID。官方提醒：team admin restriction、Max Mode requirement、plan limitation 都可能让 Cursor fallback 到兼容模型。

## 7. 调用方式

Agent 可以自动委派，也可以显式调用。

自动委派取决于：

- task complexity and scope。
- project 中 custom subagent descriptions。
- 当前上下文和可用工具。

显式调用可以用 `/name`：

```text
/verifier confirm the auth flow is complete
/debugger investigate this error
/security-auditor review the payment module
```

也可以自然语言调用：

```text
Use the verifier subagent to confirm the auth flow is complete
Run the security-auditor subagent on the payment module
```

## 8. 恢复和常见模式

每次 subagent execution 会返回 agent ID。你可以用这个 ID 恢复 subagent conversation：

```text
Resume agent abc123 and analyze the remaining test failures
```

常见模式：

- Verification agent：独立验证 claimed work 是否真的完成。
- Orchestrator pattern：Planner、Implementer、Verifier 依次交接。
- Debugger：捕获 error、stack trace、复现步骤，定位 root cause。

<details>
<summary>深读：为什么 verifier 应该 readonly 起步</summary>

Verifier 的职责是独立验证，而不是继续实现。让 verifier 默认只读，可以避免它把“发现问题”和“顺手修改”混在一起。

如果验证结论需要修复，回到 parent agent 或单独创建 implementer 任务。这样责任边界更清楚：谁验证，谁实现，谁最终合并。
</details>

## 本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. Subagent 为什么能节省主 conversation 的 context？
2. 什么任务应该用 skill，而不是 subagent？
3. Project subagent 和 user subagent 的优先级是什么？

通过标准：你能写出一个 `.cursor/agents/verifier.md`，并解释它的 `description`、`model`、`readonly` 和调用方式。

## 官方来源

- [Cursor Subagents](https://cursor.com/docs/subagents.md) —— 官方说明上下文隔离、并行、内置 subagents、自定义文件位置、字段、调用和恢复。
- [Cursor Skills](https://cursor.com/docs/skills.md) —— 官方说明何时用 skill 而不是 subagent。
- [Cursor Models & Pricing](https://cursor.com/docs/models-and-pricing.md) —— 官方模型 ID 和可用性以当前页面为准。

## 接下来去哪

<Cards>
  <Card title="Hooks" description="继续学习用脚本观察、阻止或扩展 agent loop。" href="/docs/cursor/official/02-context-customization/24-hooks" />
  <Card title="Skills" description="单一可复用任务优先看 Skills。" href="/docs/cursor/official/02-context-customization/22-skills" />
</Cards>
