qwen-code/docs/developers/tools/swarm.md

Swarm Tool (swarm)

Use swarm to run many independent, simple tasks through ephemeral worker agents and return a structured aggregate result to the parent agent.

Swarm is intended for map-reduce style work:

• analyzing many files independently
• processing chunks of a large data file
• running independent searches where the first successful result is enough
• collecting per-item summaries, counts, or validation results

For a few complex role-based tasks, use the task tool instead. For model comparison on the same task, use Agent Arena.

Arguments

• description (string, required): Short description of the overall swarm job.
• tasks (array, required): Independent tasks. Each task becomes one worker.
  • id (string, optional): Stable identifier returned in results.
  • description (string, required): Short per-worker description.
  • prompt (string, required): Complete instructions for the worker.
• mode (wait_all or first_success, optional): Defaults to wait_all.
• max_concurrency (number, optional): Maximum workers to run at once.
• max_turns (number, optional): Maximum model/tool turns per worker. Defaults to 8.
• timeout_seconds (number, optional): Per-worker wall-clock timeout.
• worker_system_prompt (string, optional): Shared worker system prompt.
• allowed_tools (string array, optional): Tool allowlist for workers.
• disallowed_tools (string array, optional): Tools removed from workers.

If max_concurrency is omitted, Qwen Code uses QWEN_CODE_MAX_SWARM_CONCURRENCY, then QWEN_CODE_MAX_TOOL_CONCURRENCY, then 10.

Result

The tool returns JSON to the parent agent with:

• summary.total
• summary.completed
• summary.failed
• summary.cancelled
• summary.notStarted
• results[] with one entry per task, including taskId, status, output or error, duration, and execution stats when available

Individual worker failures do not abort the whole swarm. The parent agent is responsible for reading the aggregate result and presenting the final answer.

Examples

Analyze files in parallel:

swarm(
  description="Extract function names",
  tasks=[
    {
      id="src/a.ts",
      description="Analyze src/a.ts",
      prompt="Read /repo/src/a.ts and return the exported function names."
    },
    {
      id="src/b.ts",
      description="Analyze src/b.ts",
      prompt="Read /repo/src/b.ts and return the exported function names."
    }
  ],
  max_concurrency=10
)

Use first successful result:

swarm(
  description="Find API route definition",
  mode="first_success",
  tasks=[
    {
      description="Search routes directory",
      prompt="Search /repo/src/routes for the user creation route."
    },
    {
      description="Search controllers directory",
      prompt="Search /repo/src/controllers for the user creation route."
    }
  ]
)

Notes

Workers are lightweight and ephemeral: they are spawned, execute one task, return a result, and are cleaned up. Workers cannot spawn further subagents or cron jobs.

Swarm workers run concurrently, so interactive permission prompts are avoided. Permission hooks can still approve actions, and permissive approval modes still apply where configured. Prefer read-only or disjoint file scopes for swarm tasks.