nt-dispatching-parallel-agents

Parallel Scheduling of Subagents

Overview

When you have multiple independent tasks or problems, using subagents to execute them in parallel can significantly improve efficiency. The main agent is responsible for scheduling and assigning tasks, while subagents are responsible for executing the specific work.

This skill integrates a professional agent prompt system and provides the following built-in agent types:

• Code Fix Agent
• Code Generation Agent
• Test Generation Agent
• Code Review Agent
• Documentation Agent

For complete agent prompt templates and usage guides, see:dispatching-parallel-agents-zh/references/agent_prompts.md

Core principle: One subagent handles one independent problem domain. Let them work in parallel.

Usage Scenarios

digraph when_to_use {
    "多个任务吗？" [shape=diamond];
    "它们独立吗？" [shape=diamond];
    "单个代理处理所有任务" [shape=box];
    "每个问题域一个代理" [shape=box];
    "可以并行工作吗？" [shape=diamond];
    "顺序代理" [shape=box];
    "并行调度" [shape=box];

    "多个任务吗？" -> "它们独立吗？" [label="是"];
    "它们独立吗？" -> "单个代理处理所有任务" [label="否 - 相关"];
    "它们独立吗？" -> "可以并行工作吗？" [label="是"];
    "可以并行工作吗？" -> "并行调度" [label="是"];
    "可以并行工作吗？" -> "顺序代理" [label="否 - 共享状态"];
}

Conditions for use:

• 3+ independent test files or modules
• Multiple subsystems working independently
• Each problem can be understood independently
• No shared state between tasks

Conditions to avoid:

• Tasks are related (fixing one problem may affect other tasks)
• Requires understanding the complete system state
• Agents will interfere with each other

Pattern Structure

1. Identify Independent Domains

Group tasks by function:

• File A: Approval process
• File B: Batch completion behavior
• File C: Abort functionality

Each domain is independent - fixing the approval flow does not affect the abort functionality.

2. Create Focused Agent Tasks

Each agent receives:

• Specific scope: One file or subsystem
• Clear objective: Complete this task
• Permission limitations: Must not change code without permission
• Expected output: Detailed task summary report

3. Parallel Scheduling

// 在AI环境中
Task("修复文件A - 权限：只读/src/approval", 提交路径="src/approval", 任务类型="修复bug")
Task("修复文件B - 权限：读写/src/batch", 提交路径="src/batch", 任务类型="添加功能") 
Task("修复文件C - 权限：只读/src/abort", 提交路径="src/abort", 任务类型="优化性能")
// 所有子代理并行执行

4. Aggregate and Integrate

When subagents return:

• Read each summary report
• Verify that changes do not conflict
• Run integration tests
• Integrate all results

Subagent Task Structure

A good agent task has the following characteristics:

1. Focused: One clear scope
2. Self-contained: Complete required context
3. Specific output: What the subagent should return

Examples of Using Built-in Agents

For complete built-in agent usage examples and templates, see:dispatching-parallel-agents-zh/references/agent_prompts.md

Important: When calling Task, the following detailed information must be included:

1. prompt: Complete agent prompt template (including role, workflow, and permission description)
2. config.permissions: Detailed permission configuration
   • read: directories that can be read
   • write: directories that can be modified
   • execute: executable command
   • forbidden: forbidden directory
3. config.timeout: timeout (seconds)
4. config.output_format: output format

Example usage:

Task(
  description="修复登录会话问题",
  prompt="你是代码修复专家，专门负责分析和修复代码中的问题。\n\n工作流程：\n1. 分析问题...\n2. 定位根因...\n\n权限范围：只读 src/auth/*, src/models/*; 可修改 src/auth/*; 禁止修改 src/payment/*\n工作目录：C:/Users/Administrator/project/src/auth\n\n请修复会话超时问题...\n\n返回：详细任务总结报告。",
  config={
    "permissions": {
      "read": ["/src/auth/**/*", "/src/models/**/*", "/src/config/**/*"],
      "write": ["/src/auth/**/*"],
      "execute": ["npm test", "npm run build"],
      "forbidden": ["/src/payment/**/*", "/src/config/database.js"]
    },
    "timeout": 1800,
    "output_format": "detailed_report"
  }
)

Permission management

Sub-agent permissions:

• Read permission: can view code and documentation
• Write permission: can modify files in specified directories
• Execute permission: can run tests and build commands
• Restricted permission: not authorized to modify code in other directories

Conflict handling:

• If a sub-agent detects that code in other directories needs to be modified, report to the main agent
• The main agent decides after analysis whether to dispatch other agents or reassign permissions
• Major modifications require review by the main agent

Sub-agent task summary report format

Each sub-agent must generate a report in the following format:

任务ID: [任务编号]
子代理: [代理类型 - 如代码修复代理、代码编写代理等]
执行时间: [开始-结束时间]
工作目录: [工作目录]
权限范围: [有权限修改的目录]

发现:
- 问题1: [详细描述，包括具体错误信息、堆栈跟踪等]
- 问题2: [详细描述]

解决方案:
- 方法1: [如何解决，包括具体的代码修改方案]
- 方法2: [如何解决]

修改的文件:
- src/file1.ts: [修改原因 - 为什么需要改]
- src/file2.ts: [修改原因]

测试结果:
- 修复前: [失败情况 - 具体错误]
- 修复后: [成功情况 - 测试通过]

