ArchilFilesystem

Stocke les fichiers sur les disques élastiques et serverless d'Archil. Associe une API objet compatible S3 pour des lectures et écritures rapides à exec() pour les opérations de shell POSIX et à grep() pour les recherches parallèles côté serveur. Pour en savoir plus sur l'interface, consultez l'interface WorkspaceFilesystem.

Installation

npm

npm install @mastra/archil

pnpm

pnpm add @mastra/archil

Yarn

yarn add @mastra/archil

Bun

bun add @mastra/archil

Utilisation

Ajoutez un ArchilFilesystem à un Workspace et attribuez-le à un agent :

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { ArchilFilesystem } from '@mastra/archil'

const workspace = new Workspace({
  filesystem: new ArchilFilesystem({
    diskId: 'dsk-0123456789abcdef',
    apiKey: process.env.ARCHIL_API_KEY,
    region: 'aws-us-east-1',
  }),
})

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

Créer un disque lors de l'initialisation

Si vous ne disposez pas déjà d'un disque, fournissez createDiskOptions pour en créer un automatiquement :

import { ArchilFilesystem } from '@mastra/archil'

const filesystem = new ArchilFilesystem({
  apiKey: process.env.ARCHIL_API_KEY,
  region: 'aws-us-east-1',
  createDiskOptions: {
    name: 'my-agent-workspace',
  },
})

await filesystem.init()
// filesystem.diskId now contains the newly created disk ID

Valeurs de repli des variables d'environnement

Lorsque apiKey et region sont omis, le Provider lit les variables d'environnement suivantes :

• ARCHIL_API_KEY : clé API
• ARCHIL_REGION : région (par exemple aws-us-east-1)
• ARCHIL_S3_BASE_URL : point de terminaison S3 personnalisé (facultatif)

import { ArchilFilesystem } from '@mastra/archil'

// Uses ARCHIL_API_KEY and ARCHIL_REGION from environment
const filesystem = new ArchilFilesystem({
  diskId: 'dsk-0123456789abcdef',
})

Paramètres du constructeur

diskId?:

string

ID d’un disque Archil existant (par exemple "dsk-0123456789abcdef"). Mutuellement exclusif avec createDiskOptions.

createDiskOptions?:

CreateDiskRequest

Options de création d’un disque lors de l’initialisation. Mutuellement exclusif avec diskId.

apiKey?:

string

Clé API Archil. Utilise par défaut la variable d’environnement ARCHIL_API_KEY.

region?:

string

Région Archil (par exemple "aws-us-east-1"). Utilise par défaut la variable d’environnement ARCHIL_REGION.

baseUrl?:

string

URL personnalisée du plan de contrôle Archil (pour les tests ou les déploiements auto-hébergés).

s3BaseUrl?:

string

URL personnalisée de l’API compatible S3. Utilise par défaut la variable d’environnement ARCHIL_S3_BASE_URL.

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 valeur est 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 ('ArchilFilesystem').

provider:

string

Identifiant du Provider ('archil').

diskId:

string | undefined

ID du disque Archil (disponible après l’initialisation).

readOnly:

boolean | undefined

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

Méthodes

ArchilFilesystem 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. Se connecte au disque existant ou en crée un nouveau.

await filesystem.init()

getInfo()

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

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

Méthodes propres à Archil

exec(command)

Exécute une commande shell sur le disque. Renvoie le code de sortie, stdout et stderr.

const result = await filesystem.exec('ls -la /data')
// { exitCode: 0, stdout: '...', stderr: '' }

grep(options)

Effectue une recherche parallèle côté serveur dans les fichiers du disque.

const results = await filesystem.grep({
  directory: '/logs',
  pattern: 'ERROR',
  recursive: true,
  glob: '*.log',
})
// { matches: [...], stoppedReason: null }

share(path, options?)

Génère une URL signée pour partager un fichier.

const { url } = await filesystem.share('/reports/output.pdf', {
  expiresIn: 3600,
})

Ressources associées

• Interface WorkspaceFilesystem
• Référence S3Filesystem
• Référence GCSFilesystem
• Référence AzureBlobFilesystem
• Documentation Archil