GoogleDriveFilesystem

Stocke les fichiers dans un seul dossier Google Drive. Chaque répertoire correspond à un dossier Drive sous la racine configurée, et les chemins respectent la sémantique POSIX, par exemple /notes/todo.txt. Pour en savoir plus sur l’interface, consultez l’interface WorkspaceFilesystem.

Installation

npm

npm install @mastra/google-drive

pnpm

pnpm add @mastra/google-drive

Yarn

yarn add @mastra/google-drive

Bun

bun add @mastra/google-drive

Utilisation

Ajoutez un GoogleDriveFilesystem à un Workspace et attribuez-le à un Agent :

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { GoogleDriveFilesystem } from '@mastra/google-drive'

const workspace = new Workspace({
  filesystem: new GoogleDriveFilesystem({
    folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
    accessToken: process.env.GOOGLE_DRIVE_ACCESS_TOKEN!,
  }),
})

const agent = new Agent({
  id: 'drive-agent',
  name: 'Drive Agent',
  model: 'openai/gpt-5-mini',
  workspace,
})

Authentification

Fournissez l’une des options d’authentification suivantes :

• accessToken : token d’accès OAuth obtenu au préalable. Utilisez la portée https://www.googleapis.com/auth/drive afin que le token puisse voir les dossiers partagés avec l’identité authentifiée.
• getAccessToken : callback qui renvoie un token. Utile lorsque les tokens sont actualisés par un système externe.
• serviceAccount : compte de service Google. Partagez le dossier cible avec l’adresse e-mail du compte de service.

Compte de service

L’authentification par compte de service est l’option recommandée pour les Agents backend. Elle ne nécessite ni flux de consentement de l’utilisateur ni gestion de l’actualisation des tokens. Vous avez uniquement besoin de deux valeurs du fichier de clé JSON du compte de service : client_email et private_key.

Configurer le compte de service

1. Ouvrez la Google Cloud Console, puis sélectionnez ou créez un projet.
2. Accédez à APIs & Services > Library, recherchez Google Drive API, puis sélectionnez Enable.
3. Accédez à APIs & Services > Credentials, sélectionnez Create credentials > Service account, puis remplissez le formulaire. Le rôle peut rester vide : les permissions Drive sont accordées par le partage des dossiers, et non par les rôles IAM.
4. Ouvrez le nouveau compte de service, accédez à l’onglet Keys, puis sélectionnez Add key > Create new key > JSON. Le navigateur télécharge un fichier de clé JSON.
5. Copiez la valeur client_email du fichier JSON. Il s’agit de l’adresse avec laquelle vous partagez les dossiers Drive.

Partager le dossier Drive avec le compte de service

Le compte de service possède sa propre identité Google. Il ne peut rien voir dans Drive tant que vous ne partagez pas explicitement du contenu avec lui.

1. Ouvrez le dossier cible dans Google Drive.
2. Sélectionnez Share.
3. Collez l’adresse client_email du compte de service.
4. Définissez le rôle sur Editor pour la lecture et l’écriture, ou sur Viewer pour un accès en lecture seule. Sélectionnez Send.
5. Copiez l’ID du dossier depuis l’URL. Il s’agit du segment qui suit /folders/ dans https://drive.google.com/drive/folders/<folderId>.

attention

Les comptes de service ne peuvent pas créer de fichiers dans les dossiers standards "My Drive". Un compte de service ne possède aucun quota de stockage Drive personnel ; chaque fichier qu’il crée doit donc appartenir à une entité disposant d’un quota. Si vous partagez uniquement un dossier Drive personnel, les opérations de lecture fonctionnent, mais les écritures échouent avec une erreur de quota.

Pour autoriser l’écriture, placez le dossier dans un shared drive, anciennement appelé Team Drive, puis ajoutez le compte de service comme membre de ce shared drive. Les shared drives fournissent le quota de stockage nécessaire aux fichiers créés par le compte de service.

Les charges de travail en lecture seule sur un dossier Drive personnel ne sont pas soumises à cette restriction.

Configurer le système de fichiers

Copiez client_email et private_key depuis le fichier JSON dans votre environnement :

GOOGLE_DRIVE_FOLDER_ID=1AbCdEfGhIjKlMnOpQrStUvWxYz
GOOGLE_DRIVE_CLIENT_EMAIL=my-bot@my-project.iam.gserviceaccount.com
# Wrap the value in quotes — the key contains newlines that must be preserved.
GOOGLE_DRIVE_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nMIIEvQIBADANBgkq...\n-----END PRIVATE KEY-----\n"

import { GoogleDriveFilesystem } from '@mastra/google-drive'

const filesystem = new GoogleDriveFilesystem({
  folderId: process.env.GOOGLE_DRIVE_FOLDER_ID!,
  serviceAccount: {
    clientEmail: process.env.GOOGLE_DRIVE_CLIENT_EMAIL!,
    privateKey: process.env.GOOGLE_DRIVE_PRIVATE_KEY!,
  },
})

