Subagents

A subagent is a complete agent folder nested inside another agent. maiden loads it recursively and exposes it to the parent as a single tool — so the parent model can delegate a whole sub-task to a specialized agent with its own instructions, model, and tools.

Add a subagent

Create a subdirectory under subagents/, and put a full agent folder inside it:

my-agent/
  agent.toml
  instructions.md
  subagents/
    researcher/
      agent.toml
      instructions.md
      tools/
        search.wasm

The subdirectory name (researcher) becomes the name of the tool the parent sees. The parent’s model calls it like any other tool, passing a message; the subagent runs its own loop and returns its answer.

Each subagent is its own agent

A subagent is not a lightweight config — it is a real agent:

• It has its own agent.toml, so it can use a different model from its parent. A --model override on the parent does not propagate into subagents; each keeps the model in its own file.
• It has its own tools, skills, and even its own subagents — nesting is recursive.
• It has its own durable state, stored under the parent’s state directory at subagents/<name>/.

Why nest agents

Subagents let you decompose a problem without inflating one giant system prompt. A parent can stay a thin router — “when the user asks for research, call researcher” — while each subagent stays focused, with only the tools and instructions its narrow job needs. Because a subagent is just a Tool to its parent (see architecture), the parent loop treats it identically to a WASM tool or an MCP tool.

Run it

Nothing special is required — load and run the parent, and the subagent is available as a tool:

maiden run my-agent "research the history of the espresso machine" --mock