본문으로 건너뛰기

작업공간

작업공간은 Mastra 플랫폼이 배포 시 Agent에 프로비저닝하고 전달하는 런타임 리소스 세트입니다. 각 환경에는 고유한 작업 공간이 있으므로production그리고staging격리 상태를 유지하세요.

모든 작업공간은 두 가지 기능을 제공합니다.

  • 파일 시스템 스토리지용 버킷 하나로, PlatformFilesystem로 래핑됩니다. 버킷은 Agent가 여러 실행에 걸쳐 읽고 쓸 수 있는 환경 범위의 영구 저장소입니다.
  • 명령 실행용 온디맨드 Sandbox 풀로, PlatformSandbox로 래핑됩니다. 각 PlatformSandbox 인스턴스는 start()에서 자체 원격 Sandbox를 프로비저닝하고 destroy()에서 제거합니다. Agent는 일반적으로 세션마다 여러 Sandbox를 시작하여 작업에 사용한 뒤 그대로 둡니다. Workspace의 범위는 하나의 환경으로 지정되므로 production과 staging은 버킷이나 Sandbox 풀을 공유하지 않습니다. 플랫폼에서 프로비저닝, 인증, 유휴 리소스 정리를 관리합니다.

Workspace가 프로비저닝되는 경우
Workspace가 프로비저닝되는 경우에 대한 직접 링크

새 프로젝트에는 기본적으로 Workspace가 활성화되어 있습니다. 환경을 생성하면 플랫폼이 해당 환경의 버킷을 자동으로 프로비저닝합니다. Sandbox 기본 이미지는 백그라운드에서 미리 준비되므로 첫 번째 PlatformSandbox 호출도 빠르게 시작됩니다. 아직 활성화하지 않은 기존 프로젝트의 Workspaces 탭에는 Enable workspaces 작업이 표시됩니다. 활성화하면 프로젝트의 모든 환경에 버킷이 프로비저닝됩니다. 예를 들어 샌드박스 공급자가 로드 중인 동안 환경에 대한 프로비저닝이 실패하면 작업 영역 탭에 실패가 표시되고 재시도가 제공됩니다. 환경 자체는 여전히 생성됩니다. 다시 시도할 때까지 작업공간만 사용할 수 없습니다.

코드에서 작업공간 사용
코드에서 작업공간 사용에 대한 직접 링크

공급자 패키지를 설치합니다.

npm install @mastra/platform-workspace

공급자를 작업 공간으로 구성하고 이를 Mastra에 등록합니다.

src/mastra/workspace.ts
import { Workspace } from '@mastra/core/workspace'
import { PlatformFilesystem, PlatformSandbox } from '@mastra/platform-workspace'

export const workspace = new Workspace({
  filesystem: new PlatformFilesystem(),
  sandbox: new PlatformSandbox(),
})
src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { workspace } from './workspace'

export const mastra = new Mastra({
  workspace,
})

PlatformFilesystem과 PlatformSandbox는 환경 변수에서 구성을 읽으므로 플랫폼에서는 옵션을 전달하지 않습니다. 플랫폼이 배포 시 해당 변수를 주입합니다. 환경 변수를 참조하세요.

하나의 버킷, 많은 샌드박스
하나의 버킷, 많은 샌드박스에 대한 직접 링크

PlatformFilesystem과 PlatformSandbox는 수명 주기가 서로 다르며, 이는 Agent를 설계할 때 중요합니다. PlatformFilesystem환경 버킷에 대한 수명이 긴 핸들입니다.환경의 모든 요청, 모든 Agent 및 모든 샌드박스는 동일한 객체 스토리지를 읽고 씁니다. Agent가 작성한 모든 내용은 명시적으로 삭제하지 않는 한 다음 요청 시 표시됩니다.

PlatformSandbox임시 샌드박스를 프로비저닝하기 위한 클라이언트입니다.각PlatformSandbox instance owns one remote sandbox:

  • start()는 새 Sandbox를 프로비저닝하거나 전달된 sandboxId에 다시 연결합니다.
  • executeCommand()는 해당 Sandbox에서 명령을 실행합니다.
  • destroy()는 Sandbox를 제거합니다. stop()은 별칭입니다. Workspace에 전달하는 sandbox는 Agent가 자체 요청 내에서 사용하는 Tool을 제공합니다. 작업별 Workspace, 사용자별 테넌트 또는 호출자의 셸 상태에 영향을 주면 안 되는 백그라운드 작업처럼 Agent에 별도의 격리된 환경이 필요한 경우 다른 PlatformSandbox를 생성하세요.
