S3Filesystem

Amazon S3、または Cloudflare R2、MinIO、DigitalOcean Spaces、Tigris などの S3 互換ストレージサービスにファイルを保存します。インターフェースの詳細は、WorkspaceFilesystem インターフェースを参照してください。

インストール

npm

npm install @mastra/s3

pnpm

pnpm add @mastra/s3

Yarn

yarn add @mastra/s3

Bun

bun add @mastra/s3

使用方法

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

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'

const workspace = new Workspace({
  filesystem: new S3Filesystem({
    bucket: 'my-bucket',
    region: 'us-east-1',
    accessKeyId: process.env.AWS_ACCESS_KEY_ID,
    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'anthropic/claude-opus-4-7',
  workspace,
})

AWS 認証情報 Provider チェーン

認証情報を指定しない場合、S3Filesystem は AWS SDK のデフォルト認証情報 Provider チェーンを使用します。環境変数、~/.aws 設定ファイル、ECS コンテナ認証情報、EC2 インスタンスプロファイル、その他の標準ソースから認証情報を自動検出します。

import { S3Filesystem } from '@mastra/s3'

// SDK discovers credentials from the environment automatically
const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
})

認証情報を自動更新するには、認証情報 Provider 関数を渡します。ECS や Lambda へのデプロイ、または有効期限のある一時認証情報を更新する必要がある SSO / AssumeRole の使用時に便利です。

fromNodeProviderChain() を直接呼び出す場合は、AWS SDK の認証情報 Provider パッケージをインストールします。

npm

npm install @aws-sdk/credential-providers

pnpm

pnpm add @aws-sdk/credential-providers

Yarn

yarn add @aws-sdk/credential-providers

Bun

bun add @aws-sdk/credential-providers

import { S3Filesystem } from '@mastra/s3'
import { fromNodeProviderChain } from '@aws-sdk/credential-providers'

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
  credentials: fromNodeProviderChain(),
})

Provider 関数は S3Filesystem API の呼び出しにのみ適用されます。Filesystem を E2B Sandbox にマウントする場合、マウント設定は静的な accessKeyId、secretAccessKey、sessionToken の値にしか対応しないため、認証情報の更新はマウントの外部で処理する必要があります。

Cloudflare R2

import { S3Filesystem } from '@mastra/s3'

const filesystem = new S3Filesystem({
  bucket: 'my-r2-bucket',
  region: 'auto',
  endpoint: `https://${process.env.R2_ACCOUNT_ID}.r2.cloudflarestorage.com`,
  accessKeyId: process.env.R2_ACCESS_KEY_ID,
  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
})

MinIO

import { S3Filesystem } from '@mastra/s3'

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'us-east-1',
  endpoint: 'http://localhost:9000',
  accessKeyId: 'minioadmin',
  secretAccessKey: 'minioadmin',
})

Tigris

import { S3Filesystem } from '@mastra/s3'

const filesystem = new S3Filesystem({
  bucket: 'my-bucket',
  region: 'auto',
  endpoint: 'https://t3.storage.dev',
  accessKeyId: process.env.TIGRIS_ACCESS_KEY_ID,
  secretAccessKey: process.env.TIGRIS_SECRET_ACCESS_KEY,
  forcePathStyle: false,
})

Tigris は仮想ホスト形式のアドレス指定を使用するため、forcePathStyle を false に設定する必要があります（カスタムエンドポイントを指定した場合のデフォルトは true）。認証情報は Tigris ダッシュボードで作成します。アクセスキーには tid_、シークレットには tsec_ の接頭辞が付きます。

コンストラクターパラメーター

bucket:

string

S3 バケット名。

region:

string

AWS リージョン（R2 では 'auto' を使用）。

credentials?:

AwsCredentialIdentity | AwsCredentialIdentityProvider

AWS 認証情報または認証情報 Provider 関数。静的な認証情報、または自動更新する Provider（@aws-sdk/credential-providers の fromNodeProviderChain() など）を指定できます。accessKeyId / secretAccessKey / sessionToken より優先されます。すべての認証情報オプションを省略すると、SDK のデフォルト認証情報 Provider チェーンを使用します。

accessKeyId?:

string

AWS アクセスキー ID。secretAccessKey と credentials とともに省略した場合は、SDK のデフォルト認証情報 Provider チェーンを使用します。

secretAccessKey?:

string

AWS シークレットアクセスキー。accessKeyId と credentials とともに省略した場合は、SDK のデフォルト認証情報 Provider チェーンを使用します。

sessionToken?:

string

静的な一時認証情報用の AWS セッショントークン。完全な一時認証情報一式を手動で渡す場合にのみ、accessKeyId / secretAccessKey とともに使用します。自動更新する SSO、AssumeRole、コンテナ認証情報には、credentials Provider パラメーターまたは SDK のデフォルト認証情報 Provider チェーンを使用してください。

endpoint?:

string

S3 互換ストレージ（R2、MinIO、Tigris など）のカスタムエンドポイント URL。

forcePathStyle?:

boolean

= true (when endpoint is set)

仮想ホスト形式ではなくパス形式の URL を強制します。MinIO など一部の S3 互換サービスで必要です。カスタムエンドポイントを指定した場合のデフォルトは true です。

prefix?:

string

すべてのキーに付加する任意のプレフィックス（サブディレクトリとして機能します）。

id?:

string

= Auto-generated

この Filesystem インスタンスの一意な識別子。

displayName?:

string

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

icon?:

FilesystemIcon

UI に表示するアイコンの識別子。

description?:

string

UI に表示する Filesystem の短い説明。

readOnly?:

boolean

= false

true の場合、すべての書き込み操作を禁止します。

プロパティ

id:

string

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

name:

string

Provider 名（'S3Filesystem'）。

provider:

string

Provider 識別子（'s3'）。

bucket:

string

S3 バケット名。

readOnly:

boolean | undefined

Filesystem が読み取り専用モードかどうか。

メソッド

S3Filesystem は 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()

Filesystem を初期化し、バケットへのアクセスと認証情報を検証します。

await filesystem.init()

getInfo()

この Filesystem インスタンスのメタデータを返します。

const info = filesystem.getInfo()
// { id: '...', name: 'S3Filesystem', provider: 's3', status: 'ready' }

getMountConfig()

この種類の Filesystem のマウントに対応する Sandbox 向けに、マウント設定を返します。

const config = filesystem.getMountConfig()
// { type: 's3', bucket: 'my-bucket', region: 'us-east-1', ... }

E2B Sandbox にマウントする

S3Filesystem を E2B Sandbox にマウントすると、バケットへローカルディレクトリとしてアクセスできます。

import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
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,
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})

マウントの詳細は、E2BSandbox リファレンスを参照してください。

関連項目

• WorkspaceFilesystem インターフェース
• ArchilFilesystem リファレンス
• GCSFilesystem リファレンス
• AzureBlobFilesystem リファレンス
• E2BSandbox リファレンス
• Workspace の概要