Swarm Tool

What is it?

The Swarm Tool is Yukkai's built-in orchestration system for running many AI sub-agents in parallel. Instead of asking one agent to work through a huge task step by step, you split the task into smaller pieces and assign each piece to its own agent. All agents work at the same time, dramatically reducing total completion time while costing the same in API usage.

Think of it like a project manager who delegates tasks to a team of specialists: each team member handles their own assignment simultaneously, and you collect the results when everyone is done.

How it works

The swarm follows a simple three-step lifecycle:

1. Create a plan — You give the swarm a name and a list of tasks. Each task specifies an agent role (the type of specialist) and a prompt (the instructions for that agent). The plan is created and launched automatically — no separate execution step needed.
2. Monitor progress — While the swarm is running, you can check the status at any time. While agents are still working, you get a short progress summary. Once all agents finish, status automatically returns the full results.
3. Collect and assemble — When the plan completes, all agent outputs are returned together. If any agents failed, you can retry them with their original prompts without relaunching the entire swarm.

Auto-retry

Agents automatically retry up to 2 times on transient errors like rate limits (429), timeouts, or network issues. The backoff between retries follows an exponential schedule: 3 seconds, then 6 seconds, then 12 seconds. Non-retryable errors (such as context too long or authentication failures) fail immediately without retrying.

How to use it

Step 1: Create a plan

Define a name for your plan and a list of tasks. Each task needs an agent role name and a prompt:

create_plan(
  name: "Analyze 5 projects",
  tasks: [
    { agentRoleName: "code-reviewer", prompt: "Review the code in /src/project-A and summarize issues" },
    { agentRoleName: "code-reviewer", prompt: "Review the code in /src/project-B and summarize issues" },
    { agentRoleName: "code-reviewer", prompt: "Review the code in /src/project-C and summarize issues" },
    { agentRoleName: "code-reviewer", prompt: "Review the code in /src/project-D and summarize issues" },
    { agentRoleName: "code-reviewer", prompt: "Review the code in /src/project-E and summarize issues" }
  ]
)

The plan is created and immediately launched. You receive a plan ID you can use to track progress.

Step 2: Check status

Poll the status to see how things are going:

status()

While agents are still running, you get a compact progress view:

Plan: "Analyze 5 projects"
Status: running
Progress: 3/5 agents completed

When the plan finishes, status automatically returns the full output from every agent.

Step 3: Retry failures (if needed)

If some agents failed or were cancelled, retry them without restarting the whole plan:

retry_failed()

Each failed agent is relaunched with its original prompt and role.

Step 4: Cancel (optional)

If you need to stop a running plan early:

cancel(planId: "your-plan-id")

Examples

Example 1: Multi-file documentation

Generate documentation for every source file in a project, one agent per file:

create_plan(
  name: "Doc sprint",
  tasks: [
    { agentRoleName: "writer", prompt: "Write API docs for src/auth.swift" },
    { agentRoleName: "writer", prompt: "Write API docs for src/models.swift" },
    { agentRoleName: "writer", prompt: "Write API docs for src/networking.swift" },
    { agentRoleName: "writer", prompt: "Write API docs for src/database.swift" },
    { agentRoleName: "writer", prompt: "Write API docs for src/ui.swift" }
  ]
)

Example 2: Research across multiple sources

Have different agents research different topics in parallel:

create_plan(
  name: "Market research",
  tasks: [
    { agentRoleName: "researcher", prompt: "Research competitors in the fitness app space" },
    { agentRoleName: "researcher", prompt: "Research pricing models for subscription apps" },
    { agentRoleName: "researcher", prompt: "Research user onboarding best practices" },
    { agentRoleName: "researcher", prompt: "Research app store optimization strategies" }
  ]
)

Example 3: Batch content creation

create_plan(
  name: "Blog batch",
  tasks: [
    { agentRoleName: "copywriter", prompt: "Write a blog post about SwiftUI tips" },
    { agentRoleName: "copywriter", prompt: "Write a blog post about Combine framework" },
    { agentRoleName: "copywriter", prompt: "Write a blog post about Core Data migrations" },
    { agentRoleName: "copywriter", prompt: "Write a blog post about XCTest best practices" }
  ]
)

Tips & best practices

• One task per unit of work — Assign one agent per file, per module, or per category. This maximizes parallelism and keeps each agent focused.
• Scale up freely — For large tasks, use 10, 50, or even 100+ agents. The swarm is designed to handle it.
• Same cost, faster results — The swarm costs the same in total tokens as doing the work sequentially — it's just much faster because everything runs in parallel.
• Let status do the work — When the plan completes, status automatically returns full results. You don't need a separate get_results call in most cases.
• Use get_results only when needed — Call get_results to force-retrieve results if you want to wait up to 5 minutes for a still-running plan to finish.
• Retry smartly — If a few agents fail, use retry_failed to relaunch only those agents. You don't need to recreate the entire plan.
• Cancel to save resources — If you realize a plan isn't going the right direction, cancel it early rather than waiting for all agents to finish.
• Choose the right agent role — Each task can use a different agent role. Match the role's specialty to the task at hand (e.g., code-reviewer for reviews, writer for documentation, researcher for research).