在Cursor中使用多代理协同（Agent Swarm）

概述

在 Cursor IDE 中实现类似 Claude Agent Swarm 的多代理协同功能，主要有三种方式：

一、Cursor 内置子代理（Subagents）

Cursor v2.4（2026-01-22）引入，最原生的多代理协同方案。

1.1 工作原理

子代理是独立的 AI 代理，用于并行处理父代理任务中彼此独立的部分。每个子代理具备以下特性：

• 独立上下文窗口 — 不会污染主对话上下文
• 可配置自定义提示词 — 针对特定任务优化指令
• 独立工具访问权限 — 按需分配可用工具
• 独立模型选择 — 可为不同子代理指定不同模型

1.2 运行模式

1.3 内置子代理

Cursor 自带三个内置子代理，无需配置，Agent 会在需要时自动调用：

1.4 创建自定义子代理

在以下目录中创建 Markdown 文件即可定义自定义子代理：

• 项目级：.cursor/agents/（仅当前项目生效）
• 用户级：~/.cursor/agents/（所有项目生效）

示例：创建一个验证代理

创建文件 .cursor/agents/verifier.md：

---
name: verifier
description: 验证已完成的工作，检查实现是否正确
---

你是一个代码验证专家。你的任务是：

1. 检查已完成的实现是否符合需求
2. 运行测试并报告结果
3. 检查是否有遗漏的边界情况
4. 报告通过了什么、还有什么未完成

示例：创建一个数据库专家代理

创建文件 .cursor/agents/db-expert.md：

---
name: db-expert
description: 数据库架构设计和查询优化专家
---

你是一个数据库专家。专注于：

1. 数据库 schema 设计和迁移
2. SQL 查询性能优化
3. 索引策略建议
4. 数据一致性检查

你也可以直接在 Agent 对话中让 AI 帮你创建：

"Create a subagent file at .cursor/agents/verifier.md that validates completed work, runs tests, and reports results."

1.5 前提条件

• Cursor 版本 >= 2.4
• 按量计费套餐：子代理默认启用
• 传统按请求计费套餐：需要先启用 Max Mode 才能使用子代理

1.6 使用建议

1.7 性能与成本注意事项

二、Parallel Agents（并行代理 + Worktrees）

这是另一种"蜂群"模式——在多个 Git Worktree 中并行运行多个完整代理，每个代理在隔离的环境中独立工作。

2.1 使用方法

1. 在 Agent 聊天窗口中，点击发送按钮旁的下拉菜单
2. 选择 "Run in Worktree"
3. 代理在独立的 worktree 中工作，互不干扰
4. 完成后点击 "Apply" 按钮，将更改合并回主工作分支

2.2 Best-of-N：多模型同时运行

可以用同一个提示词同时运行多个模型，然后从中选出最佳方案：

1. 在 Worktree 模式下选择多个模型
2. 提交提示词后，每个模型会在独立的 worktree 中生成方案
3. 查看每个方案的卡片，比较代码差异
4. 选择最优方案，点击 "Apply" 应用

适用场景

• 难题需要不同模型尝试不同方案
• 比较不同模型的代码质量
• 发现单个模型可能遗漏的边界情况
• 基准测试哪个模型最适合你的代码库

2.3 配置 Worktree 初始化

在项目中创建 .cursor/worktrees.json，定义 worktree 的初始化命令：

Node.js 项目

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

Python 项目

{
  "setup-worktree": [
    "python -m venv venv",
    "source venv/bin/activate && pip install -r requirements.txt",
    "cp $ROOT_WORKTREE_PATH/.env .env"
  ]
}

带数据库迁移的项目

{
  "setup-worktree": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env",
    "npm run db:migrate"
  ]
}

跨平台配置

{
  "setup-worktree-unix": [
    "npm ci",
    "cp $ROOT_WORKTREE_PATH/.env .env",
    "chmod +x scripts/*.sh"
  ],
  "setup-worktree-windows": [
    "npm ci",
    "copy %ROOT_WORKTREE_PATH%\\.env .env"
  ]
}

2.4 Worktree 管理

• 数量限制：每个工作区最多 20 个 worktree
• 自动清理：超过限制时自动移除最旧的 worktree
• 可在设置中配置清理策略：

{
  "cursor.worktreeCleanupIntervalHours": 6,
  "cursor.worktreeMaxCount": 20
}

• 查看所有 worktree：终端运行 git worktree list
• 在 SCM 面板查看：启用 git.showCursorWorktrees 设置

三、Agency Swarm 框架（第三方）

Agency Swarm 是一个第三方 Python 框架，专门用于构建多代理 AI 系统，与 Cursor 有良好集成。适合构建生产级多代理应用。

3.1 使用步骤

1. 安装 Agency Swarm

   pip install agency-swarm

2. 下载 .cursorrules 文件

   从 GitHub 仓库 下载，放到项目根目录。

3. 在 Cursor 设置中启用 Rules for AI

   打开 Cursor IDE → Settings → Cursor Settings → 启用 Rules for AI。

4. 打开 Composer 开始创建代理

   按 Ctrl+I（Linux/Windows）或 Cmd+I（macOS）打开 Composer。

5. 发送详细提示词

   在第一个提示词中包含：

   • 要创建的所有代理
   • 代理需要使用的工具和 API
   • 代理之间的通信流程

6. 验证和迭代

   • 验证所有 import 语句正确
   • 检查 requirements.txt 文件存在
   • 运行每个工具文件确保工作正常
   • 手动审查和调整 agent 的 instruction.md 文件
   • 运行 agency.py 测试整体流程

3.2 与内置子代理的区别

四、最佳实践

4.1 日常开发推荐流程

1. 默认使用内置 Subagents — 无需额外配置，Agent 自动调度
2. 复杂任务创建自定义子代理 — 在 .cursor/agents/ 下定义专门的代理
3. 重要变更使用 Parallel Agents — 多模型对比，选最优方案
4. 配合 Rules 和 Skills 使用 — Rules 定义始终生效的规范，Skills 定义按需调用的操作指南

4.2 自定义子代理设计原则

• 单一职责：每个子代理聚焦一个领域（测试、文档、重构等）
• 清晰的提示词：在 YAML frontmatter 中准确描述用途
• 合理的工具权限：只授予必要的工具访问权限
• 适当的模型选择：简单任务用快速模型，复杂任务用强模型

4.3 何时不应使用子代理

• 简单的单步任务（直接由主代理完成更快）
• 不需要上下文隔离的短任务
• 可以用 Skill 一次性完成的标准操作

参考资料

• Cursor 官方文档 - Subagents
• Cursor 官方文档 - Parallel Agents
• Cursor 官方文档 - Skills
• Cursor v2.4 更新日志
• Agency Swarm 官方文档
• Agency Swarm GitHub