Parallel Agent Dispatch
Overview
You delegate tasks to specialized agents with isolated contexts. By carefully designing their instructions and context, ensure they stay focused and successfully complete their tasks. They should not inherit your session context or history—you precisely construct everything they need. This also preserves your own context for coordinating work.
When you encounter multiple unrelated failures (different test files, different subsystems, different bugs), troubleshooting them one by one wastes time. Each troubleshooting task is independent and can be performed in parallel.
Core Principle: Assign one agent per independent problem domain and let them work concurrently.
When to Use
dot
digraph when_to_use {
"存在多个失败?" [shape=diamond];
"它们是否独立?" [shape=diamond];
"单个智能体排查所有问题" [shape=box];
"每个问题域一个智能体" [shape=box];
"能否并行工作?" [shape=diamond];
"顺序执行智能体" [shape=box];
"并行分派" [shape=box];
"存在多个失败?" -> "它们是否独立?" [label="是"];
"它们是否独立?" -> "单个智能体排查所有问题" [label="否 - 有关联"];
"它们是否独立?" -> "能否并行工作?" [label="是"];
"能否并行工作?" -> "并行分派" [label="是"];
"能否并行工作?" -> "顺序执行智能体" [label="否 - 有共享状态"];
}
Applicable Scenarios:
- 3+ test files failing due to different root causes
- Multiple subsystems failing independently
- Each issue can be understood without context from other issues
- No shared state between troubleshooting tasks
Inapplicable Scenarios:
- Failures are related (fixing one may fix others)
- Need to understand the complete system state
- Agents will interfere with each other
Pattern
1. Identify Independent Problem Domains
Group failures by domain:
- File A Tests: Tool approval flow
- File B Tests: Batch completion behavior
- File C Tests: Abort functionality
Each problem domain is independent—fixing tool approval won't affect abort tests.
2. Create Focused Agent Tasks
Each agent gets:
- Clear Scope: One test file or subsystem
- Clear Goal: Make these tests pass
- Constraints: Do not modify other code
- Expected Output: A summary of what you found and fixed
3. Parallel Dispatch
typescript
// 在 Claude Code / AI 环境中
Task("修复 agent-tool-abort.test.ts 的失败")
Task("修复 batch-completion-behavior.test.ts 的失败")
Task("修复 tool-approval-race-conditions.test.ts 的失败")
// 三个任务并发运行
4. Review and Integrate
When agents return:
- Read each summary
- Verify no conflicts between fixes
- Run the full test suite
- Integrate all changes
Agent Prompt Structure
A good agent prompt should be:
- Focused - One clear problem domain
- Self-contained - Contains all context needed to understand the problem
- Clear Output Requirements - What should the agent return?
markdown
修复 src/agents/agent-tool-abort.test.ts 中 3 个失败的测试：
1. "should abort tool with partial output capture" - 期望消息中包含 'interrupted at'
2. "should handle mixed completed and aborted tools" - 快速工具被中止而非完成
3. "should properly track pendingToolCount" - 期望 3 个结果但得到 0 个
这些是时序/竞态条件问题。你的任务：
1. 阅读测试文件，理解每个测试验证的内容
2. 找到根因——是时序问题还是实际 bug？
3. 修复方式：
- 用基于事件的等待替换任意超时
- 如果发现中止实现中的 bug 则修复
- 如果测试的是已变更的行为则调整测试期望
不要只是增加超时时间——找到真正的问题。
返回：你发现了什么以及修复了什么的总结。
Common Mistakes
Wrong Approach: Too Broad: "Fix all tests" - Agents will get lost
Right Approach: Specific: "Fix agent-tool-abort.test.ts" - Focused scope
Wrong Approach: No Context: "Fix race conditions" - Agents don't know where
Right Approach: Provide Context: Paste error messages and test names
Wrong Approach: No Constraints: Agents might refactor all code
Right Approach: Set Constraints: "Do not modify production code" or "Only fix tests"
Wrong Approach: Vague Output Requirements: "Fix it" - You don't know what was changed
Right Approach: Clear Requirements: "Return a summary of root causes and changes made"
Inapplicable Scenarios
Related Failures: Fixing one may fix others—troubleshoot together first
Need Full Context: Understanding the issue requires seeing the entire system
Exploratory Debugging: You don't yet know what's broken
Shared State: Agents will interfere with each other (editing the same file, using the same resource)
Real-World Example
Scenario: 6 test failures across 3 files after a large refactor
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 problem domains—abort logic, batch completion, and race conditions are separate
Dispatch:
Agent 1 → Fix agent-tool-abort.test.ts
Agent 2 → Fix batch-completion-behavior.test.ts
Agent 3 → Fix tool-approval-race-conditions.test.ts
Results:
- Agent 1: Replaced timeouts with event-based waits
- Agent 2: Fixed event structure bug (incorrect threadId placement)
- Agent 3: Added logic to wait for asynchronous tool execution completion
Integration: All fixes are independent, no conflicts, full test suite passes
Time Saved: 3 issues resolved in parallel vs sequentially
Core Benefits
- Parallelization - Multiple troubleshooting tasks happening simultaneously
- Focus - Each agent has a narrow scope with less context to track
- Independence - Agents don't interfere with each other
- Speed - 3 issues solved in the time it takes to solve 1
Validation
After agents return:
- Review Each Summary - Understand what was changed
- Check for Conflicts - Did agents edit the same code?
- Run Full Suite - Verify all fixes work together
- Spot Check - Agents may make systemic errors
Actual Results
From debugging session (2025-10-03):
- 6 failures across 3 files
- 3 agents dispatched in parallel
- All troubleshooting completed concurrently
- All fixes successfully integrated
- Zero conflicts between agent changes