본문으로 건너뛰기

플랫폼파일 시스템

Mastra Platform 작업 공간 버킷에 파일을 저장합니다. 각 Mastra 플랫폼 환경은 하나의 버킷을 가질 수 있으며,PlatformFilesystemAgent를 제공합니다read, write, list, delete, 그리고move이에 대한 작전.

관련 Provider: S3에 직접 액세스하려면 S3Filesystem, 로컬 디렉터리에는 LocalFilesystem을 사용합니다.

정보

인터페이스에 대한 자세한 내용은 다음을 참조하세요.WorkspaceFilesystem interface.

설치
설치에 대한 직접 링크

npm install @mastra/platform-workspace

플랫폼 자격 증명을 구성합니다. 액세스 토큰, 프로젝트 ID 및 버킷 이름은 환경 변수로 대체되므로 Mastra 플랫폼 배포는 생성자 옵션을 0으로 전달할 수 있습니다.

MASTRA_PLATFORM_ACCESS_TOKEN=your-platform-access-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name

Mastra 플랫폼 배포에서는 MASTRA_PLATFORM_ACCESS_TOKEN, MASTRA_PROJECT_ID, MASTRA_PLATFORM_BUCKET_NAME이 자동으로 주입되므로 옵션 없이 생성자를 호출할 수 있습니다. 로컬 개발에서는 MASTRA_PLATFORM_ACCESS_TOKEN에 조직 설정 페이지의 API Tokens에서 가져온 sk_ API 토큰을 사용할 수 있습니다.

용법
용법에 대한 직접 링크

Workspace에 PlatformFilesystem을 추가하고 Agent에 할당합니다:

import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { PlatformFilesystem } from '@mastra/platform-workspace'

const workspace = new Workspace({
  filesystem: new PlatformFilesystem({
    // accessToken, projectId, bucketName all fall back to env vars
  }),
})

const agent = new Agent({
  id: 'file-agent',
  name: 'File Agent',
  instructions: 'You are a research assistant that reads and writes reports.',
  model: 'anthropic/claude-sonnet-4-6',
  workspace,
})

파일 읽기 및 쓰기
파일 읽기 및 쓰기에 대한 직접 링크

객체 키는 세그먼트별로 퍼센트 인코딩되므로 파일 이름의 ?, #, %, &, + 또는 공백이 전체 과정에서 보존됩니다:

const fs = new PlatformFilesystem()

await fs.writeFile('/analyses/repo.md', markdown)
const content = await fs.readFile('/analyses/repo.md')
const entries = await fs.readdir('/analyses')
await fs.moveFile('/analyses/repo.md', '/analyses/repo-final.md')

읽기 전용 모드
읽기 전용 모드에 대한 직접 링크

버킷을 읽기 전용으로 마운트하려면 readOnly: true를 전달합니다. 변경 작업을 수행하는 모든 호출은 WorkspaceReadOnlyError를 발생시킵니다:

const fs = new PlatformFilesystem({ readOnly: true })

await fs.readFile('/analyses/repo.md') // ok
await fs.writeFile('/analyses/repo.md', 'x') // throws WorkspaceReadOnlyError

의미론 덮어쓰기
의미론 덮어쓰기에 대한 직접 링크

writeFile은 overwrite: false를 지원하며 대상이 이미 존재하면 FileExistsError를 발생시킵니다. copyFile과 moveFile은 항상 대상을 덮어씁니다. 두 메서드 중 하나에 overwrite: false를 전달하면 조용히 덮어쓰는 대신 오류가 발생합니다.

파일 추가
파일 추가에 대한 직접 링크

appendFile은 읽기-수정-쓰기 방식이며 원자적이지 않습니다. 동일한 경로에 동시에 추가하면 서로 덮어쓸 수 있습니다. 동시 작성자가 있다면 서로 다른 키와 함께 writeFile을 사용하세요.

생성자 매개변수
생성자 매개변수에 대한 직접 링크

accessToken?:

string
플랫폼 액세스 토큰입니다. MASTRA_PLATFORM_ACCESS_TOKEN 환경 변수를 대신 사용할 수 있습니다.

projectId?:

string
플랫폼 프로젝트 ID입니다. MASTRA_PROJECT_ID 환경 변수를 대신 사용할 수 있습니다.

bucketName?:

string
파일을 저장할 플랫폼 버킷 이름입니다. MASTRA_PLATFORM_BUCKET_NAME 환경 변수를 대신 사용할 수 있습니다.

readOnly?:

boolean
= false
true이면 변경 작업을 수행하는 모든 호출이 WorkspaceReadOnlyError를 발생시킵니다.

displayName?:

string
Workspace UI에 표시되는 사람이 읽기 쉬운 이름입니다.

description?:

string
Workspace UI에 표시되는 간단한 설명입니다.

icon?:

FilesystemIcon
Workspace UI에 표시되는 아이콘입니다.

instructions?:

string | ((opts: { defaultInstructions: string; requestContext?: RequestContext }) => string)
getInstructions()에서 반환되는 사용자 지정 지침입니다. 문자열은 기본값을 완전히 대체하며, 함수는 기본값을 전달받아 요청별로 확장하거나 사용자 지정할 수 있습니다.

id?:

string
= 자동 생성
이 파일 시스템 인스턴스의 고유 식별자입니다.

fetch?:

typeof fetch
주로 테스트에 사용하는 사용자 지정 fetch 구현입니다.

속성
속성에 대한 직접 링크

id:

string
파일 시스템 인스턴스 식별자입니다.

name:

string
Provider 이름('PlatformFilesystem')입니다.

provider:

string
Provider 식별자('platform').

readOnly:

boolean | undefined
파일 시스템이 읽기 전용으로 마운트되었는지 여부입니다.

오류
오류에 대한 직접 링크

파일 시스템 관련 오류는 표준 작업 공간 오류 유형과 일치합니다.

  • FileNotFoundError: 경로가 존재하지 않습니다. readFile, stat, deleteFile에서 발생합니다(force: true가 설정된 경우 제외).
  • FileExistsError: 대상이 이미 존재하는 상태에서 overwrite: false로 writeFile을 호출했습니다.
  • WorkspaceReadOnlyError: 읽기 전용 파일 시스템에서 변경 작업을 호출했습니다. 그 밖의 플랫폼 API 오류는 PlatformApiError를 발생시킵니다. 구조화된 { error: { message, type } } 응답은 .code(머신 판독 가능한 유형)와 .proxyMessage(사람이 읽을 수 있는 문자열)로 파싱됩니다.
import { FileNotFoundError } from '@mastra/core/workspace'
import { PlatformApiError } from '@mastra/platform-workspace'

try {
  await fs.readFile('/missing.txt')
} catch (err) {
  if (err instanceof FileNotFoundError) {
    // handle missing file
  } else if (err instanceof PlatformApiError) {
    if (err.code === 'authentication_error') {
      // refresh token
    }
    console.error(err.status, err.code, err.proxyMessage)
  }
}

FileNotFoundError, FileExistsError, WorkspaceReadOnlyError는 @mastra/core/workspace의 표준 Workspace 오류 유형을 다시 내보낸 것입니다. PlatformApiError는 @mastra/platform-workspace 전용입니다. 응답 본문이 JSON이 아닌 경우(예: 로드 밸런서가 반환한 HTML 502) code와 proxyMessage는 undefined입니다.

On this page