Subagents

A file-based agent can declare subagents, specialist child agents it delegates to. The parent model sees each subagent as a delegation tool named after the subagent directory, calls that tool to hand off a task, and receives the subagent's result back in the parent conversation.

Use this page for the file-based convention. For broader delegation patterns, hooks, memory isolation, tool approval propagation, and scoring, see Supervisor agents.

Quickstart

Declare one directory per subagent under subagents/:

Subagent layout

src/mastra/agents/
└── supervisor/
    ├── config.ts
    ├── instructions.md
    └── subagents/
        └── researcher/
            ├── config.ts
            ├── instructions.md
            └── tools/
                └── search.ts

Mastra assembles researcher as its own agent and wires it into the supervisor's agents map. The parent model can delegate to it by using the generated researcher delegation tool.

A subagent's config.ts must set a non-empty description. The parent model reads this when deciding whether to delegate.

src/mastra/agents/supervisor/subagents/researcher/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.5',
  description: 'Researches a topic and returns cited findings.',
})

How the model delegates

A subagent's description is routing text for the parent model. Write it like a tool description: explain what the subagent does and when to delegate to it.

The build fails when a discovered subagent doesn't provide a non-empty description.

Isolation

Subagents are isolated. A subagent doesn't inherit its parent's tools, skills, workspace, memory, processors, or subagents. Each child is a self-contained agent with its own directory.

If multiple agents should share the same dependency, define it in code and assign it through each agent's config.

Nesting

Subagents can declare their own subagents/ directories, nesting up to three levels below the top-level agent. A subagents/ directory nested deeper is ignored with a warning.

Nested subagents

src/mastra/agents/
└── supervisor/            # depth 0
    └── subagents/
        └── researcher/    # depth 1
            └── subagents/
                └── summarizer/ # depth 2

Naming rules

• A subagent id that collides with one of the parent's tool keys is a build error.
• A duplicate subagent id under the same parent is a build error.
• If a subagent id also exists in the parent's config.agents, the config.agents entry wins and logs a warning.
• If config.agents is a function, discovered subagents are ignored with a warning because they can't be statically merged.

Example

This supervisor coordinates a research-and-writing flow. The researcher subagent owns search tools, while the writer subagent owns a workspace for drafting files.

Research supervisor

src/mastra/agents/
└── research-supervisor/
    ├── config.ts
    ├── instructions.md
    └── subagents/
        ├── researcher/
        │   ├── config.ts
        │   ├── instructions.md
        │   └── tools/
        │       └── search_web.ts
        └── writer/
            ├── config.ts
            ├── instructions.md
            └── workspace/
                └── draft-template.md

src/mastra/agents/research-supervisor/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.5',
})

src/mastra/agents/research-supervisor/instructions.md

You coordinate research and writing.

Delegate fact gathering to `researcher`. Delegate final drafting to `writer`.

src/mastra/agents/research-supervisor/subagents/researcher/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5-mini',
  description: 'Use to gather facts, sources, and concise research notes for a topic.',
})

src/mastra/agents/research-supervisor/subagents/writer/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.5',
  description: 'Use to turn research notes into a structured draft.',
})