FilesSDKFilesystem
FilesSDK が対応する任意のストレージバックエンドにファイルを保存します。FilesSDK は S3、Cloudflare R2、Google Cloud Storage、Azure Blob、Vercel Blob、MinIO、ローカル Filesystem などを統一的に抽象化します。インターフェースの詳細は、WorkspaceFilesystem インターフェースを参照してください。
同じコードで複数のストレージバックエンドを扱う単一のアダプターが必要な場合は、FilesSDKFilesystem を使用します。Workspace の設定を変えずに、基盤となるドライバーを切り替えられます。対象が1つのバックエンドのみで、そのバックエンド専用のオプションが必要な場合は、専用 Provider（S3Filesystem や GCSFilesystem など）を推奨します。
インストールインストールへの直接リンク
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/files-sdk files-sdk
pnpm add @mastra/files-sdk files-sdk
yarn add @mastra/files-sdk files-sdk
bun add @mastra/files-sdk files-sdk
files-sdk は peer dependency であり、使用するアダプターとともに設定します。
使用方法使用方法への直接リンク
任意のアダプターを指定して FilesSDK の Files インスタンスを作成し、FilesSDKFilesystem へ渡します。
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { FilesSDKFilesystem } from '@mastra/files-sdk'
import { Files } from 'files-sdk'
import { s3 } from 'files-sdk/s3'
const files = new Files({
adapter: s3({
bucket: 'my-bucket',
region: 'us-east-1',
}),
})
const workspace = new Workspace({
filesystem: new FilesSDKFilesystem({ files }),
})
const agent = new Agent({
id: 'file-agent',
name: 'file-agent',
model: 'anthropic/claude-opus-4-7',
workspace,
})
アダプターを切り替えるアダプターを切り替えるへの直接リンク
同じ FilesSDKFilesystem を任意の FilesSDK アダプターで使用できます。バックエンドを切り替えるには、ドライバーファクトリーを置き換えます。
import { Files } from 'files-sdk'
import { r2 } from 'files-sdk/r2'
import { gcs } from 'files-sdk/gcs'
import { azure } from 'files-sdk/azure'
import { fs } from 'files-sdk/fs'
// Cloudflare R2
const r2Files = new Files({ adapter: r2({ accountId, bucket, accessKeyId, secretAccessKey }) })
// Google Cloud Storage
const gcsFiles = new Files({ adapter: gcs({ bucket, projectId }) })
// Azure Blob
const azureFiles = new Files({ adapter: azure({ container, connectionString }) })
// Local filesystem (useful for tests and development)
const localFiles = new Files({ adapter: fs({ root: './workspace' }) })
アダプターの完全なカタログと設定オプションは、FilesSDK ドキュメントを参照してください。
読み取り専用マウント読み取り専用マウントへの直接リンク
const filesystem = new FilesSDKFilesystem({
files,
readOnly: true,
})
すべての書き込み操作（writeFile、appendFile、deleteFile、copyFile、moveFile、mkdir、rmdir）は WorkspaceReadOnlyError をスローし、読み取り操作は成功します。
コンストラクターパラメーターコンストラクターパラメーターへの直接リンク
files:
Files インスタンス。id?:
displayName?:
icon?:
description?:
readOnly?:
プロパティプロパティへの直接リンク
id:
name:
provider:
readOnly:
メソッドメソッドへの直接リンク
FilesSDKFilesystem は WorkspaceFilesystem インターフェースを実装し、標準の Filesystem メソッドをすべて提供します。
readFile(path, options?)- ファイルの内容を読み取りますwriteFile(path, content, options?)- ファイルに内容を書き込みますappendFile(path, content)- ファイルに内容を追記しますdeleteFile(path, options?)- ファイルを削除しますcopyFile(src, dest, options?)- ファイルをコピーしますmoveFile(src, dest, options?)- ファイルを移動または名前変更しますmkdir(path, options?)- ディレクトリを作成（オブジェクトストアでは何もしません）rmdir(path, options?)- ディレクトリを削除しますreaddir(path, options?)- ディレクトリの内容を一覧表示しますexists(path)- パスが存在するか確認しますstat(path)- ファイルまたはディレクトリのメタデータを取得します
init()initへの直接リンク
Filesystem を初期化します。指定された認証情報で、設定済みアダプターがキーを一覧表示できることを確認します。
await filesystem.init()
getInfo()getinfoへの直接リンク
この Filesystem インスタンスのメタデータを返します。
const info = filesystem.getInfo()
// { id: '...', name: 'FilesSDKFilesystem', provider: 'files-sdk', status: 'ready' }
filesfilesへの直接リンク
アダプター固有の API を直接呼び出せるよう、基盤となる FilesSDK の Files インスタンスが public プロパティとして公開されます。
const url = await filesystem.files.url('reports/q3.pdf')
オブジェクトストアのセマンティクスオブジェクトストアのセマンティクスへの直接リンク
FilesSDKFilesystem は、基盤となるアダプターが階層型（fs など）でも、設定されたバックエンドをオブジェクトストアとして扱います。これにより、アダプター間で動作が統一されます。
mkdirは何もしません。その接頭辞を持つキーが存在すると、ディレクトリも暗黙的に存在します。existsがtrueを返すのは、完全一致するキーがファイルとして存在する場合、またはパスが1つ以上の子キーを含む接頭辞である場合だけです。階層型アダプターに残った空のディレクトリは対象外です。deleteFileは、{ force: true }を渡さない限り、キーが存在しない場合にFileNotFoundErrorをスローします。- ディレクトリに対する
deleteFileは、S3FilesystemおよびGCSFilesystemと同様に、rmdir({ recursive: true })へ処理を委譲します。 moveFileはcopyFileの後にdeleteFileを実行する形で実装されており、アトミックではありません。コピーの成功後にコピー元の削除が失敗すると、コピー先は残り、コピー元も削除されません。appendFileは読み取り、変更、書き込みを行う操作です。同じキーへの同時追記は互いに上書きする可能性があります。これはオブジェクトストレージ固有の性質であり、FilesSDK に限ったものではありません。readdir({ recursive: true })は中間ディレクトリのエントリも返します（たとえば、a/b/c.txtとともにa/bも返します）。