Back to Details

dispatching-parallel-agents

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

調度並行代理

Dispatch Parallel Agents

概述

Overview

當您遇到多個不相關的故障（不同的測試檔案、不同的子系統、不同的錯誤）時，按順序調查它們會浪費時間。每項調查都是獨立的，可以並行進行。
核心原則： 每個獨立問題域調度一名代理。讓他們同時工作。
When you encounter multiple unrelated failures (different test files, different subsystems, different errors), investigating them sequentially wastes time. Each investigation is independent and can be conducted in parallel.
Core Principle: Assign one agent to each independent problem domain. Let them work simultaneously.

何時使用

When to Use

dot
digraph when_to_use {
    "Multiple failures?" [shape=diamond];
    "Are they independent?" [shape=diamond];
    "Single agent investigates all" [shape=box];
    "One agent per problem domain" [shape=box];
    "Can they work in parallel?" [shape=diamond];
    "Sequential agents" [shape=box];
    "Parallel dispatch" [shape=box];

    "Multiple failures?" -> "Are they independent?" [label="yes"];
    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
}
使用時間：
  • 3 個以上的測試文件因不同的根本原因而失敗
  • 多個子系統獨立損壞
  • 每個問題都可以在沒有其他問題的上下文的情況下被理解
  • 調查之間沒有共享狀態
請勿在以下情況下使用：
  • 故障是相關的（修復一個可能會修復其他故障）
  • 需要了解完整的系統狀態
  • 代理會互相干擾
dot
digraph when_to_use {
    "Multiple failures?" [shape=diamond];
    "Are they independent?" [shape=diamond];
    "Single agent investigates all" [shape=box];
    "One agent per problem domain" [shape=box];
    "Can they work in parallel?" [shape=diamond];
    "Sequential agents" [shape=box];
    "Parallel dispatch" [shape=box];

    "Multiple failures?" -> "Are they independent?" [label="yes"];
    "Are they independent?" -> "Single agent investigates all" [label="no - related"];
    "Are they independent?" -> "Can they work in parallel?" [label="yes"];
    "Can they work in parallel?" -> "Parallel dispatch" [label="yes"];
    "Can they work in parallel?" -> "Sequential agents" [label="no - shared state"];
}
When to use:
  • 3 or more test files failing due to different root causes
  • Multiple subsystems broken independently
  • Each problem can be understood without context from other problems
  • No shared state between investigations
Do NOT use when:
  • Failures are related (fixing one may fix others)
  • Full system state understanding is required
  • Agents will interfere with each other

模式

Patterns

1. 識別獨立域

1. Identify Independent Domains

按損壞的情況對失敗進行分組：
  • 文件A測試：工具解讀流程
  • 檔案 B 測驗：批次完成行為
  • 文件C 測試：中止功能
每個域都是獨立的 - 修復工具批准不會影響中止測試。
Group failures by broken functionality:
  • File A tests: Tool approval flow
  • File B tests: Batch completion behavior
  • File C tests: Abort functionality
Each domain is independent - fixing tool approval won't affect abort tests.

2. 創建有針對性的代理任務

2. Create Targeted Agent Tasks

每個代理獲得：
  • 具體範圍： 一個測試文件或子系統
  • 明確的目標： 通過這些測試
  • 約束： 不要更改其他代碼
  • 預期輸出： 您發現並修復的內容的摘要
Each agent gets:
  • Specific Scope: One test file or subsystem
  • Clear Goal: Pass these tests
  • Constraints: Do not change other code
  • Expected Output: A summary of what you found and fixed

3. 並行調度

3. Parallel Dispatch

typescript
// In Claude Code / AI environment
Task("Fix agent-tool-abort.test.ts failures")
Task("Fix batch-completion-behavior.test.ts failures")
Task("Fix tool-approval-race-conditions.test.ts failures")
// All three run concurrently
typescript
// In Claude Code / AI environment
Task("Fix agent-tool-abort.test.ts failures")
Task("Fix batch-completion-behavior.test.ts failures")
Task("Fix tool-approval-race-conditions.test.ts failures")
// All three run concurrently

4. 審查和整合

4. Review and Integrate

當代理返回時：
  • 閱讀每個摘要
  • 驗證修復不衝突
  • 運行完整的測試套件
  • 整合所有變更
When agents return:
  • Read each summary
  • Verify fixes do not conflict
  • Run the full test suite
  • Integrate all changes

代理提示結構

Agent Prompt Structure

好的代理提示是：
  1. 專注 - 一個明確的問題域
  2. 獨立 - 理解問題所需的所有上下文
  3. 具體輸出 - 代理應該返回什麼？
markdown
Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0

These are timing/race condition issues. Your task:

1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
   - Replacing arbitrary timeouts with event-based waiting
   - Fixing bugs in abort implementation if found
   - Adjusting test expectations if testing changed behavior

Do NOT just increase timeouts - find the real issue.

