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"	Classification hint. subagent = intended as a task target. primary = intended as the top-level agent. all = both. Runtime behavior depends on how AGENTS.md references the agents.
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	If true, intended to be excluded from the task tool's agent list. Runtime filtering is not guaranteed.

How It Works

1. The orchestrator agent sees the task tool, which can dispatch work to configured sub-agents.
2. When dispatching work, the orchestrator calls task with a prompt and optionally specifies which agent entry to use.
3. The sub-agent runs autonomously in its own session context with its configured model, skills, step budget, and tools.
4. Sub-agents cannot spawn further sub-agents — nesting is limited to one level to prevent runaway recursion.
5. Results flow back to the orchestrator, which can inspect output, verify artifacts, and dispatch the next phase.

Writing Good Orchestrator Instructions

The orchestrator's AGENTS.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. Independent work — like a code review, security audit, and QA testing — runs in parallel:

### 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" },
}

AGENTS.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/.

Depth Guard

By default, sub-agents cannot spawn further sub-agents — the task tool permission is set to deny at depth 1. 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.