> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# 작업공간

에이[workspace](https://mastra.zisheng.pro/ko/docs/workspace/overview)Agent 파일 시스템 액세스 및 명령 실행을 제공합니다. 파일 기반 Agent는 다음을 통해 검색되면 자동으로 기본 작업 공간을 얻습니다.`mastra dev`또는`mastra build`, 추가 구성 없이 파일을 읽고 쓸 수 있으며 셸 명령을 실행할 수 있습니다.

파일 기반 규칙에 대해서는 이 페이지를 사용하십시오. 작업 영역 공급자, Tool, 검색, 수명 주기 및 샌드박스 세부 정보는 다음을 참조하세요.[Workspaces](https://mastra.zisheng.pro/ko/docs/workspace/overview).

## 기본 작업공간

`workspace.ts`가 없으면 빌드에서 Agent별 Workspace 경로를 제공할 때 파일 기반 Agent에 기본 [`Workspace`](https://mastra.zisheng.pro/ko/reference/workspace/workspace-class)가 지정됩니다. 기본 Workspace는 다음을 사용합니다.

- [`LocalFilesystem`](https://mastra.zisheng.pro/ko/reference/workspace/local-filesystem)Agent의 번들 작업 공간 디렉터리에 루트가 있습니다.
- [`LocalSandbox`](https://mastra.zisheng.pro/ko/reference/workspace/local-sandbox)동일한 작업 디렉토리를 사용합니다.

그러면 Agent 파일 Tool와 셸 Tool이 자동으로 제공됩니다. 기본 작업 영역은 Agent별로 이루어집니다. 하위 Agent는 상위 Agent의 작업 영역 경로 아래에 중첩된 작업 영역 디렉터리를 가져옵니다.

## 빠른 시작

기본 작업공간의 경우 파일을 추가하지 마세요. 다음과 같은 Agent 디렉터리로 시작하세요.

```text
src/mastra/agents/weather/
├── config.ts
└── instructions.md
```

Workspace를 사용자 지정해야 할 때만 `workspace.ts`를 추가하세요.

```typescript
import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace'

export default new Workspace({
  name: 'weather-workspace',
  filesystem: new LocalFilesystem({ basePath: './data/weather' }),
  sandbox: new LocalSandbox({ workingDirectory: './data/weather' }),
})
```

전체 구성은 [`Workspace` 참조](https://mastra.zisheng.pro/ko/reference/workspace/workspace-class)를 확인하세요.

## 작업공간을 사용자 정의해야 하는 경우

기본 로컬 디렉토리가 충분하지 않은 경우 작업공간을 사용자 정의하십시오. 일반적인 이유는 다음과 같습니다.

- 다른 파일 시스템 루트에 있는 포인트 파일 Tool.
- 다른 샌드박스 공급자에서 셸 명령을 실행합니다.
- BM25 또는 벡터 검색으로 작업공간 검색을 추가하세요.
- 여러 Agent가 하나의 작업 공간을 공유합니다.

Provider 패턴 및 런타임 동작은 [Workspace 개요](https://mastra.zisheng.pro/ko/docs/workspace/overview), [Sandbox 가이드](https://mastra.zisheng.pro/ko/docs/workspace/sandbox), [Workspace 검색](https://mastra.zisheng.pro/ko/docs/workspace/search)을 참조하세요.

## 런타임 경계

Workspace 파일 시스템은 Tool이 읽고 쓸 수 있는 파일을 제어합니다. Sandbox는 셸 명령이 실행되는 위치를 제어합니다. [`tools/`](https://mastra.zisheng.pro/ko/reference/file-based-agents/tools)의 코드를 포함한 애플리케이션 런타임 코드는 Workspace 또는 Sandbox API를 명시적으로 호출하지 않는 한 앱/서버 프로세스에서 계속 실행됩니다.

## 시드 파일

Agent에 초기 파일을 포함하려면 `workspace/` 디렉터리를 추가하세요. Mastra는 빌드 시 `workspace/` 아래의 파일을 Agent의 기본 런타임 Workspace로 미러링하므로 Agent는 해당 파일이 디스크에 있는 상태로 시작합니다.

```text
src/mastra/agents/weather/
├── config.ts
└── workspace/
    ├── README.md
    └── data/
        └── cities.json
```

파일은 작업 공간 파일 Tool와 샌드박스 명령이 읽을 수 있는 번들 작업 공간 경로에 복사됩니다. 미러링 중에는 Symlinked 시드 파일을 건너뜁니다.

## 구성 우선순위

`config.workspace`가 `workspace.ts`보다 우선합니다. 둘 다 없으면 기본 파일 기반 Workspace가 사용됩니다. 전체 병합 표는 [`config.ts` 우선순위](https://mastra.zisheng.pro/ko/reference/file-based-agents/config)를 참조하세요.