Filesystem

追加バージョン: @mastra/core@1.1.0

Filesystem Provider を使用すると、Agent はファイルの読み取り、書き込み、管理を行えます。Workspace に Filesystem を設定すると、Agent にファイル操作用の Tool が提供されます。

Filesystem Provider は、Workspace のすべてのファイル操作を処理します。

• 読み取り - ファイルの内容を読み取ります
• 書き込み - ファイルを作成、更新します
• 一覧表示 - オプションの glob パターンによる絞り込みを使用してディレクトリを参照します
• 削除 - ファイルとディレクトリを削除します
• Stat - ファイルのメタデータを取得します
• コピー/移動 - 場所をまたいでファイルをコピーまたは移動します
• Grep - 正規表現パターンを使用してファイルの内容を検索します

サポートされている Provider

利用可能な Provider は次のとおりです。

• LocalFilesystem: ディスク上のディレクトリにファイルを保存します
• S3Filesystem: Amazon S3 または S3 互換ストレージ（R2、MinIO、Tigris）にファイルを保存します
• GCSFilesystem: Google Cloud Storage にファイルを保存します
• PlatformFilesystem: Mastra Platform の Workspace バケットにファイルを保存します
• GoogleDriveFilesystem: Google Drive フォルダー内にファイルを保存します
• AzureBlobFilesystem: Azure Blob Storage にファイルを保存します
• FilesSDKFilesystem: 任意の FilesSDK アダプター（S3、R2、GCS、Azure Blob、Vercel Blob、ローカル Filesystem など）にファイルを保存します。1 つの Provider で複数のバックエンドを対象にする場合に便利です
• AgentFSFilesystem: AgentFS を介して Turso/SQLite データベースにファイルを保存します
• MesaFilesystem: バージョン管理された Mesa リポジトリにファイルを保存します
• ArchilFilesystem: Archil の柔軟なサーバーレスディスクにファイルを保存します

ヒント

LocalFilesystem は外部サービスを必要としないため、最も簡単に使い始められます。クラウドストレージには、S3Filesystem、GCSFilesystem、または AzureBlobFilesystem を使用してください。バージョン管理されたストレージには MesaFilesystem を使用します。外部サービスを必要としないデータベースベースのストレージには、AgentFSFilesystem を使用してください。

基本的な使い方

Filesystem を設定した Workspace を作成し、Agent に割り当てます。これにより、Agent はタスクの一環としてファイルを読み取り、書き込み、管理できます。

src/mastra/agents/file-agent.ts

import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
  }),
})

const agent = new Agent({
  id: 'file-agent',
  model: 'openai/gpt-5.6-sol',
  instructions: 'You are a helpful file management assistant.',
  workspace,
})

// The agent now has filesystem tools available
const response = await agent.generate('List all files in the workspace')

アクセス範囲の制限

デフォルトでは、LocalFilesystem は contained モードで実行され、すべてのファイル操作が basePath 内に制限されます。これにより、パストラバーサル攻撃やシンボリックリンクを介した範囲外へのアクセスを防止できます。

contained モードでは次のように動作します。

• 相対パス（例: src/index.ts）は basePath を基準に解決されます
• 絶対パス（例: /home/user/.config/file.txt）は実際の Filesystem パスとして扱われます。basePath とすべての allowedPaths の外部にある場合は、PermissionError がスローされます
• チルダパス（例: ~/Documents）はホームディレクトリに展開され、同じアクセス範囲のルールが適用されます

Agent が basePath 外の特定のパスにアクセスする必要がある場合は、contained モードを完全に無効にせずにアクセスを許可できる allowedPaths を使用します。相対パスは basePath を基準に解決され、絶対パスはそのまま使用されます。

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    allowedPaths: ['~/.claude/skills', '../shared-data'],
  }),
})

許可するパスは、setAllowedPaths() メソッドを使用して実行時に更新できます。

// Add a path dynamically
workspace.filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents'])

これは最小権限でアクセスさせるために推奨される方法です。Agent は許可した特定のディレクトリにのみアクセスできます。

Agent が Filesystem 全体に無制限でアクセスする必要がある場合は、contained モードを無効にします。

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    contained: false,
  }),
})

contained が false の場合、絶対パスは制限なしで実際の Filesystem パスとして扱われます。

動的 Filesystem

filesystem オプションには、静的インスタンスの代わりにリゾルバー関数を指定できます。リゾルバーは requestContext を受け取り、リクエストごとに Filesystem を返します。これにより、1 つの Workspace で呼び出し元の ID、ロール、テナントに応じて異なる Filesystem を提供できます。

