Swarm Orchestration

Swarm is Yukkai's primary strength for decomposable work. Instead of processing tasks sequentially, Swarm launches multiple sub-agents in parallel — each with its own role, prompt, and tool access — then aggregates the results.

The Swarm Lifecycle

create_plan → execute → poll status → get_results → wrap_up

1. Create a Plan

Define a set of tasks, each with a role name and a self-contained prompt:

swarm(action: "create_plan", name: "Refactor Auth", tasks: [
  { agentRoleName: "Architect", prompt: "Analyze the files in src/auth/ and propose a new module structure..." },
  { agentRoleName: "Developer", prompt: "Refactor src/auth/LoginManager.swift to follow the new structure..." },
  { agentRoleName: "Tester", prompt: "Verify src/auth/ tests still pass after the refactor..." }
])

This returns a planId. The plan is created and automatically launched — no separate execute call is needed in most cases.

2. Monitor Progress

swarm(action: "status")

While the plan is running, status shows a compact progress view (pending / running / completed / failed per task). Check approximately every 30 seconds and keep the user informed.

You can also use peek for a quick overview without full detail:

swarm(action: "peek")

3. Retrieve Results

Once status shows all tasks as completed or failed:

swarm(action: "get_results")

This returns the aggregated output of all agents.

4. Wrap Up

swarm(action: "wrap_up")

wrap_up performs the final closeout and synthesis. Do not skip this step — a plan left "completed" without wrap_up has no final synthesis for the user.

5. Retry Failed Tasks

If some tasks failed, you can relaunch just those:

swarm(action: "retry_failed")

Failed agents auto-retry up to 2 times on transient errors (429 rate limit, timeout, network) with exponential backoff (3s, 6s, 12s). Non-retryable errors (413 context too long, 401 auth) fail immediately.

Additional Controls

Action	Description
pause	Suspend execution of the plan
resume	Resume a paused plan
cancel	Cancel the active plan (optionally by planId)

Scale

Yukkai supports up to 100 agents per swarm. Scaling to 20–100 agents for a large project is expected and fine — cost is linear (same total tokens as sequential), but wall-clock time is divided by the number of parallel agents.

Best Practices

• Decompose finely: 1 task = 1 file or 1 clear aspect. Finer decomposition = more effective parallelism.
• End with a Reviewer or Tester role that checks the other agents' work before wrap_up.
• Keep prompts small — limit the prompt size per agent to avoid context overflow.
• Use existing roles via agent_roles(action: "list") rather than inventing generic names when a matching specialized role already exists.

Common Mistakes

• ❌ Writing a task prompt that references main-conversation context — the sub-agent cannot see it.
• ❌ Checking get_results before status shows all tasks completed/failed.
• ❌ Using swarm for a single simple task — use plain agent instead.
• ❌ Forgetting wrap_up — no final synthesis without it.