4.1 KiB
| name | description |
|---|---|
| dispatching-parallel-agents | Fan work out to multiple sub-agents at once when a task splits into 2+ independent pieces with no shared state or ordering dependency - auditing several modules, researching unrelated questions, or applying the same change across separate files. Covers agent prompt structure, common mistakes, and verifying results after agents return. Triggers: do these in parallel, spin up agents, run these at once, split this work, parallelize this. |
Delegate tasks to specialized agents with isolated context. By precisely crafting their instructions and context, you ensure they stay focused and succeed. They should never inherit your session's context or history — construct exactly what they need. This also preserves your own context for coordination work.
When you have multiple unrelated failures (different test files, different subsystems, different bugs), investigating them sequentially wastes time. Each independent investigation can happen in parallel.
Core principle: dispatch one agent per independent problem domain. Let them work concurrently.
When to Use
Use when: 3+ things are failing with different root causes, multiple subsystems are broken independently, each problem can be understood without context from the others, and there's no shared state between investigations. Don't use when: failures are related (fixing one might fix others), you need to understand full system state first, or agents would interfere with each other (editing the same files/resources).
The Pattern
- Identify independent domains — group failures by what's broken (e.g. File A tests: tool approval flow; File B tests: batch completion; File C tests: abort functionality). Confirm they're truly independent — fixing one doesn't affect another.
- Create focused agent tasks — each agent gets: a specific scope (one file/subsystem), a clear goal, explicit constraints ("don't change other code"), and an expected output format (a summary of what was found/fixed).
- Dispatch in parallel — issue all agent dispatches in the SAME response/turn. Multiple dispatch calls in one response run in parallel; one per response runs sequentially.
- Review and integrate — read each summary, verify fixes don't conflict, run the full test suite, integrate all changes.
Agent Prompt Structure
Good prompts are: focused (one clear problem domain), self-contained (all context needed to understand the problem, e.g. paste the actual error messages and test names), and specific about the expected output (what should the agent return).
Example of a focused, well-scoped prompt: "Fix the 3 failing tests in src/agents/agent-tool-abort.test.ts: [list the specific failing assertions]. These are timing/race condition issues. Read the test file, identify root cause (timing vs actual bug), fix by replacing arbitrary timeouts with event-based waiting or fixing the actual bug — do NOT just increase timeouts. Return: summary of what you found and fixed."
Common Mistakes
Too broad ("fix all the tests" — agent gets lost) vs specific ("fix agent-tool-abort.test.ts"). No context ("fix the race condition") vs context (paste the actual error messages/test names). No constraints (agent might refactor everything) vs constraints ("do NOT change production code" / "fix tests only"). Vague output ("fix it") vs specific ("return summary of root cause and changes").
When NOT to Use
Related failures where fixing one might fix others — investigate together first. Situations needing full system context to understand. Exploratory debugging where you don't yet know what's broken. Shared state where agents would interfere with each other.
Verification After Agents Return
- Review each summary — understand what changed.
- Check for conflicts — did agents edit the same code?
- Run the full test suite — verify all fixes work together.
- Spot check — agents can make systematic errors; don't rubber-stamp.
Key Benefits
Parallelization (multiple investigations run simultaneously), focus (each agent has a narrow scope, less context to track), independence (agents don't interfere), speed (N problems solved in roughly the time of 1).