src/mastra/workspaces.ts

import { Agent } from '@mastra/core/agent'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const workspace = new Workspace({
  filesystem: ({ requestContext }) => {
    const role = requestContext.get('agent-role') || 'guest'
    return new LocalFilesystem({
      basePath: `/workspaces/${role}`,
      readOnly: role !== 'admin',
    })
  },
})

const agent = new Agent({
  id: 'multi-role-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
})

各リクエストでは、Workspace Tool と Workspace instructions に使用する Filesystem が個別に解決されます。

import { RequestContext } from '@mastra/core/request-context'

// Admin request — reads and writes from /workspaces/admin/
const adminCtx = new RequestContext([['agent-role', 'admin']])
await agent.generate('Write report.txt with Q4 results', { requestContext: adminCtx })

// Viewer request — reads from /workspaces/viewer/, writes are blocked
const viewerCtx = new RequestContext([['agent-role', 'viewer']])
await agent.generate('Read info.txt', { requestContext: viewerCtx })

Workspace instructions は同じ requestContext を使用するため、Agent は解決された Provider の Filesystem コンテキストを認識できます。

リゾルバーは非同期にすることもできます。たとえば、データベースから設定を取得できます。

const workspace = new Workspace({
  filesystem: async ({ requestContext }) => {
    const tenantConfig = await db.getTenant(requestContext.get('tenant-id'))
    return new LocalFilesystem({ basePath: tenantConfig.storagePath })
  },
})

注記

filesystem と mounts は同時に使用できません。同じ Workspace でリゾルバー関数と mounts を併用することはできません。

読み取り専用モード

Agent がファイルを変更できないようにするには、読み取り専用モードを有効にします。

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    readOnly: true,
  }),
})

静的 Filesystem では、書き込み Tool（write_file、edit_file、delete、mkdir）が Agent の Tool セットから完全に除外されます。Agent は引き続きファイルの読み取りと一覧表示を行えます。

動的 Filesystem を使用する場合、readOnly の値はリゾルバーが実行されるまで不明なため、書き込み Tool は常に含まれます。代わりに書き込み操作は実行時にブロックされ、解決された Filesystem が読み取り専用の場合は Tool がエラーを返します。

マウントと CompositeFilesystem

Workspace で mounts オプションを使用すると、Mastra はパスのプレフィックスに基づいてファイル操作を適切な Provider に振り分ける CompositeFilesystem を作成します。

import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
    '/skills': new GCSFilesystem({
      bucket: 'agent-skills',
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})

この設定では、次のように動作します。

• read_file('/data/input.csv') は S3 バケットから読み取ります
• write_file('/skills/guide.md', content) は GCS バケットに書き込みます
• list_directory('/') は /data と /skills の仮想エントリを返します
• Sandbox 内のコマンドは、FUSE マウントを介して /data と /skills のファイルにアクセスできます

パスのルーティング

パスがマウントのプレフィックスと一致しない場合は操作が失敗するため、すべてのファイルパスをマウントのプレフィックスで始める必要があります。ルートディレクトリ（/）の一覧を表示すると、各マウントポイントの仮想ディレクトリエントリが返されます。

マウントパスはネストできません。たとえば、/data と /data/sub の両方にマウントすることはできません。

filesystem と mounts の比較

filesystem と mounts は、Workspace で同時に使用できないオプションです。

• ストレージ Provider が 1 つで、Sandbox にマウントする必要がない場合は filesystem を使用します。Agent には Provider を直接操作するファイル Tool が提供されます。
• Sandbox 内からクラウドストレージにアクセスする必要がある場合や、複数の Provider を組み合わせる場合は mounts を使用します。Workspace はファイル Tool 用に CompositeFilesystem を作成し、ストレージを FUSE で Sandbox にマウントします。

ローカル開発では通常、mounts は必要ありません。同じディレクトリを指定した LocalFilesystem と LocalSandbox を使用すれば、同じファイルに対するファイル Tool とコマンド実行の両方を利用できます。詳しくは、設定パターンを参照してください。

Agent Tool

Workspace に Filesystem を設定すると、Agent にファイルの読み取り、書き込み、一覧表示、削除を行う Tool が提供されます。詳しくは、Workspace クラスのリファレンスを参照してください。

関連項目

• LocalFilesystem リファレンス
• S3Filesystem リファレンス
• GCSFilesystem リファレンス
• GoogleDriveFilesystem リファレンス
• AzureBlobFilesystem リファレンス
• FilesSDKFilesystem リファレンス
• AgentFSFilesystem リファレンス
• MesaFilesystem リファレンス
• Workspace の概要
• Sandbox