S3Filesystem

Stocke des fichiers dans Amazon S3 ou dans des services de stockage compatibles S3 tels que Cloudflare R2, MinIO, DigitalOcean Spaces et Tigris. Pour plus de détails sur l'interface, consultez l'interface WorkspaceFilesystem.

Installation

npm

npm install @mastra/s3

pnpm

pnpm add @mastra/s3

Yarn

yarn add @mastra/s3

Bun

bun add @mastra/s3

Utilisation

Ajoutez un S3Filesystem à un Workspace et attribuez-le à un 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,
})

Chaîne de Providers d'identifiants AWS

Lorsqu'aucun identifiant n'est fourni, S3Filesystem utilise la chaîne de Providers d'identifiants par défaut du SDK AWS. Celle-ci détecte automatiquement les identifiants à partir des variables d'environnement, des fichiers de configuration ~/.aws, des identifiants de conteneurs ECS, des profils d'instances EC2 et d'autres sources standard.

import { S3Filesystem } from '@mastra/s3'

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

Transmettez une fonction de Provider d'identifiants pour actualiser automatiquement les identifiants. Cela est utile pour les déploiements sur ECS ou Lambda, ainsi que lors de l'utilisation de SSO/AssumeRole, où les identifiants temporaires expirent et doivent être renouvelés.

Installez le package de Providers d'identifiants du SDK AWS lorsque vous appelez directement fromNodeProviderChain() :

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(),
})

Les fonctions de Provider s'appliquent uniquement aux appels d'API de S3Filesystem. Lors du montage du système de fichiers dans une Sandbox E2B, la configuration de montage prend uniquement en charge les valeurs statiques accessKeyId, secretAccessKey et sessionToken ; l'actualisation des identifiants doit donc être gérée en dehors du montage.

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 utilise un adressage de type hôte virtuel ; forcePathStyle doit donc être défini sur false (la valeur par défaut est true lorsqu'un endpoint personnalisé est fourni). Créez les identifiants depuis le tableau de bord Tigris. Les clés d'accès sont préfixées par tid_ et les secrets par tsec_.

Paramètres du constructeur

bucket:

string

Nom du bucket S3

region:

string

Région AWS (utilisez 'auto' pour R2)

credentials?:

AwsCredentialIdentity | AwsCredentialIdentityProvider

Identifiants AWS ou fonction de Provider d'identifiants. Accepte des identifiants statiques ou un Provider qui les actualise automatiquement (par exemple, fromNodeProviderChain() de @aws-sdk/credential-providers). Prend le pas sur accessKeyId/secretAccessKey/sessionToken. Lorsque toutes les options d'identifiants sont omises, la chaîne de Providers d'identifiants par défaut du SDK est utilisée.

accessKeyId?:

string

Identifiant de clé d'accès AWS. Lorsqu'il est omis avec secretAccessKey et credentials, la chaîne de Providers d'identifiants par défaut du SDK est utilisée.

secretAccessKey?:

string

Clé d'accès secrète AWS. Lorsqu'elle est omise avec accessKeyId et credentials, la chaîne de Providers d'identifiants par défaut du SDK est utilisée.

sessionToken?:

string

Token de session AWS pour les identifiants temporaires statiques. Utilisez-le avec accessKeyId/secretAccessKey uniquement lorsque vous transmettez manuellement un ensemble complet d'identifiants temporaires. Pour l'actualisation automatique des identifiants SSO, AssumeRole ou de conteneur, utilisez le paramètre Provider credentials ou la chaîne de Providers d'identifiants par défaut du SDK.

endpoint?:

string

URL personnalisée de l’endpoint pour un stockage compatible S3 (R2, MinIO, Tigris, etc.)

forcePathStyle?:

boolean

= true (lorsque l'endpoint est défini)

Force l'utilisation d'URL de type chemin au lieu du type hôte virtuel. Obligatoire pour certains services compatibles S3 tels que MinIO. Utilise par défaut true lorsqu'un endpoint personnalisé est fourni.

prefix?:

string

Préfixe facultatif pour toutes les clés (agit comme un sous-répertoire)

id?:

string

= Généré automatiquement

Identifiant unique de cette instance de système de fichiers

displayName?:

string

Nom d'affichage lisible dans l'interface utilisateur

icon?:

FilesystemIcon

Identifiant de l'icône dans l'interface utilisateur

description?:

string

Courte description de ce système de fichiers dans l'interface utilisateur

readOnly?:

boolean

= false

Lorsque cette option vaut true, toutes les opérations d'écriture sont bloquées

Propriétés

id:

string

Identifiant de l'instance du système de fichiers

name:

string

Nom du Provider ('S3Filesystem')

provider:

string

Identifiant du Provider ('s3')

bucket:

string

Nom du bucket S3

readOnly:

boolean | undefined

Indique si le système de fichiers est en mode lecture seule

Méthodes

S3Filesystem implémente l'interface WorkspaceFilesystem et fournit toutes les méthodes standard d'un système de fichiers :

• readFile(path, options?) - Lit le contenu d'un fichier
• writeFile(path, content, options?) - Écrit du contenu dans un fichier
• appendFile(path, content) - Ajoute du contenu à un fichier
• deleteFile(path, options?) - Supprime un fichier
• copyFile(src, dest, options?) - Copie un fichier
• moveFile(src, dest, options?) - Déplace ou renomme un fichier
• mkdir(path, options?) - Crée un répertoire
• rmdir(path, options?) - Supprime un répertoire
• readdir(path, options?) - Répertorie le contenu d'un répertoire
• exists(path) - Vérifie si un chemin existe
• stat(path) - Récupère les métadonnées d'un fichier ou d'un répertoire

init()

Initialise le système de fichiers. Vérifie l'accès au bucket et les identifiants.

await filesystem.init()

getInfo()

Renvoie les métadonnées de cette instance de système de fichiers.

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

getMountConfig()

Renvoie la configuration de montage pour les Sandboxes prenant en charge le montage de ce type de système de fichiers.

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

Montage dans des Sandboxes E2B

S3Filesystem peut être monté dans des Sandboxes E2B afin de rendre le bucket accessible comme un répertoire local :

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

Consultez la référence d'E2BSandbox pour en savoir plus sur le montage.

Voir aussi

• Interface WorkspaceFilesystem
• Référence d'ArchilFilesystem
• Référence de GCSFilesystem
• Référence d'AzureBlobFilesystem
• Référence d'E2BSandbox
• Présentation de Workspace