Vous ne devez pas copier l’intégralité du fichier JSON ni transmettre d’autres champs tels que project_id, client_id, private_key_id ou token_uri, car ils ne sont pas utilisés. Seuls clientEmail et privateKey sont requis. privateKeyId, scopes et subject sont facultatifs. Par défaut, scopes vaut ['https://www.googleapis.com/auth/drive'], la portée nécessaire pour que le compte de service voie les dossiers partagés avec lui. La portée plus restreinte drive.file donne uniquement accès aux fichiers créés par l’application elle-même ; un dossier partagé avec le compte de service renverrait donc 404 Not Found.

GoogleDriveFilesystem normalise automatiquement la chaîne privateKey avant la signature. Il supprime les guillemets qui l’entourent, y compris ceux échappés dans les valeurs encapsulées en JSON, et convertit les séquences littérales \n en véritables sauts de ligne. Il normalise également les fins de ligne \r\n et supprime toute virgule finale. La clé fonctionne quelle que soit la manière dont votre chargeur .env traite la valeur.

Résolution des problèmes

• 404 File not found: <folderId> : le compte de service n’a pas accès au dossier. Vérifiez que le dossier est partagé avec l’adresse client_email exacte et que son ID correspond à l’URL.
• storageQuotaExceeded lors de l’écriture : le dossier se trouve dans un espace "My Drive" personnel. Déplacez-le vers un shared drive et ajoutez le compte de service comme membre.
• error:1E08010C:DECODER routines::unsupported : la valeur privateKey est mal formée. Vérifiez qu’elle contient l’intégralité du bloc PEM et que les sauts de ligne sont conservés (les séquences littérales \n conviennent).

Mode lecture seule

Transmettez readOnly: true pour bloquer les opérations d’écriture (writeFile, appendFile, deleteFile, copyFile, moveFile, mkdir, rmdir).

const filesystem = new GoogleDriveFilesystem({
  folderId,
  accessToken,
  readOnly: true,
})

Paramètres du constructeur

folderId:

string

ID du dossier Google Drive qui sert de racine au Workspace. Tous les chemins sont résolus à l’intérieur de ce dossier.

accessToken?:

string

Token d’accès OAuth ayant accès au dossier.

getAccessToken?:

() => string | Promise<string>

Callback qui renvoie un nouveau token d’accès OAuth. Appelé pour chaque requête nécessitant une autorisation.

serviceAccount?:

{ clientEmail: string; privateKey: string; privateKeyId?: string; scopes?: string[]; subject?: string }

Identifiants du compte de service utilisés pour générer des tokens d’accès au moyen du flux JWT OAuth 2.0.

id?:

string

= `google-drive:${folderId}`

Identifiant unique de cette instance de système de fichiers

readOnly?:

boolean

= false

Lorsque la valeur est true, toutes les opérations d’écriture sont bloquées.

instructions?:

InstructionsOption

Remplace les instructions par défaut renvoyées dans les descriptions des Tools.

Propriétés

id:

string

Identifiant de l’instance du système de fichiers

name:

string

Nom du Provider ('GoogleDriveFilesystem')

provider:

string

Identifiant du Provider ('google-drive')

readOnly:

boolean | undefined

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

Méthodes

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

• readFile(path, options?) - Télécharge le contenu d’un fichier
• writeFile(path, content, options?) - Charge ou remplace un fichier
• appendFile(path, content) - Ajoute du contenu en lisant puis en rechargeant le fichier
• deleteFile(path, options?) - Supprime un fichier
• copyFile(src, dest, options?) - Copie un fichier à l’aide de l’API Drive files.copy
• moveFile(src, dest, options?) - Déplace un fichier entre des dossiers en échangeant ses parents
• mkdir(path, options?) - Crée un dossier
• rmdir(path, options?) - Supprime un dossier
• readdir(path, options?) - Répertorie le contenu d’un dossier (prend en charge le filtrage recursive et extension)
• stat(path) - Renvoie les métadonnées Drive d’un fichier ou d’un dossier
• exists(path) - Vérifie si un fichier ou un dossier existe

Remarques

• Google Drive autorise plusieurs fichiers portant le même nom dans un dossier. GoogleDriveFilesystem résout les chemins en sélectionnant la première correspondance ; utilisez donc des noms uniques dans chaque dossier lorsque vous dépendez de la recherche par chemin.
• writeFile crée automatiquement les dossiers parents lorsque recursive n’est pas défini, ce qui est le comportement par défaut, ou vaut true. Définissez recursive: false pour exiger que le dossier parent existe déjà.
• La valeur expectedMtime de WriteOptions est respectée. Lorsque la valeur modifiedTime stockée diffère, l’écriture est rejetée avec StaleFileError afin de prendre en charge la concurrence optimiste.
• Le Provider utilise uniquement les endpoints REST de Drive (https://www.googleapis.com/drive/v3 et https://www.googleapis.com/upload/drive/v3) au moyen du fetch intégré. Aucune dépendance supplémentaire n’est requise.