Parallel agents

Dispatching Parallel Agents

Assign separate agents to independent problem domains simultaneously for faster resolution.

When to Use

• 3+ test failures across different files/subsystems
• Multiple independent tasks that don't share state
• Investigations that won't interfere with each other
• Failures from unrelated root causes

When NOT to Use

• Failures are interconnected
• Tasks share state or create conflicts
• Agents would modify the same files
• You lack context to properly scope tasks

Implementation Steps

1. Group by Domain

Organize failures/tasks into independent categories:

Group A: Authentication tests (3 failures)
Group B: API endpoint tests (2 failures)
Group C: UI component tests (4 failures)

2. Define Focused Tasks

Each agent receives:

Field	Description
Scope	Specific files/tests to focus on
Goal	Clear success criteria
Constraints	What NOT to change
Output	Expected deliverable

3. Dispatch Concurrently

IMPORTANT: Launch all tasks in a single message (no run_in_background). Multiple Task calls in the same message automatically run in parallel, and Claude waits for all to complete.

# All three tasks run in parallel automatically when in the same message
Task(test-engineer, prompt="Fix auth test failures in src/auth/*.test.ts")
Task(test-engineer, prompt="Fix API test failures in src/api/*.test.ts")
Task(frontend-developer, prompt="Fix UI test failures in src/components/*.test.tsx")
# Claude waits for all to complete, then continues

Avoid run_in_background: true unless you need to do other work while waiting. Task IDs must be captured and used within the same response.

4. Integrate Results

1. Review all agent outputs (available after parallel completion)
2. Verify no conflicts between changes
3. Run full test suite
4. Merge changes

Effective Agent Prompts

Good prompt:

Fix the 3 failing tests in src/auth/login.test.ts:
- "should reject invalid email format"
- "should require password min length"
- "should handle network errors"

Error messages attached. Identify root causes - don't just increase timeouts.
Constraints: Don't modify src/api/* files.
Output: Summary of fixes with test results.

Bad prompt:

Fix all the tests

Prompt Template

## Task: [Specific description]

**Scope:** [Files/tests to focus on]

**Failures:**

- [Test name]: [Error message]
- [Test name]: [Error message]

**Goal:** [What success looks like]

**Constraints:**

- Don't modify [files]
- Preserve [behavior]

**Output:**

- Summary of root causes found
- Changes made
- Verification results

Common Pitfalls

Mistake	Problem	Solution
Vague scope	Agent changes wrong files	Specify exact paths
Missing context	Agent can't diagnose	Include error messages
No constraints	Conflicting changes	Define boundaries
Unclear output	Can't verify success	Specify deliverables

Benefits

• Reduces investigation time through parallelization
• Each agent maintains narrow focus
• Minimizes cross-agent interference
• Solves multiple problems concurrently

Background Execution

For long-running tasks where you need to continue working, use run_in_background: true.

Pattern: Background + Foreground

# Long-running audit in background
audit_task = Task(security-auditor,
  prompt="Full security audit",
  run_in_background: true)

# Continue with implementation work
Task(frontend-developer, prompt="Build login form")

# Later, get audit results
TaskOutput(audit_task.id, block: true)

Pattern: Multiple Background Tasks

# Launch multiple background tasks
task1 = Task(test-engineer, prompt="...", run_in_background: true)
task2 = Task(code-reviewer, prompt="...", run_in_background: true)

# Do other work...

# Collect all results
result1 = TaskOutput(task1.id, block: true)
result2 = TaskOutput(task2.id, block: true)

When to Use Background vs Foreground

Scenario	Mode	Why
Quick tasks (< 1 min)	Foreground	Simpler, immediate results
Long audit/analysis	Background	Continue working
Multiple independent tasks	Foreground (parallel)	Auto-waits for all
Security + Implementation	Background + Foreground	Overlap work

Important Notes

• Task IDs are only valid within the same response
• Always use block: true when retrieving results with TaskOutput
• Prefer foreground parallel (single message, multiple Tasks) when possible
• Background tasks should be collected before the response ends