メインコンテンツへ移動

PlatformFilesystem

Mastra Platform の Workspace バケットにファイルを保存します。各 Mastra Platform 環境は1つのバケットを持つことができ、PlatformFilesystem はそのバケットに対する read、write、list、delete、move 操作を Agent に提供します。

関連 Provider：S3 への直接アクセスには S3Filesystem、ローカルディレクトリには LocalFilesystem を使用します。

情報

インターフェースの詳細は、WorkspaceFilesystem インターフェースを参照してください。

インストール
インストールへの直接リンク

npm install @mastra/platform-workspace

Platform の認証情報を設定します。アクセストークン、プロジェクト ID、バケット名は環境変数を使用できるため、Mastra Platform へのデプロイではコンストラクターオプションを省略できます。

MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name

Mastra Platform へのデプロイでは、MASTRA_PLATFORM_ACCESS_TOKEN、MASTRA_PROJECT_ID、MASTRA_PLATFORM_BUCKET_NAME が自動挿入されるため、オプションなしでコンストラクターを呼び出せます。ローカル開発では、組織の設定ページにある API Tokens で取得した sk_ API トークンを MASTRA_PLATFORM_ACCESS_TOKEN に設定できます。

使用方法
使用方法への直接リンク

Workspace に PlatformFilesystem を追加して Agent に割り当てます。

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { PlatformFilesystem } from '@mastra/platform-workspace'

const workspace = new Workspace({
  filesystem: new PlatformFilesystem({
    // accessToken, projectId, bucketName all fall back to env vars
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'File Agent',
  instructions: 'You are a research assistant that reads and writes reports.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})

ファイルを読み書きする
ファイルを読み書きするへの直接リンク

オブジェクトキーはセグメントごとにパーセントエンコードされるため、?、#、%、&、+、空白を含むファイル名も処理全体で保持されます。

const fs = new PlatformFilesystem()

await fs.writeFile('/analyses/repo.md', markdown)
const content = await fs.readFile('/analyses/repo.md')
const entries = await fs.readdir('/analyses')
await fs.moveFile('/analyses/repo.md', '/analyses/repo-final.md')

読み取り専用モード
読み取り専用モードへの直接リンク

バケットを読み取り専用でマウントするには、readOnly: true を渡します。変更を伴う呼び出しはすべて WorkspaceReadOnlyError をスローします。

const fs = new PlatformFilesystem({ readOnly: true })

await fs.readFile('/analyses/repo.md') // ok
await fs.writeFile('/analyses/repo.md', 'x') // throws WorkspaceReadOnlyError

上書きのセマンティクス
上書きのセマンティクスへの直接リンク

writeFile は overwrite: false に対応し、コピー先がすでに存在する場合は FileExistsError をスローします。

copyFile と moveFile は常にコピー先を上書きします。どちらかのメソッドに overwrite: false を渡すと、黙って上書きせずエラーをスローします。

ファイルへの追記
ファイルへの追記への直接リンク

appendFile は読み取り、変更、書き込みを行う操作であり、アトミックではありません。同じパスへの同時追記は互いに上書きする可能性があります。複数の Writer が同時に処理する場合は、異なるキーで writeFile を使用してください。

コンストラクターパラメーター
コンストラクターパラメーターへの直接リンク

accessToken?:

string
Platform のアクセストークン。未指定の場合は環境変数 MASTRA_PLATFORM_ACCESS_TOKEN を使用します。

projectId?:

string
Platform のプロジェクト ID。未指定の場合は環境変数 MASTRA_PROJECT_ID を使用します。

bucketName?:

string
ファイルを保存する Platform バケット名。未指定の場合は環境変数 MASTRA_PLATFORM_BUCKET_NAME を使用します。

readOnly?:

boolean
= false
true の場合、変更を伴うすべての呼び出しが WorkspaceReadOnlyError をスローします。

displayName?:

string
Workspace UI に表示するわかりやすい名前。

description?:

string
Workspace UI に表示する短い説明。

icon?:

FilesystemIcon
Workspace UI に表示するアイコン。

instructions?:

string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)
getInstructions() が返すカスタム指示。文字列はデフォルトを完全に置き換えます。関数はデフォルトを受け取り、リクエストごとに拡張またはカスタマイズできます。

id?:

string
= Auto-generated
この Filesystem インスタンスの一意な識別子。

fetch?:

typeof fetch
カスタム fetch 実装。主にテストで使用します。

プロパティ
プロパティへの直接リンク

id:

string
Filesystem インスタンスの識別子。

name:

string
Provider 名（'PlatformFilesystem'）。

provider:

string
Provider 識別子（'platform'）。

readOnly:

boolean | undefined
Filesystem が読み取り専用でマウントされたかどうか。

エラー
エラーへの直接リンク

Filesystem 固有のエラーは、Workspace の標準エラー型に対応します。

  • FileNotFoundError：パスが存在しません。readFile、stat、deleteFile からスローされます（force: true を設定した場合を除く）。
  • FileExistsError：overwrite: false で writeFile を呼び出し、コピー先がすでに存在します。
  • WorkspaceReadOnlyError：読み取り専用の Filesystem で変更を伴う呼び出しが行われました。

その他の Platform API の失敗では PlatformApiError が発生します。構造化された { error: { message, type } } レスポンスは、.code（機械可読な種別）と .proxyMessage（人が読める文字列）へ解析されます。

import { FileNotFoundError } from '@mastra/core/workspace'
import { PlatformApiError } from '@mastra/platform-workspace'

try {
  await fs.readFile('/missing.txt')
} catch (err) {
  if (err instanceof FileNotFoundError) {
    // handle missing file
  } else if (err instanceof PlatformApiError) {
    if (err.code === 'authentication_error') {
      // refresh token
    }
    console.error(err.status, err.code, err.proxyMessage)
  }
}

FileNotFoundError、FileExistsError、WorkspaceReadOnlyError は、@mastra/core/workspace の標準 Workspace エラー型を再エクスポートしたものです。PlatformApiError は @mastra/platform-workspace 固有です。

レスポンス本文が JSON でない場合（ロードバランサーからの HTML 502 など）、code と proxyMessage は undefined です。

On this page