파일 시스템

추가된 항목: @mastra/core@1.1.0

파일 시스템 공급자는 Agent에 파일 읽기, 쓰기, 관리 기능을 제공합니다. 작업공간에서 파일 시스템을 구성하면 Agent는 파일 작업을 위한 Tool을 받습니다.

파일 시스템 공급자는 작업공간에 대한 모든 파일 작업을 처리합니다.

• 읽다- 파일 내용 읽기
• 쓰다- 파일 생성 및 업데이트
• 목록- 선택적 글로브 패턴 필터링을 사용하여 디렉토리 찾아보기
• 삭제- 파일 및 디렉토리 제거
• 통계- 파일 메타데이터 가져오기
• 복사/이동- 위치 간 파일 복사 또는 이동
• 그렙- 정규식 패턴을 사용하여 파일 내용 검색

지원되는 Provider

사용 가능한 Provider:

• LocalFilesystem: 디스크의 디렉터리에 파일을 저장합니다.
• S3Filesystem: Amazon S3 또는 S3 호환 스토리지(R2, MinIO, Tigris)에 파일을 저장합니다.
• GCSFilesystem: Google Cloud Storage에 파일을 저장합니다.
• PlatformFilesystem: Mastra Platform Workspace 버킷에 파일을 저장합니다.
• GoogleDriveFilesystem: Google Drive 폴더에 파일을 저장합니다.
• AzureBlobFilesystem: Azure Blob Storage에 파일을 저장합니다.
• FilesSDKFilesystem: FilesSDK 어댑터를 통해 원하는 위치에 파일을 저장합니다(S3, R2, GCS, Azure Blob, Vercel Blob, 로컬 파일 시스템 등). 하나의 Provider로 여러 백엔드를 대상으로 지정하려는 경우 유용합니다.
• AgentFSFilesystem: AgentFS를 통해 Turso/SQLite 데이터베이스에 파일을 저장합니다.
• MesaFilesystem: 버전이 관리되는 Mesa 저장소에 파일을 저장합니다.
• ArchilFilesystem: Archil 탄력적 서버리스 디스크에 파일을 저장합니다.

팁

LocalFilesystem은 외부 서비스가 필요하지 않으므로 가장 간단하게 시작할 수 있는 방법입니다. 클라우드 스토리지에는 S3Filesystem, GCSFilesystem, AzureBlobFilesystem 중 하나를 사용하세요. 버전 관리 스토리지에는 MesaFilesystem을 사용하세요. 외부 서비스 없이 데이터베이스 기반 스토리지를 사용하려면 AgentFSFilesystem을 사용하세요.

기본 사용법

파일 시스템으로 작업공간을 생성하고 이를 Agent에 할당합니다. 그러면 Agent는 작업의 일부로 파일을 읽고, 쓰고, 관리할 수 있습니다.

src/mastra/agents/file-agent.ts

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

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
  }),
})

const agent = new Agent({
  id: 'file-agent',
  model: 'openai/gpt-5.6-sol',
  instructions: 'You are a helpful file management assistant.',
  workspace,
})

// The agent now has filesystem tools available
const response = await agent.generate('List all files in the workspace')

방지

기본적으로 LocalFilesystem은 격리 모드로 실행되며, 모든 파일 작업은 basePath 내부로 제한됩니다. 이를 통해 경로 순회 공격과 심볼릭 링크를 통한 이탈을 방지합니다. 포함 모드에서:

• 상대 경로(예: src/index.ts)는 basePath를 기준으로 해석됩니다.
• 절대 경로(예: /home/user/.config/file.txt)는 실제 파일 시스템 경로로 취급됩니다. 경로가 basePath와 모든 allowedPaths 외부에 있으면 PermissionError가 발생합니다.
• 물결표 경로(예: ~/Documents)는 홈 디렉터리로 확장되며 동일한 격리 규칙을 따릅니다. Agent가 basePath 외부의 특정 경로에 액세스해야 한다면 격리를 완전히 비활성화하는 대신 allowedPaths로 액세스 권한을 부여하세요. 상대 경로는 basePath를 기준으로 해석되며 절대 경로는 그대로 사용됩니다.

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    allowedPaths: ['~/.claude/skills', '../shared-data'],
  }),
})

허용된 경로는 다음을 사용하여 런타임 시 업데이트될 수 있습니다.setAllowedPaths() method:

// Add a path dynamically
workspace.filesystem.setAllowedPaths(prev => [...prev, '/home/user/documents'])

이는 최소 권한 액세스에 권장되는 접근 방식입니다. Agent는 사용자가 허용하는 특정 디렉터리에만 접근할 수 있습니다.

Agent가 전체 파일 시스템에 대한 무제한 액세스가 필요한 경우 포함을 비활성화합니다.

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    contained: false,
  }),
})

contained가 false이면 절대 경로가 아무런 제한 없이 실제 파일 시스템 경로로 취급됩니다.

동적 파일 시스템

filesystem 옵션에는 정적 인스턴스 대신 리졸버 함수를 사용할 수 있습니다. 리졸버는 requestContext를 받아 요청별 파일 시스템을 반환하므로, 하나의 Workspace에서 호출자의 ID, 역할 또는 테넌트에 따라 서로 다른 파일 시스템을 제공할 수 있습니다.

src/mastra/workspaces.ts

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

const workspace = new Workspace({
  filesystem: ({ requestContext }) => {
    const role = requestContext.get('agent-role') || 'guest'
    return new LocalFilesystem({
      basePath: `/workspaces/${role}`,
      readOnly: role !== 'admin',
    })
  },
})

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

