Système de fichiers

Ajouté dans : @mastra/core@1.1.0

Les fournisseurs de système de fichiers permettent aux agents de lire, écrire et gérer des fichiers. Lorsque vous configurez un système de fichiers dans un workspace, les agents reçoivent des outils pour effectuer des opérations sur les fichiers.

Un fournisseur de système de fichiers gère toutes les opérations sur les fichiers d’un workspace :

• Lecture — lit le contenu des fichiers
• Écriture — crée et met à jour des fichiers
• Liste — parcourt les répertoires avec un filtrage facultatif par motif glob
• Suppression — supprime des fichiers et des répertoires
• Stat — récupère les métadonnées des fichiers
• Copie/Déplacement — copie ou déplace des fichiers entre différents emplacements
• Grep — recherche dans le contenu des fichiers au moyen de motifs d’expressions régulières

Fournisseurs pris en charge

Fournisseurs disponibles :

• LocalFilesystem : stocke les fichiers dans un répertoire sur le disque
• S3Filesystem : stocke les fichiers dans Amazon S3 ou un stockage compatible S3 (R2, MinIO, Tigris)
• GCSFilesystem : stocke les fichiers dans Google Cloud Storage
• PlatformFilesystem : stocke les fichiers dans un bucket de workspace Mastra Platform
• GoogleDriveFilesystem : stocke les fichiers dans un dossier Google Drive
• AzureBlobFilesystem : stocke les fichiers dans Azure Blob Storage
• FilesSDKFilesystem : stocke les fichiers dans n’importe quel adaptateur FilesSDK (S3, R2, GCS, Azure Blob, Vercel Blob, système de fichiers local, etc.) ; cette solution est utile lorsqu’un même fournisseur doit pouvoir cibler plusieurs backends
• AgentFSFilesystem : stocke les fichiers dans une base de données Turso/SQLite au moyen d’AgentFS
• MesaFilesystem : stocke les fichiers dans des dépôts Mesa versionnés
• ArchilFilesystem : stocke les fichiers sur des disques Archil élastiques et sans serveur

astuce

LocalFilesystem est la solution la plus simple pour commencer, car elle ne nécessite aucun service externe. Pour le stockage cloud, utilisez S3Filesystem, GCSFilesystem ou AzureBlobFilesystem. Pour le stockage versionné, utilisez MesaFilesystem. Pour un stockage fondé sur une base de données sans service externe, utilisez AgentFSFilesystem.

Utilisation de base

Créez un workspace doté d’un système de fichiers et attribuez-le à un agent. L’agent peut ensuite lire, écrire et gérer des fichiers dans le cadre de ses tâches :

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

Confinement

Par défaut, LocalFilesystem s’exécute en mode confiné : toutes les opérations sur les fichiers sont restreintes à basePath. Cela empêche les attaques par traversée de chemins et les échappements au moyen de liens symboliques.

En mode confiné :

• Les chemins relatifs, par exemple src/index.ts, sont résolus par rapport à basePath
• Les chemins absolus, par exemple /home/user/.config/file.txt, sont traités comme de véritables chemins du système de fichiers : s’ils se trouvent en dehors de basePath et de tous les allowedPaths, une PermissionError est levée
• Les chemins avec tilde, par exemple ~/Documents, sont développés vers le répertoire personnel et suivent les mêmes règles de confinement

Si votre agent doit accéder à certains chemins situés en dehors de basePath, utilisez allowedPaths pour accorder cet accès sans désactiver entièrement le confinement. Les chemins relatifs sont résolus par rapport à basePath, tandis que les chemins absolus sont utilisés tels quels :

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

Les chemins autorisés peuvent être mis à jour au moment de l’exécution avec la méthode setAllowedPaths() :

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

Cette approche est recommandée pour appliquer le principe du moindre privilège : l’agent peut atteindre uniquement les répertoires que vous autorisez.

Si votre agent a besoin d’un accès sans restriction à l’ensemble du système de fichiers, désactivez le confinement :

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

Lorsque contained vaut false, les chemins absolus sont traités comme de véritables chemins du système de fichiers, sans aucune restriction.

