メインコンテンツへ移動

ArchilFilesystem

Archil の伸縮可能なサーバーレスディスクにファイルを保存します。高速な読み書きに対応する S3 互換オブジェクト API、POSIX シェル操作用の exec()、サーバー側並列検索用の grep() を組み合わせています。インターフェースの詳細は、WorkspaceFilesystem インターフェースを参照してください。

インストール
インストールへの直接リンク

npm install @mastra/archil

使用方法
使用方法への直接リンク

Workspace に ArchilFilesystem を追加して 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,
})

初期化時に新しいディスクを作成する
初期化時に新しいディスクを作成するへの直接リンク

既存のディスクがない場合は、createDiskOptions を指定すると自動的に作成できます。

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

環境変数へのフォールバック
環境変数へのフォールバックへの直接リンク

apiKey と region を省略すると、Provider は環境変数から値を読み取ります。

  • ARCHIL_API_KEY - API キー
  • ARCHIL_REGION - リージョン（例：aws-us-east-1）
  • ARCHIL_S3_BASE_URL - カスタム S3 エンドポイント（任意）
import { ArchilFilesystem } from '@mastra/archil'

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

コンストラクターパラメーター
コンストラクターパラメーターへの直接リンク

diskId?:

string
既存の Archil ディスク ID（例："dsk-0123456789abcdef"）。createDiskOptions とは同時に指定できません。

createDiskOptions?:

CreateDiskRequest
初期化時に新しいディスクを作成するためのオプション。diskId とは同時に指定できません。

apiKey?:

string
Archil API キー。未指定の場合は環境変数 ARCHIL_API_KEY を使用します。

region?:

string
Archil リージョン（例："aws-us-east-1"）。未指定の場合は環境変数 ARCHIL_REGION を使用します。

baseUrl?:

string
カスタム Archil コントロールプレーン URL（テストまたはセルフホスト環境向け）。

s3BaseUrl?:

string
カスタム S3 互換 API URL。未指定の場合は環境変数 ARCHIL_S3_BASE_URL を使用します。

id?:

string
= Auto-generated
この Filesystem インスタンスの一意な識別子。

displayName?:

string
UI に表示するわかりやすい名前。

icon?:

FilesystemIcon
UI に表示するアイコンの識別子。

description?:

string
UI に表示する Filesystem の短い説明。

readOnly?:

boolean
= false
true の場合、すべての書き込み操作を禁止します。

プロパティ
プロパティへの直接リンク

id:

string
Filesystem インスタンスの識別子。

name:

string
Provider 名（'ArchilFilesystem'）。

provider:

string
Provider 識別子（'archil'）。

diskId:

string | undefined
Archil ディスク ID（初期化後に使用可能）。

readOnly:

boolean | undefined
Filesystem が読み取り専用モードかどうか。

メソッド
メソッドへの直接リンク

ArchilFilesystem は WorkspaceFilesystem インターフェースを実装し、標準の Filesystem メソッドをすべて提供します。

  • readFile(path, options?) - ファイルの内容を読み取ります
  • writeFile(path, content, options?) - ファイルに内容を書き込みます
  • appendFile(path, content) - ファイルに内容を追記します
  • deleteFile(path, options?) - ファイルを削除します
  • copyFile(src, dest, options?) - ファイルをコピーします
  • moveFile(src, dest, options?) - ファイルを移動または名前変更します
  • mkdir(path, options?) - ディレクトリを作成します
  • rmdir(path, options?) - ディレクトリを削除します
  • readdir(path, options?) - ディレクトリの内容を一覧表示します
  • exists(path) - パスが存在するか確認します
  • stat(path) - ファイルまたはディレクトリのメタデータを取得します

init()
initへの直接リンク

Filesystem を初期化します。既存のディスクに接続するか、新しいディスクを作成します。

await filesystem.init()

getInfo()
getinfoへの直接リンク

この Filesystem インスタンスのメタデータを返します。

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

Archil 固有のメソッド
Archil 固有のメソッドへの直接リンク

exec(command)
execcommandへの直接リンク

ディスク上でシェルコマンドを実行し、終了コード、stdout、stderr を返します。

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

grep(options)
grepoptionsへの直接リンク

ディスク上のファイルを対象に、サーバー側で並列検索を実行します。

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

share(path, options?)
sharepath-optionsへの直接リンク

ファイル共有用の署名付き URL を生成します。

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