Multi-Agent

A single agent can spawn sub-agents via the built-in task tool. This lets you build orchestrators that dispatch specialist agents for different parts of a workflow — research, coding, review, testing — each with its own skills and step budget.

The agent Config Field

Define named agent entries in swarmlord.jsonc. Each entry configures a specialist role:

{
    "name": "my-orchestrator",
    "model": "anthropic/claude-haiku-4.5",
    "tools": {
        "task": true,
        "skill": true,
        // ... other tools
    },
    "agent": {
        "orchestrator": {
            "description": "Dispatches specialist sub-agents, never does heavy work itself",
            "steps": 200,
        },
        "researcher": {
            "description": "Market research specialist — web search, source analysis",
            "mode": "subagent",
            "steps": 75,
        },
        "builder": {
            "description": "Full-stack developer — implements features from a spec",
            "mode": "subagent",
            "model": "anthropic/claude-sonnet-4.6",
            "skills": ["eng-review"],
            "steps": 300,
        },
        "reviewer": {
            "description": "Code review — architecture, quality, security",
            "mode": "subagent",
            "skills": ["review"],
            "steps": 75,
        },
    },
    "permission": { "*": "allow" },
}

Agent Entry Fields

Field	Type	Description
description	string	What this agent does — metadata for documentation and prompt context.
mode	"subagent" | "primary" | "all"	Descriptive hint — does not affect runtime behavior. Orchestration is driven by prompts.
model	string	Override the model for this agent (e.g. use a more capable model for the builder).
steps	number	Maximum tool call steps for this agent.
skills	string[]	Skills available to this agent (by directory name).
tools	Record<string, boolean>	Override tool access for this agent.
temperature	number	Temperature override.
top_p	number	Top-p sampling override.
permission	Record<string, string>	Permission overrides — values are "allow", "deny", or "ask" (e.g. { "*": "allow" }).
hidden	boolean	Descriptive flag for UIs. Does not affect task resolution.

How It Works

1. The orchestrator calls task with a prompt and a subagent_type that maps to a named agent entry (defaults to general).
2. The sub-agent shares the parent's /workspace but runs its own conversation loop with its configured model, skills, step budget, and tools.
3. By default, sub-agents cannot spawn further sub-agents (see Depth Guard). At most 3 run concurrently.
4. Results flow back to the orchestrator. Use workspace files for large outputs (result text is truncated to 12k chars).

Writing Good Orchestrator Instructions

The orchestrator's SOUL.md should define the workflow and dispatch rules. Key patterns:

Be explicit about sequencing

## Workflow

1. Dispatch "researcher" to analyze the market → wait for `market-research.md`
2. Dispatch "builder" with the research results → wait for implementation
3. Dispatch "reviewer" to review the code → wait for `code-review.md`
4. Fix any issues from the review

Provide full context in dispatch prompts

Sub-agents are autonomous — they can't ask the orchestrator clarifying questions. Front-load all decisions:

## Prompt Rules for Sub-Agents

- State the mode explicitly: "Run in startup mode. Target audience: B2B SaaS founders."
- Pre-answer obvious questions: "Goal: MVP. Stage: pre-product. Stack: React + Cloudflare Workers."
- Be directive, not open-ended: "Produce market-research.md covering competitors, pricing, and gaps"
  beats "research this idea."

Verify output before proceeding

## After Each Dispatch

- Check that the expected output file exists
- If missing, re-dispatch with a more specific prompt
- Don't block the entire pipeline on one failure — note it and continue

Parallel Dispatch

The orchestrator can dispatch multiple sub-agents simultaneously by making multiple task tool calls in the same response. At most 3 run concurrently; additional calls wait. (batch cannot invoke task.)

### Quality Phase (PARALLEL)

Dispatch all three in a single response:

- **Code Review** (agent: "reviewer") — reviews all code, produces `code-review.md`
- **Security Audit** (agent: "security") — OWASP/STRIDE analysis, produces `security-audit.md`
- **QA Testing** (agent: "qa") — writes and runs tests, produces `qa-report.md`

Wait for all three to complete before proceeding.

Example: Simple Two-Agent Setup

A minimal orchestrator with one sub-agent:

swarmlord.jsonc:

{
    "name": "research-writer",
    "model": "anthropic/claude-haiku-4.5",
    "tools": { "task": true, "websearch": true, "read": true, "write": true },
    "agent": {
        "orchestrator": {
            "description": "Coordinates research and writing tasks",
            "steps": 100,
        },
        "researcher": {
            "description": "Deep web researcher — finds data, cites sources, produces reports",
            "mode": "subagent",
            "steps": 75,
        },
    },
    "permission": { "*": "allow" },
}

SOUL.md:

# Research Writer

You coordinate research and writing. For research tasks, dispatch the
"researcher" sub-agent. For writing, do it yourself.

## Process

1. When asked to research a topic, dispatch a task to "researcher" with specific
   questions to answer and output file to produce.
2. Read the researcher's output and synthesize it into the final deliverable.
3. Write the result to /workspace/output/.

Task Tool Parameters

The task tool supports several parameters beyond the prompt:

Parameter	Type	Description
description	string	Short description of the task for the sub-agent (required).
subagent_type	string	Agent entry to use (defaults to general). Unknown values fall back to general.
skills	string[]	Load specific skills instead of using a named agent (mutually exclusive with subagent_type).
task_id	string	Stable ID for the subtask (used as session ID, enables resume).
timeout_minutes	number	Timeout in minutes (1–60, default: 30).
output_files	string[]	Glob patterns under /workspace/ to verify. Missing files trigger one auto-retry.
todos	array	Seed todo items for the subtask.

Depth Guard

By default, sub-agents cannot spawn further sub-agents — the task tool permission is set to deny at the maximum configured depth. This prevents runaway recursion.

The depth limit is configurable via maxSubtaskDepth in session config (range: 1–5, default: 1). At the default depth of 1, the orchestrator can dispatch sub-agents, but those sub-agents cannot dispatch their own. Increasing the limit allows deeper delegation chains up to 5 levels.