Subagents

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

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

1. 为什么需要 Subagents

官方给出四个核心价值。

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

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

优先级：

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

6. 文件格式

每个 subagent 是一个带 YAML frontmatter 的 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：

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

也可以自然语言调用：

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：

Resume agent abc123 and analyze the remaining test failures

常见模式：

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

深读：为什么 verifier 应该 readonly 起步

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

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

本章自检

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

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

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

官方来源

Cursor Subagents —— 官方说明上下文隔离、并行、内置 subagents、自定义文件位置、字段、调用和恢复。
Cursor Skills —— 官方说明何时用 skill 而不是 subagent。
Cursor Models & Pricing —— 官方模型 ID 和可用性以当前页面为准。