Dispatching Parallel Agents
Overview
When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each investigation is independent and can happen in parallel.
Core principle: Dispatch one agent per independent problem domain. Let them work concurrently.
When to Use
CODEBLOCK0
Use when:
- - 3+ test files failing with different root causes
- Multiple subsystems broken independently
- Each problem can be understood without context from others
- No shared state between investigations
Don't use when:
- - Failures are related (fix one might fix others)
- Need to understand full system state
- Agents would interfere with each other
The Pattern
1. Identify Independent Domains
Group failures by what's broken:
- - File A tests: Tool approval flow
- File B tests: Batch completion behavior
- File C tests: Abort functionality
Each domain is independent - fixing tool approval doesn't affect abort tests.
2. Create Focused Agent Tasks
Each agent gets:
- - Specific scope: One test file or subsystem
- Clear goal: Make these tests pass
- Constraints: Don't change other code
- Expected output: Summary of what you found and fixed
3. Dispatch in Parallel
CODEBLOCK1
4. Review and Integrate
When agents return:
- - Read each summary
- Verify fixes don't conflict
- Run full test suite
- Integrate all changes
Agent Prompt Structure
Good agent prompts are:
- 1. Focused - One clear problem domain
- Self-contained - All context needed to understand the problem
- Specific about output - What should the agent return?
CODEBLOCK2
Common Mistakes
❌ Too broad: "Fix all the tests" - agent gets lost
✅ Specific: "Fix agent-tool-abort.test.ts" - focused scope
❌ No context: "Fix the race condition" - agent doesn't know where
✅ Context: Paste the error messages and test names
❌ No constraints: Agent might refactor everything
✅ Constraints: "Do NOT change production code" or "Fix tests only"
❌ Vague output: "Fix it" - you don't know what changed
✅ Specific: "Return summary of root cause and changes"
When NOT to Use
Related failures: Fixing one might fix others - investigate together first
Need full context: Understanding requires seeing entire system
Exploratory debugging: You don't know what's broken yet
Shared state: Agents would interfere (editing same files, using same resources)
Real Example from Session
Scenario: 6 test failures across 3 files after major refactoring
Failures:
- - agent-tool-abort.test.ts: 3 failures (timing issues)
- batch-completion-behavior.test.ts: 2 failures (tools not executing)
- tool-approval-race-conditions.test.ts: 1 failure (execution count = 0)
Decision: Independent domains - abort logic separate from batch completion separate from race conditions
Dispatch:
CODEBLOCK3
Results:
- - Agent 1: Replaced timeouts with event-based waiting
- Agent 2: Fixed event structure bug (threadId in wrong place)
- Agent 3: Added wait for async tool execution to complete
Integration: All fixes independent, no conflicts, full suite green
Time saved: 3 problems solved in parallel vs sequentially
Key Benefits
- 1. Parallelization - Multiple investigations happen simultaneously
- Focus - Each agent has narrow scope, less context to track
- Independence - Agents don't interfere with each other
- Speed - 3 problems solved in time of 1
Verification
After agents return:
- 1. Review each summary - Understand what changed
- Check for conflicts - Did agents edit same code?
- Run full suite - Verify all fixes work together
- Spot check - Agents can make systematic errors
Real-World Impact
From debugging session (2025-10-03):
- - 6 failures across 3 files
- 3 agents dispatched in parallel
- All investigations completed concurrently
- All fixes integrated successfully
- Zero conflicts between agent changes
并行代理调度
概述
当遇到多个不相关的故障（不同的测试文件、不同的子系统、不同的缺陷）时，逐个排查会浪费时间。每个调查都是独立的，可以并行进行。
核心原则： 每个独立问题域分配一个代理，让它们同时工作。
使用时机
dot
digraph whentouse {
存在多个故障？ [shape=diamond];
它们是否独立？ [shape=diamond];
单个代理调查所有问题 [shape=box];
每个问题域一个代理 [shape=box];
它们能并行工作吗？ [shape=diamond];
串行代理 [shape=box];
并行调度 [shape=box];
存在多个故障？ -> 它们是否独立？ [label=是];
它们是否独立？ -> 单个代理调查所有问题 [label=否 - 相关];
它们是否独立？ -> 它们能并行工作吗？ [label=是];
它们能并行工作吗？ -> 并行调度 [label=是];
它们能并行工作吗？ -> 串行代理 [label=否 - 共享状态];
}
适用场景：
- - 3个以上测试文件因不同根本原因失败
- 多个子系统独立损坏
- 每个问题无需其他上下文即可理解
- 调查之间无共享状态
不适用场景：
- - 故障相互关联（修复一个可能修复其他）
- 需要了解完整系统状态
- 代理之间会相互干扰
模式
1. 识别独立域
按故障内容对失败进行分组：
- - 文件A测试：工具审批流程
- 文件B测试：批次完成行为
- 文件C测试：中止功能
每个域都是独立的——修复工具审批不会影响中止测试。
2. 创建聚焦的代理任务
每个代理获得：
- - 特定范围： 一个测试文件或子系统
- 明确目标： 使这些测试通过
- 约束条件： 不更改其他代码
- 预期输出： 发现和修复内容的摘要
3. 并行调度
typescript
// 在Claude Code / AI环境中
Task(修复 agent-tool-abort.test.ts 的故障)
Task(修复 batch-completion-behavior.test.ts 的故障)
Task(修复 tool-approval-race-conditions.test.ts 的故障)
// 三个任务同时运行
4. 审查与整合
当代理返回时：
- - 阅读每个摘要
- 验证修复不冲突
- 运行完整测试套件
- 整合所有更改
代理提示结构
好的代理提示应具备：
- 1. 聚焦性 - 一个清晰的问题域
- 自包含性 - 理解问题所需的所有上下文
- 输出明确性 - 代理应返回什么？
markdown
修复 src/agents/agent-tool-abort.test.ts 中的3个失败测试：
- 1. should abort tool with partial output capture - 期望消息中包含 interrupted at
- should handle mixed completed and aborted tools - 快速工具被中止而非完成
- should properly track pendingToolCount - 期望3个结果但得到0个
这些是时序/竞态条件问题。你的任务：
- 1. 阅读测试文件并理解每个测试验证的内容
- 识别根本原因 - 时序问题还是实际缺陷？
- 通过以下方式修复：
- 用基于事件的等待替换任意超时
- 如果发现中止实现中的缺陷则修复
- 如果测试的是已更改的行为则调整测试预期
不要仅仅增加超时时间——找到真正的问题。
返回：你发现的内容和修复内容的摘要。
常见错误
❌ 过于宽泛： 修复所有测试 - 代理会迷失方向
✅ 具体明确： 修复 agent-tool-abort.test.ts - 聚焦范围
❌ 无上下文： 修复竞态条件 - 代理不知道在哪里
✅ 提供上下文： 粘贴错误消息和测试名称
❌ 无约束条件： 代理可能会重构所有内容
✅ 设定约束： 不要更改生产代码 或 仅修复测试
❌ 输出模糊： 修复它 - 你不知道改变了什么
✅ 输出明确： 返回根本原因和更改的摘要
不适用场景
相关故障： 修复一个可能修复其他 - 先一起调查
需要完整上下文： 理解需要查看整个系统
探索性调试： 你还不知道哪里出了问题
共享状态： 代理会相互干扰（编辑相同文件、使用相同资源）
实际会话示例
场景： 重大重构后3个文件出现6个测试失败
故障：
- - agent-tool-abort.test.ts：3个失败（时序问题）
- batch-completion-behavior.test.ts：2个失败（工具未执行）
- tool-approval-race-conditions.test.ts：1个失败（执行次数=0）
决策： 独立域 - 中止逻辑与批次完成逻辑分离，与竞态条件分离
调度：
代理1 → 修复 agent-tool-abort.test.ts
代理2 → 修复 batch-completion-behavior.test.ts
代理3 → 修复 tool-approval-race-conditions.test.ts
结果：
- - 代理1：用基于事件的等待替换超时
- 代理2：修复事件结构缺陷（threadId位置错误）
- 代理3：添加对异步工具执行完成的等待
整合： 所有修复独立，无冲突，完整套件通过
节省的时间： 并行解决3个问题 vs 串行解决
关键优势
- 1. 并行化 - 多个调查同时进行
- 聚焦性 - 每个代理范围狭窄，需要跟踪的上下文更少
- 独立性 - 代理之间不相互干扰
- 速度 - 3个问题在1个问题的时间内解决
验证
代理返回后：
- 1. 审查每个摘要 - 了解更改了什么
- 检查冲突 - 代理是否编辑了相同代码？
- 运行完整套件 - 验证所有修复协同工作
- 抽查 - 代理可能犯系统性错误
实际影响
来自调试会话（2025-10-03）：
- - 3个文件中的6个故障
- 3个代理并行调度
- 所有调查同时完成
- 所有修复成功整合
- 代理更改之间零冲突
