Sub-Agents

The subagents server lets one agent delegate work to other configured agents. Each sub-agent resolves its own model, prompts, MCP sources, and tool filters from settings.json.

Configuration

.aether/mcp.json

{
  "servers": {
    "subagents": {
      "type": "in-memory",
      "args": ["--project-root", "."]
    }
  }
}

--project-root loads .aether/settings.json from that directory. --dir is accepted as an alias. When omitted, the built-in in-memory server uses the workspace root; the standalone mcp-servers-stdio --server subagents binary defaults to the current directory.

Available sub-agents

Only agents with agentInvocable: true can be spawned. The server advertises available sub-agents in its MCP instructions so the parent agent can choose from the registered names.

.aether/settings.json

{
  "agents": [
    {
      "name": "Coder",
      "description": "General coding agent",
      "model": "anthropic:claude-sonnet-4-5-20250929",
      "userInvocable": true,
      "agentInvocable": true,
      "prompts": [".aether/CODER.md"],
      "mcps": [".aether/mcp.json"]
    },
    {
      "name": "Explorer",
      "description": "Read-only codebase exploration agent",
      "model": "deepseek:deepseek-v4-flash",
      "agentInvocable": true,
      "prompts": [".aether/agents/explorer/EXPLORER.md"],
      "mcps": [".aether/agents/explorer/mcp.json"],
      "tools": {
        "allow": [
          "coding__read_file",
          "coding__find",
          "coding__grep",
          "coding__lsp_*"
        ]
      }
    }
  ]
}

Tool filters use exact tool names or a trailing * prefix match. For example, coding__lsp_* is valid.

Tools

Tool	Description
spawn_subagent	Spawn all requested agents concurrently. Wait for results by default, or run as an MCP Task.

Example

spawn_subagent

{
  "tasks": [
    {
      "agentName": "Explorer",
      "prompt": "Find all public API routes and summarize the routing structure."
    },
    {
      "agentName": "Explorer",
      "prompt": "Read the settings loader and document merge behavior."
    }
  ]
}

spawn_subagent waits for the whole batch by default, so the parent receives all results before its next reasoning step. All children run concurrently, and the output contains one result per input task in input order. Rich child progress may be displayed while the call runs.

For independent work that can complete later, set runInBackground: true at the top level. The call then immediately returns one MCP Task for the whole batch. Background mode requires MCP Tasks support; cancelling the task stops all remaining agents, and its completed payload has the same shape as the foreground response.

The result payload is:

{
  "results": [
    {
      "taskId": "task_0",
      "agentName": "Explorer",
      "status": "success",
      "output": "...",
      "error": null
    }
  ],
  "successCount": 1,
  "errorCount": 0
}

agent_name is accepted as an input alias for agentName.

Structured handoff

Aether appends structured-output instructions to each sub-agent prompt. Agents are asked to return JSON with:

Field	Description
summary	Brief summary of what the agent accomplished.
artifacts	Files or resources read, modified, discovered, or relevant.
decisions	Key findings, decisions, or conclusions.
nextSteps	Recommended follow-up tasks.
details	Optional expanded detail.

Each result’s output contains the sub-agent’s raw final output string. Parent agents should parse or summarize it before continuing.

Failure modes

• Clients that do not advertise MCP Tasks support can use foreground mode but cannot set runInBackground: true.
• If a background batch task is cancelled, all remaining child execution is stopped.
• If no agentInvocable agents are registered and tasks are requested, the tool returns an error before creating a task and should not be retried until configuration changes.
• If a named agent is missing or not agentInvocable, that task result is returned with status: "error".
• Empty tasks returns an empty result set.