AgentFSFilesystem

透過 AgentFS SDK 將檔案儲存在 Turso/SQLite 資料庫中。檔案會跨工作階段持久保存於本機 SQLite 資料庫，讓 Agent 無需外部雲端服務亦可擁有持久儲存空間。如需介面詳情，請參閱 WorkspaceFilesystem 介面。

安裝

npm

npm install @mastra/agentfs

pnpm

pnpm add @mastra/agentfs

Yarn

yarn add @mastra/agentfs

Bun

bun add @mastra/agentfs

使用方式

將 AgentFSFilesystem 加入 Workspace，並將其指派給 Agent。建立 AgentFSFilesystem 類別實例時，必須至少提供 agentId、path 或 agent 其中一項。

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { AgentFSFilesystem } from '@mastra/agentfs'

const workspace = new Workspace({
  filesystem: new AgentFSFilesystem({
    agentId: 'my-agent',
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'file-agent',
  model: 'openai/gpt-5.6-sol',
  workspace,
})

使用明確指定的資料庫路徑

根據預設設定，資料庫會儲存在 .agentfs 目錄內，並以 agentId 作為檔案名稱。你可以指定自訂資料庫路徑：

import { AgentFSFilesystem } from '@mastra/agentfs'

const filesystem = new AgentFSFilesystem({
  path: '/data/my-agent.db',
})

使用預先開啟的 AgentFS 實例

如果你需要自行管理 AgentFS 生命週期：

import { AgentFS } from 'agentfs-sdk'
import { AgentFSFilesystem } from '@mastra/agentfs'

const agent = await AgentFS.open({ id: 'my-agent' })

const filesystem = new AgentFSFilesystem({
  agent, // caller manages open/close
})

建構函數參數

你必須至少提供 agentId、path 或 agent 其中一項。

agentId?:

string

Agent ID — 在 .agentfs/<agentId>.db 建立資料庫

path?:

string

明確指定的資料庫檔案路徑（可取代 agentId）

agent?:

AgentFS

預先開啟的 AgentFS 實例。提供此項時，呼叫者負責管理生命週期（開啟／關閉）。

id?:

string

= 自動產生

此檔案系統實例的唯一識別碼

displayName?:

string

= 'AgentFS'

供使用者介面顯示、方便閱讀的名稱

icon?:

FilesystemIcon

= 'database'

使用者介面的圖示識別碼

description?:

string

在使用者介面中顯示的檔案系統簡短說明

readOnly?:

boolean

= false

設為 true 時，所有寫入操作都會被封鎖

屬性

id:

string

檔案系統實例識別碼

name:

string

Provider 名稱（'AgentFSFilesystem'）

provider:

string

Provider 識別碼（'agentfs'）

readOnly:

boolean | undefined

檔案系統是否處於唯讀模式