swarm-spawning

Swarm Spawning

How to create agents -- subagent vs teammate, agent type catalog, backend selection.

---

Two Ways to Spawn Agents

Method 1 -- Task Tool (Subagents)

Use Task for short-lived, focused work that returns a result:

Agent({
  subagent_type: "Explore",
  description: "Find auth files",
  prompt: "Find all authentication-related files in this codebase",
  model: "haiku"  // Optional: haiku, sonnet, opus
})

Characteristics:

• Runs synchronously (blocks until complete) or async with run_in_background: true
• Returns result directly to you
• No team membership required
• Best for searches, analysis, focused research

Method 2 -- Task Tool + team_name + name (Teammates)

Use Task with team_name and name to spawn persistent teammates:

// First create a team
TeamCreate({ team_name: "my-project" })

// Then spawn a teammate into that team
Agent({
  team_name: "my-project",        // Required -- which team to join
  name: "security-reviewer",      // Required -- teammate's name
  subagent_type: "general-purpose",
  prompt: "Review all authentication code for vulnerabilities. Send findings to team-lead.",
  run_in_background: true         // Teammates usually run in background
})

Characteristics:

• Joins team, appears in config.json
• Communicates via SendMessage
• Can claim tasks from shared task list
• Persists until shutdown
• Best for parallel work, ongoing collaboration, pipeline stages

Choosing Between Subagent and Teammate

flowchart TD
    Start([Need to spawn an agent]) --> Q1{Does the agent need to collaborate with others?}
    Q1 -->|No -- independent work| Sub[Task subagent<br/>Returns result directly]
    Q1 -->|Yes -- team coordination| Q2{Does it need shared task list?}
    Q2 -->|Yes| Team[Task + team_name + name<br/>Full teammate]
    Q2 -->|No -- just messaging| Team
    Sub --> Done([Agent spawned])
    Team --> Done

• Subagent -- lifespan until task complete, communication via return value, no task access, no team membership
• Teammate -- lifespan until shutdown requested, communication via inbox messages, shared task list access, team membership, ongoing coordination