src/mastra/tools/run-in-fresh-sandbox.ts
import { PlatformSandbox } from '@mastra/platform-workspace'

export async function runInFreshSandbox(command: string) {
  const sandbox = new PlatformSandbox()
  await sandbox.start()
  try {
    return await sandbox.executeCommand(command)
  } finally {
    await sandbox.destroy()
  }
}

또는 구성된 샌드박스를 플릿의 템플릿으로 복제하여 복제가 자격 증명, 환경, 네트워크 격리 및 기본값을 반복하지 않고 상속하도록 합니다.

const template = new PlatformSandbox({ networkIsolation: 'PRIVATE' })

const perProjectSandbox = template.clone({ id: `project-${projectId}` })
await perProjectSandbox.start()

전체 수명 주기, 체크포인트 복구, 재연결 및 복제 옵션은 PlatformSandbox 참고 문서를 참조하세요.

환경변수
환경변수에 대한 직접 링크

작업공간이 있는 플랫폼 환경에서 실행되는 모든 배포는 다음 변수를 자동으로 받습니다.

변수설명
MASTRA_PLATFORM_ACCESS_TOKENWorkspace Provider가 인증에 사용하는 플랫폼 발급 JSON Web Token(JWT)입니다. 토큰 범위는 배포의 조직과 프로젝트로 제한됩니다.
MASTRA_PROJECT_ID배포가 속한 프로젝트입니다.
MASTRA_ENVIRONMENT_ID배포가 속한 환경입니다. 플랫폼에서 사용할 Sandbox 풀을 선택합니다.
MASTRA_PLATFORM_BUCKET_NAME환경에 연결된 버킷 이름입니다. PlatformFilesystem이 읽고 쓸 버킷을 선택합니다.
이 이름은 예약되어 있습니다. 프로젝트에서 명시적으로 설정한 경우 플랫폼 관리 값이 우선 적용됩니다.

지역 발전
지역 발전에 대한 직접 링크

네 변수를 .env 파일에 추가하세요. 프로젝트, 환경 및 버킷 값은 프로젝트의 Workspaces 탭에서 가져옵니다. MASTRA_PLATFORM_ACCESS_TOKEN에는 조직 설정 페이지의 API Tokens에서 sk_ API 토큰을 생성해 사용하세요. 플랫폼 배포에서는 주입된 JWT를 대신 사용합니다.

.env
MASTRA_PLATFORM_ACCESS_TOKEN=sk_your-api-token
MASTRA_PROJECT_ID=your-project-id
MASTRA_ENVIRONMENT_ID=your-environment-id
MASTRA_PLATFORM_BUCKET_NAME=your-bucket-name

PlatformFilesystem과 PlatformSandbox는 로컬과 플랫폼에서 동일하게 동작하며 해당 환경의 같은 버킷과 Sandbox 풀에 연결됩니다. 프로덕션 데이터를 격리하려면 로컬 실행에 staging 또는 preview 환경의 변수를 사용하세요. 플랫폼에 전혀 영향을 주지 않는 완전한 오프라인 루프가 필요하면 로컬 빌드에서 Provider를 LocalFilesystem과 LocalSandbox로 교체하세요.

작업 공간 검사
작업 공간 검사에 대한 직접 링크

플랫폼 프로젝트의 작업공간 탭에는 환경별로 다음이 표시됩니다.

  • 업로드, 다운로드, 삭제 작업이 포함된 버킷 상태 및 해당 콘텐츠입니다.
  • 해당 명령, 종료 코드 및 기간이 포함된 최근 샌드박스 세션입니다.
  • 프로비저닝 실패Retry action.

또한보십시오
또한보십시오에 대한 직접 링크

  • PlatformFilesystem: 파일 시스템 공급자에 대한 참조입니다.
  • PlatformSandbox: 체크포인트 복구 및 복제를 포함한 샌드박스 공급자에 대한 참조입니다.
  • 환경: 환경이 작업 공간, 변수 및 데이터베이스의 범위를 지정하는 방법입니다.
On this page