Return: Summary of what you found and what you fixed.
Good agent prompts are:
  1. Focused - One clear problem domain
  2. Self-Contained - All context needed to understand the problem
  3. Specific Output - What should the agent return?
markdown
Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts:

1. "should abort tool with partial output capture" - expects 'interrupted at' in message
2. "should handle mixed completed and aborted tools" - fast tool aborted instead of completed
3. "should properly track pendingToolCount" - expects 3 results but gets 0

These are timing/race condition issues. Your task:

1. Read the test file and understand what each test verifies
2. Identify root cause - timing issues or actual bugs?
3. Fix by:
   - Replacing arbitrary timeouts with event-based waiting
   - Fixing bugs in abort implementation if found
   - Adjusting test expectations if testing changed behavior

Do NOT just increase timeouts - find the real issue.

Return: Summary of what you found and what you fixed.

常見錯誤

Common Mistakes

❌ 太廣泛：“修復所有測試”- 代理迷路 ✅具體：“Repairagent-tool-abort.test.ts”-重點範圍
❌沒有上下文：“修復競爭條件” - 代理不知道在哪裡 ✅ 上下文： 貼上錯誤訊息和測試名稱
**❌沒有限制：**代理可能會重構一切 ✅ 限制： “不要更改生產代碼”或“僅修復測試”
❌ 模糊輸出： “修復它” - 你不知道發生了什麼變化 ✅ 具體：“根本原因和更改的返回摘要”
❌ Too Broad: "Fix all tests" - Agent gets lost ✅ Specific: "Fix agent-tool-abort.test.ts" - Focused scope
❌ No Context: "Fix race conditions" - Agent doesn't know where ✅ Context: Paste error messages and test names
❌ No Constraints: Agent might refactor everything ✅ Constraints: "Do not change production code" or "Only fix tests"
❌ Vague Output: "Fix it" - You don't know what changed ✅ Specific: "Return summary of root cause and changes made"

何時不使用

When Not to Use

相關故障： 修復一個可能會修復其他故障 - 首先一起調查 **需要完整的脈絡：**理解需要看到整個系統 探索性調試： 你還不知道哪裡出了問題 **共享狀態：**代理會干擾（編輯相同的文件，使用相同的資源）
Related Failures: Fixing one may fix others - Investigate together first Full Context Required: Understanding requires seeing the entire system Exploratory Debugging: You don't yet know what's broken Shared State: Agents will interfere (editing same files, using same resources)

會話中的真實範例

Real-World Session Example

**場景：**重大重構後 3 個檔案出現 6 次測試失敗
失敗：
  • agent-tool-abort.test.ts：3次失敗（時間問題）
  • batch-completion-behavior.test.ts：2次失敗（工具未執行）
  • tool-approval-race-conditions.test.ts：1次失敗（執行計數 = 0）
決策： 獨立域 - 中止邏輯與批處理完成分開，與競爭條件分開
派遣：
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
結果：
  • 代理 1：用基於事件的等待替換逾時
  • Agent 2：修改了事件結構錯誤（threadId 在錯誤的位置）
  • 代理 3：添加等待異步工具執行完成
整合： 所有修復獨立，無衝突，全套綠色
節省時間： 並行解決 3 個問題與順序解決
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 is separate from batch completion, which is separate from race conditions
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 waiting
  • Agent 2: Fixed event structure bug (threadId in wrong place)
  • Agent 3: Added waiting for async tool execution completion
Integration: All fixes are independent, no conflicts, full suite green
Time Saved: Solved 3 problems in parallel vs sequentially

主要優點

Key Benefits

  1. 並行化 - 多項調查同時發生
  2. 焦點 - 每個代理的範圍都很窄，需要追蹤的上下文較少
  3. 獨立 - 代理之間互不幹擾
  4. 速度 - 1 時間內解決 3 個問題
  1. Parallelization - Multiple investigations happen simultaneously
  2. Focus - Each agent has a narrow scope with less context to track
  3. Independence - Agents don't interfere with each other
  4. Speed - Solve 3 problems in the time of 1

確認

Validation

代理返回後：
  1. 查看每個摘要 - 瞭解發生了什麼變化
  2. 檢查衝突 - 代理程式是否編輯了相同的程式碼？
  3. 運行全套 - 驗證所有修復程序是否協同工作
  4. 抽查 - 代理可能會犯系統錯誤
After agents return:
  1. Review Each Summary - Understand what changed
  2. Check for Conflicts - Did agents edit the same code?
  3. Run Full Suite - Verify all fixes work together
  4. Spot Check - Agents can make systematic errors

現實世界的影響

Real-World Impact

來自調試會話（2025-10-03）：
  • 3 個文件 6 次失敗
  • 3名代理並行出動
  • 所有調查同時完成
  • 所有修復均已成功集成
  • 代理變更之間零衝突
From debugging session (2025-10-03):
  • 6 failures across 3 files
  • 3 agents dispatched in parallel
  • All investigations completed simultaneously
  • All fixes successfully integrated
  • Zero conflicts between agent changes