Workspace

Un espace de travail donne à un Agent l’accès au système de fichiers et l’exécution de commandes. Les Agents basés sur des fichiers reçoivent automatiquement un espace de travail par défaut lorsqu’ils sont découverts via mastra dev ou mastra build, afin de lire, écrire et exécuter des commandes sans configuration supplémentaire.

Utilisez cette page pour la convention basée sur les fichiers. Pour les fournisseurs, Tools, recherches, cycle de vie et détails de bac à sable, consultez les espaces de travail.

Espace de travail par défaut

Sans workspace.ts, un Agent basé sur des fichiers reçoit un Workspace par défaut lorsque la compilation fournit un chemin d’espace de travail par Agent. L’espace de travail par défaut utilise :

• LocalFilesystem enraciné dans le répertoire d’espace de travail empaqueté de l’Agent.
• LocalSandbox avec le même répertoire de travail.

Cela donne automatiquement à l’Agent des Tools de fichiers et de shell. L’espace de travail par défaut est propre à chaque Agent ; les sous-agents reçoivent des répertoires d’espace de travail imbriqués sous le chemin de leur Agent parent.

Démarrage rapide

Pour l’espace de travail par défaut, n’ajoutez pas de fichier. Commencez avec un répertoire d’Agent comme celui-ci :

Default workspace

src/mastra/agents/weather/
├── config.ts
└── instructions.md

Ajoutez workspace.ts uniquement lorsque vous devez personnaliser l’espace de travail :

src/mastra/agents/weather/workspace.ts

import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

export default new Workspace({
  name: 'weather-workspace',
  filesystem: new LocalFilesystem({ basePath: './data/weather' }),
  sandbox: new LocalSandbox({ workingDirectory: './data/weather' }),
})

Consultez la référence de Workspace pour la configuration complète.

Quand personnaliser l’espace de travail

Personnalisez l’espace de travail lorsque le répertoire local par défaut ne suffit pas. Raisons fréquentes :

• Pointer les Tools de fichiers vers une autre racine de système de fichiers.
• Exécuter des commandes shell dans un autre fournisseur de bac à sable.
• Ajouter une recherche d’espace de travail avec BM25 ou une recherche vectorielle.
• Partager un espace de travail entre plusieurs Agents.

Pour les modèles de fournisseur et le comportement à l’exécution, consultez la présentation des espaces de travail, le guide du bac à sable et la recherche d’espace de travail.

Limite d’exécution

Le système de fichiers de l’espace de travail contrôle ce que les Tools de fichiers peuvent lire et écrire. Le bac à sable contrôle l’emplacement d’exécution des commandes shell. Le code d’exécution de l’application, y compris le code de tools/, s’exécute toujours dans le processus de votre application ou serveur, sauf s’il appelle explicitement des API d’espace de travail ou de bac à sable.

Fichiers initiaux

Ajoutez un répertoire workspace/ pour inclure des fichiers initiaux avec l’Agent. Mastra réplique les fichiers dans workspace/ vers l’espace de travail d’exécution par défaut de l’Agent lors de la compilation ; l’Agent démarre ainsi avec ces fichiers sur le disque.

Seed files

src/mastra/agents/weather/
├── config.ts
└── workspace/
    ├── README.md
    └── data/
        └── cities.json

Les fichiers sont copiés dans le chemin d’espace de travail empaqueté, où les Tools de fichiers de l’espace de travail et les commandes du bac à sable peuvent les lire. Les fichiers initiaux liés symboliquement sont ignorés lors de la réplication.

Priorité par rapport à config

config.workspace est prioritaire sur workspace.ts ; sinon, l’espace de travail basé sur les fichiers par défaut est utilisé. Consultez la priorité de config.ts pour le tableau complet de fusion.