각 요청은 작업 공간 Tool 및 작업 공간 지침에 대한 자체 파일 시스템을 확인합니다.

import { RequestContext } from '@mastra/core/request-context'

// Admin request — reads and writes from /workspaces/admin/
const adminCtx = new RequestContext([['agent-role', 'admin']])
await agent.generate('Write report.txt with Q4 results', { requestContext: adminCtx })

// Viewer request — reads from /workspaces/viewer/, writes are blocked
const viewerCtx = new RequestContext([['agent-role', 'viewer']])
await agent.generate('Read info.txt', { requestContext: viewerCtx })

Workspace 지침에도 동일한 requestContext가 사용되므로 Agent는 해석된 Provider의 파일 시스템 컨텍스트를 확인할 수 있습니다. 예를 들어 데이터베이스에서 구성을 조회하기 위해 해석기는 비동기식일 수도 있습니다.

const workspace = new Workspace({
  filesystem: async ({ requestContext }) => {
    const tenantConfig = await db.getTenant(requestContext.get('tenant-id'))
    return new LocalFilesystem({ basePath: tenantConfig.storagePath })
  },
})

노트

filesystem과 mounts는 함께 사용할 수 없습니다. 같은 Workspace에서 리졸버 함수와 mounts를 함께 사용할 수 없습니다.

읽기 전용 모드

Agent가 파일을 수정하지 못하도록 하려면 읽기 전용 모드를 활성화하세요.

const workspace = new Workspace({
  filesystem: new LocalFilesystem({
    basePath: './workspace',
    readOnly: true,
  }),
})

읽기 전용 정적 파일 시스템을 사용하면 쓰기 Tool(write_file, edit_file, delete, mkdir)이 Agent의 Tool 세트에서 완전히 제외됩니다. Agent는 계속해서 파일을 읽고 나열할 수 있습니다. 동적 파일 시스템을 사용할 때는 리졸버가 실행되기 전까지 readOnly 값을 알 수 없으므로 쓰기 Tool이 항상 포함됩니다. 대신 런타임에 쓰기 작업이 차단되며, 해석된 파일 시스템이 읽기 전용이면 Tool이 오류를 반환합니다.

마운트 및CompositeFilesystem

Workspace에서 mounts 옵션을 사용하면 Mastra가 경로 접두사를 기준으로 파일 작업을 올바른 Provider에 라우팅하는 CompositeFilesystem을 생성합니다.

import { Workspace } from '@mastra/core/workspace'
import { S3Filesystem } from '@mastra/s3'
import { GCSFilesystem } from '@mastra/gcs'
import { E2BSandbox } from '@mastra/e2b'

const workspace = new Workspace({
  mounts: {
    '/data': new S3Filesystem({
      bucket: 'my-bucket',
      region: 'us-east-1',
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
    }),
    '/skills': new GCSFilesystem({
      bucket: 'agent-skills',
    }),
  },
  sandbox: new E2BSandbox({ id: 'dev-sandbox' }),
})

이 구성을 사용하면 다음과 같습니다.

• read_file('/data/input.csv')는 S3 버킷에서 읽습니다.
• write_file('/skills/guide.md', content)는 GCS 버킷에 씁니다.
• list_directory('/')는 /data와 /skills의 가상 항목을 반환합니다.
• Sandbox의 명령은 FUSE 마운트를 통해 /data와 /skills의 파일에 액세스할 수 있습니다.

경로 라우팅

경로가 마운트와 일치하지 않으면 작업이 실패하므로 모든 파일 경로는 마운트 접두사로 시작해야 합니다. 루트 디렉터리(/)를 나열하면 각 마운트 지점의 가상 디렉터리 항목이 반환됩니다. 마운트 경로는 중첩할 수 없습니다. 예를 들어 /data와 /data/sub에 모두 마운트할 수 없습니다.

filesystem대mounts

filesystem과 mounts는 Workspace에서 함께 사용할 수 없는 옵션입니다.

• 단일 스토리지 Provider를 사용하고 Sandbox에 마운트할 필요가 없다면 **filesystem**을 사용하세요. Agent에는 Provider를 직접 대상으로 작업하는 파일 Tool이 제공됩니다.
• Sandbox 내부에서 클라우드 스토리지에 액세스해야 하거나 여러 Provider를 결합하려면 **mounts**를 사용하세요. Workspace는 파일 Tool을 위한 CompositeFilesystem을 만들고 스토리지를 Sandbox에 FUSE로 마운트합니다. 로컬 개발에서는 일반적으로 mounts가 필요하지 않습니다. LocalFilesystem과 LocalSandbox가 같은 디렉터리를 가리키도록 설정하면 동일한 파일에서 파일 Tool과 명령 실행을 모두 사용할 수 있습니다. 자세한 내용은 구성 패턴을 참조하세요.

Agent Tool

Workspace에서 파일 시스템을 구성하면 Agent에 파일을 읽고, 쓰고, 나열하고, 삭제하는 Tool이 제공됩니다. 자세한 내용은 Workspace 클래스 레퍼런스를 참조하세요.

관련된

• 로컬파일시스템 참조
• S3파일 시스템 참조
• GCS파일 시스템 참조
• GoogleDrive파일 시스템 참조
• AzureBlob파일 시스템 참조
• FilesSDK파일 시스템 참조
• AgentFS파일 시스템 참조
• 메사파일시스템 참조
• 작업공간 개요
• 모래 상자