Système de fichiers dynamique

L’option filesystem accepte une fonction de résolution au lieu d’une instance statique. Cette fonction reçoit requestContext et renvoie un système de fichiers pour chaque requête, ce qui permet à un même workspace d’utiliser différents systèmes de fichiers selon l’identité, le rôle ou le tenant de l’appelant.

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

Chaque requête résout son propre système de fichiers pour les outils et les instructions du workspace :

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

Les instructions du Workspace utilisent le même requestContext ; l’agent voit donc le contexte du système de fichiers correspondant au fournisseur résolu.

La fonction de résolution peut également être asynchrone, par exemple pour rechercher une configuration dans une base de données :

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

remarque

filesystem et mounts s’excluent mutuellement. Vous ne pouvez pas utiliser une fonction de résolution avec mounts dans le même workspace.

Mode lecture seule

Pour empêcher les agents de modifier les fichiers, activez le mode lecture seule :

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

Avec un système de fichiers statique, les outils d’écriture (write_file, edit_file, delete, mkdir) sont entièrement exclus de l’ensemble d’outils de l’agent. Celui-ci peut toujours lire et répertorier les fichiers.

Lorsque vous utilisez un système de fichiers dynamique, les outils d’écriture sont toujours inclus, car la valeur de readOnly n’est connue qu’au moment de l’exécution de la fonction de résolution. Les opérations d’écriture sont alors bloquées au moment de l’exécution : l’outil renvoie une erreur si le système de fichiers résolu est en lecture seule.

Points de montage et CompositeFilesystem

Lorsque vous utilisez l’option mounts dans un workspace, Mastra crée un CompositeFilesystem qui route les opérations sur les fichiers vers le bon fournisseur en fonction du préfixe du chemin.

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

Avec cette configuration :

• read_file('/data/input.csv') lit depuis le bucket S3
• write_file('/skills/guide.md', content) écrit dans le bucket GCS
• list_directory('/') renvoie des entrées virtuelles pour /data et /skills
• Les commandes de la sandbox peuvent accéder aux fichiers situés dans /data et /skills au moyen de montages FUSE

Routage des chemins

Tous les chemins de fichiers doivent commencer par un préfixe de montage, car les opérations échouent lorsque leur chemin ne correspond à aucun montage. La liste du répertoire racine (/) renvoie une entrée de répertoire virtuelle pour chaque point de montage.

Les chemins de montage ne peuvent pas être imbriqués. Vous ne pouvez par exemple pas effectuer un montage à la fois dans /data et /data/sub.

filesystem ou mounts

filesystem et mounts sont des options mutuellement exclusives dans un workspace :

• Utilisez filesystem lorsque vous disposez d’un seul fournisseur de stockage et n’avez pas besoin de le monter dans une sandbox. L’agent reçoit des outils de fichiers qui agissent directement sur le fournisseur.
• Utilisez mounts lorsque le stockage cloud doit être accessible dans une sandbox, ou lorsque vous souhaitez combiner plusieurs fournisseurs. Le workspace crée un CompositeFilesystem pour les outils de fichiers et monte le stockage dans la sandbox au moyen de FUSE.

Pour le développement local, vous n’avez généralement pas besoin de mounts : un LocalFilesystem et un LocalSandbox pointant vers le même répertoire vous fournissent à la fois des outils de fichiers et l’exécution de commandes sur ces mêmes fichiers. Consultez les modèles de configuration pour plus de détails.

Outils des agents

Lorsque vous configurez un système de fichiers dans un workspace, les agents reçoivent des outils pour lire, écrire, répertorier et supprimer des fichiers. Consultez la référence de la classe Workspace pour plus de détails.

Ressources associées

• Référence de LocalFilesystem
• Référence de S3Filesystem
• Référence de GCSFilesystem
• Référence de GoogleDriveFilesystem
• Référence de AzureBlobFilesystem
• Référence de FilesSDKFilesystem
• Référence de AgentFSFilesystem
• Référence de MesaFilesystem
• Vue d’ensemble du Workspace
• Sandbox