@mastra/core/dist/docs/references/reference-file-based-agents-subagents.md

> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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 and calls that tool to hand off a task. The subagent's result returns to 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](https://mastra.ai/docs/capabilities/subagents).

## Quickstart

Declare one directory per subagent under `subagents/`:

```text
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.

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

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
  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](https://mastra.ai/reference/file-based-agents/tools): 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.

```text
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.

```text
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
```

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

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})
```

```markdown
You coordinate research and writing.

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

```typescript
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.',
})
```

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

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