遇到的问题:
- 权限不足: [需要主代理协助的具体内容]
  * 需要修改的文件路径: [如 src/backend/api/users.js]
  * 需要修改的代码内容: [具体的代码片段或实现方案]
  * 修改原因: [为什么必须这样修改]
  
- 需要其他模块: [需要联系其他子代理的具体任务]
  * 目标代理类型: [如后端开发代理]
  * 具体任务: [要做什么]
  * 接口规范: [如果是API，详细的请求/响应格式]

总结:
- 任务完成度: [百分比]
- 是否需要后续工作: [是/否及原因]
- 后续任务详情: [详细的后续任务描述]

Adjust report focus according to agent type

For the complete report format and report focus for different types of agents, see:dispatching-parallel-agents-zh/references/agent_prompts.md

Main agent's process for handling reports

1. Receive report: read the task summary report returned by the sub-agent
2. Analyze completion: evaluate the task completion percentage
3. Check issues: review the "Problems encountered" section
4. Decision handling：
   • If there is "insufficient permission": evaluate whether other agents need to be dispatched
   • If there is "need other modules": create a new sub-agent task
   • If "task completion" is low: decide whether to retry or adjust the plan
5. Execute follow-up: dispatch a new agent or handle it yourself

Conflict resolution

Permission conflict handling process

When a sub-agent indicates in the task summary report that it needs to modify code it does not have permission for, the main agent must:

1. Analyze report: carefully read the sub-agent's insufficient permission report
2. Weigh pros and cons: evaluate whether other modules really need to be modified
3. Decide dispatch: decide whether to dispatch other agents to execute

Factors for the main agent's decision:

• Necessity of modification: whether cross-module modification is really needed
• Risk assessment: the possible impact of the modification
• Workload assessment: other agents executing vs. the main agent handling it itself
• Dependencies: the order of modifications

Possible decisions by the main agent:

Situation	Decision	Reason
Frontend needs backend API	Dispatch backend agent	Separation of duties; backend API is more specialized
Backend needs frontend coordination	Dispatch frontend agent	Maintain module independence
Simple modification	Main agent handles it directly	Avoid dispatch overhead
Complex modification	Dispatch specialized agent	Ensure code quality

Permission conflict report format

The sub-agent must specify in detail the code that needs to be modified:

遇到的问题:
- 权限不足: [需要主代理协助的具体内容]
  需要修改的文件路径: [具体路径]
  需要修改的代码内容: [具体代码片段]
  修改原因: [为什么需要这样修改]
  建议的修改方案: [推荐的具体实现方式]

- 需要其他模块: [需要其他代理执行的具体任务]
  目标代理类型: [如后端开发代理]
  任务描述: [具体要做什么]
  接口规范: [如果涉及API，要详细说明接口格式]

Resource conflict

• Multiple agents need to modify the same file → main agent coordinates
• Dependency conflict → main agent rearranges execution order

Decision process

When multiple tasks are received:

digraph decision_flow {
    "收到多个任务" [shape=box];
    "分析独立性" [shape=diamond];
    "独立？" [shape=diamond];
    "并行调度" [shape=box];
    "顺序处理" [shape=box];
    "评估复杂度" [shape=diamond];
    "复杂度高？" [shape=diamond];
    "单代理处理" [shape=box];

    "收到多个任务" -> "分析独立性";
    "分析独立性" -> "独立？" [label="分析"];
    "独立？" -> "并行调度" [label="是"];
    "独立？" -> "评估复杂度" [label="否"];
    "评估复杂度" -> "复杂度高？" [label="评估"];
    "复杂度高？" -> "单代理处理" [label="是"];
    "复杂度高？" -> "顺序处理" [label="否"];
}

Common mistakes

❌ Scope too broad: "Fix all issues" - subagents easily get lost ✅ Specific scope: "Fix file A" - clear scope

❌ No context: "Fix this" - subagent does not know the context ✅ With context: Provide error information and related files

❌ No permission restrictions: Subagent may modify code it should not change ✅ With permission restrictions: "Only src/prod/ directory may be modified"

❌ Vague output: "Fix it" - do not know what was changed ✅ Specific output: "Return a task summary report"

Verification

After subagents return:

1. Review each report - understand what modifications were made
2. Check for conflicts - did agents modify the same code?
3. Run tests - verify all fixes work together
4. Spot-check - verify subagent work quality

Key advantages

1. Parallelization - multiple investigations proceed simultaneously
2. Focus - each agent has a narrow scope, reducing context
3. Independence - agents do not interfere with each other
4. Efficiency - 3 issues solved in parallel vs sequentially
5. Clear division of labor - main agent as leader, subagents as workers

Practical example

Scenario: 6 test failures distributed across 3 files

Failures:

• agent-tool-abort.test.ts: 3 failures (timing issues)
• batch-completion-behavior.test.ts: 2 failures (tools not executed)
• tool-approval-race-conditions.test.ts: 1 failure (execution count is 0)

Decision: Independent domains - abort logic, batch completion, race conditions

Scheduling:

子代理1 → 修复agent-tool-abort.test.ts（权限：src/agents/*读写）
子代理2 → 修复batch-completion-behavior.test.ts（权限：src/batch/*读写）  
子代理3 → 修复tool-approval-race-conditions.test.ts（权限：src/approval/*读写）

Results:

• Subagent 1: replace timeout with event waiting
• Subagent 2: fix event structure bug (threadId in wrong position)
• Subagent 3: add waiting for asynchronous tool execution to complete

Integration: All fixes are independent, no conflicts, full suite green

Time saved: 3 issues solved in parallel vs sequentially