What would you like to be added?

Agent Swarm is a parallel execution feature that allows the main agent to dynamically spawn multiple lightweight worker agents on-the-fly to process simple tasks in parallel. Unlike pre-defined subagents, Swarm workers are created dynamically at runtime based on the task requirements, execute independently, and return results for aggregation.

Why is this needed?

Current Pain Points

1. Pre-definition overhead: Current subagents require upfront definition and configuration before use, creating friction for ad-hoc parallel tasks
2. Limited scalability: Pre-defined subagents are designed for specific roles, making it awkward to spawn 10+ temporary workers for batch processing
3. Static structure: Existing patterns don't support dynamic worker creation where the number and type of workers depend on runtime data

Expected Value

1. Ad-hoc parallelization: Dynamically spawn workers as needed without pre-configuration
2. Massive parallelism: Efficiently handle batch operations by spawning dozens of lightweight workers
3. Runtime adaptability: Create workers based on actual data size or complexity discovered during execution
4. Simplified workflow: No need to define roles upfront; just spawn workers and aggregate results

Core Requirements

1. Dynamic Worker Spawning

Allow main agent to create workers on-the-fly without pre-definition.

• Spawn workers dynamically at runtime via tool calls (e.g., spawn_swarm_worker)
• No pre-configuration or role definition required
• Specify task description per worker at spawn time
• Support spawning N workers where N is determined at runtime

2. Lightweight Execution Context

Workers should be lightweight and fast to spawn.

• Minimal initialization overhead compared to full agent sessions
• Isolated but lightweight context per worker
• Workers execute a single task and return (ephemeral lifecycle)
• No long-running state or complex coordination needed

3. Parallel Execution and Aggregation

Execute workers in parallel and collect their results.

• Workers run concurrently without blocking each other
• Results collected and returned to parent agent for aggregation
• Support both "wait for all" and "first result wins" patterns
• Error handling for individual worker failures without affecting others

4. Runtime-Determined Scaling

Number of workers determined by runtime conditions.

• Spawn workers based on data size (e.g., one worker per file, per row, per chunk)
• Dynamically adjust parallelism based on task characteristics
• No hardcoded limits; scale up/down based on actual needs

5. Simple Communication Pattern

Straightforward one-way result flow.

• Workers execute task and return result to parent
• No inter-worker communication (pure parallel map-reduce pattern)
• Parent agent responsible for result aggregation and next steps
• Optional progress tracking for long-running batch operations

Additional context

User Entry Point Examples

I have 50 files to analyze. Spawn a swarm of workers, one per file,
to extract the function names from each file in parallel.

Process this large CSV by spawning 10 workers, each handling a chunk of rows.
Aggregate the error counts from all workers when done.

Acceptance Criteria

• Main agent can dynamically spawn multiple workers without pre-definition
• Workers execute in parallel with isolated lightweight contexts
• Results from all workers are aggregated and returned to parent
• Number of workers can be determined at runtime based on data/task
• Individual worker failures don't cascade to other workers or parent
• Workers have ephemeral lifecycle (spawn → execute → return → cleanup)

Key Differences vs. Related Features