> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt # 작업실 수업 **추가된 항목:** `@mastra/core@1.1.0` `Workspace` 클래스는 파일 시스템과 Sandbox를 결합하여 Agent에 파일 저장 및 명령 실행 기능을 제공합니다. 또한 인덱싱된 콘텐츠에 대한 BM25 및 벡터 검색을 지원합니다. ## 사용예 ```typescript import { Workspace, LocalFilesystem, LocalSandbox } from '@mastra/core/workspace' const workspace = new Workspace({ id: 'my-workspace', name: 'My Workspace', filesystem: new LocalFilesystem({ basePath: './workspace', }), sandbox: new LocalSandbox({ workingDirectory: './workspace', }), bm25: true, autoIndexPaths: ['docs'], }) ``` ## 생성자 매개변수 **id** (`string`): Workspace의 고유 식별자입니다. (Default: `자동 생성`) **name** (`string`): 사람이 읽을 수 있는 이름입니다. (Default: `workspace-{id}`) **filesystem** (`WorkspaceFilesystem | WorkspaceFilesystemResolver`): 파일 시스템 Provider 인스턴스 또는 requestContext를 받아 요청별 파일 시스템을 반환하는 리졸버 함수입니다. 동적 파일 시스템을 참조하세요. **sandbox** (`WorkspaceSandbox | WorkspaceSandboxResolver`): Sandbox Provider 인스턴스 또는 requestContext를 받아 요청별 Sandbox를 반환하는 리졸버 함수입니다. 동적 Sandbox를 참조하세요. **instructions.dynamicSandbox** (`'placeholder' | 'resolve' | (({ requestContext }) => string)`): 리졸버 기반 sandbox가 Workspace 지침에 반영되는 방식을 제어합니다. 'placeholder'(기본값)은 리졸버를 호출하지 않고 고정된 텍스트를 출력합니다. 'resolve'는 리졸버를 호출하고 Sandbox 자체 지침을 사용합니다. 함수를 지정하면 리졸빙하지 않고 사용자 지정 텍스트를 반환합니다. 정적 Sandbox에는 영향을 주지 않습니다. (Default: `'placeholder'`) **sandboxCacheKey** (`({ requestContext }) => string | undefined`): 리졸버 기반 sandbox의 고정 캐시 키입니다. 설정하면 리졸빙된 Sandbox가 RequestContext 인스턴스별이 아닌 키별로 메모이제이션되므로, 백그라운드 프로세스 Tool이 후속 요청에서도 동일한 Sandbox에 접근합니다. 정적 Sandbox에는 영향을 주지 않습니다. **bm25** (`boolean | BM25Config`): BM25 키워드 검색을 활성화합니다. 기본값을 사용하려면 true를, 별도 설정을 사용하려면 구성 객체를 전달하세요. (Default: `undefined`) **vectorStore** (`MastraVector`): 의미 검색에 사용할 벡터 저장소입니다. **embedder** (`Embedder`): 텍스트를 벡터로 변환하는 함수입니다. vectorStore가 설정된 경우 필수입니다. 단일 텍스트 함수 (text: string) => Promise\ 또는 batch: true 속성과 선택적 maxBatchSize를 갖는 배치 지원 함수 (texts: string\[]) => Promise\를 받습니다. 배치 임베딩을 참조하세요. **autoIndexPaths** (`string[]`): init() 시 자동으로 인덱싱할 경로 또는 glob 패턴입니다. 선택적 인덱싱을 위해 '\*\*/\*.md'와 같은 glob 패턴을 지원합니다. **skills** (`string[] | ((context: SkillsContext) => string[] | Promise)`): SKILL.md 파일이 있는 경로입니다. 정적 배열이나 경로를 동적으로 리졸빙하는 비동기 함수일 수 있습니다. 탐색을 위해 './\*\*/skills'와 같은 glob 패턴을 지원합니다. **skillSource** (`SkillSource`): Skill 탐색을 위한 사용자 지정 Skill 소스입니다. 지정하면 Workspace 파일 시스템 대신 이 소스를 사용합니다. 콘텐츠 주소 지정 가능 blob 저장소에서 게시된 Skill 버전을 제공하려면 VersionedSkillSource를 사용하세요. **onMount** (`OnMountHook`): 각 파일 시스템을 Sandbox에 마운트하기 전에 호출되는 사전 마운트 훅입니다. 마운트를 건너뛰려면 false를 반환하고, 훅이 마운트를 처리했다면 { success: true }를 반환하세요. 기본 마운트 동작을 사용하려면 undefined를 반환하세요. **searchIndexName** (`string`): 벡터 저장소의 사용자 지정 인덱스 이름입니다. 유효한 SQL 식별자여야 합니다(문자 또는 밑줄로 시작하고 문자, 숫자 또는 밑줄만 포함하며 최대 63자). 기본값은 정리된 '{id}\_search' 버전입니다. **tools** (`WorkspaceToolsConfig`): Tool 활성화 및 안전 옵션 설정을 위한 Tool별 구성입니다. **tools.enabled** (`boolean`): Agent가 Tool을 사용할 수 있는지 여부입니다. **tools.requireApproval** (`boolean`): Tool 실행 전에 사용자 승인이 필요한지 여부입니다. **tools.name** (`string`): 이 Tool을 노출할 사용자 지정 이름입니다. 기본 mastra\_workspace\_\* 이름을 대체합니다. 구성 키에는 여전히 원래 WORKSPACE\_TOOLS 상수를 사용해야 합니다. **tools.requireReadBeforeWrite** (`boolean`): 쓰기 Tool의 경우 덮어쓰기를 방지하기 위해 먼저 파일을 읽도록 요구합니다. **tools.maxOutputTokens** (`number`): Tool 출력의 최대 토큰 수입니다. 이 제한을 초과하는 출력은 tiktoken을 사용하여 잘립니다. **tools.writeLockTimeoutMs** (`number`): 쓰기 Tool이 실패하기 전에 파일별 쓰기 잠금을 획득하기 위해 대기하는 최대 시간(밀리초)입니다. 느리거나 콜드 스타트가 발생하는 파일 시스템(예: 원격 Sandbox)의 경우 이 값을 늘리세요. **tools.hooks** (`WorkspaceToolHooks`): 활성화된 모든 Workspace Tool 호출 전후에 실행되는 훅입니다. 아래의 Tool 훅을 참조하세요. **operationTimeout** (`number`): 작업 시간 제한(밀리초)입니다. ## Tool 구성 `tools` 옵션은 활성화할 Workspace Tool과 안전 설정을 제어하는 `WorkspaceToolsConfig` 객체를 받습니다. ```typescript import { Workspace } from '@mastra/core/workspace' import { WORKSPACE_TOOLS } from '@mastra/core/workspace' const workspace = new Workspace({ id: 'my-workspace', name: 'My Workspace', tools: { // Global defaults (apply to all tools) enabled: true, requireApproval: false, // Per-tool overrides using WORKSPACE_TOOLS constants [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: { requireApproval: true, }, }, }) ``` 구성 개체는 두 부분으로 구성됩니다. - **전역 기본값** (`enabled`, `requireApproval`): 재정의하지 않는 한 모든 Tool에 적용됩니다. - **Tool별 재정의**: 개별 Tool을 구성하려면 `WORKSPACE_TOOLS` 상수를 키로 사용합니다. 더 많은 예제는 [Workspace 개요](https://mastra.zisheng.pro/ko/docs/workspace/overview)를 참조하세요. ### Tool 이름 다시 매핑 개별 Tool 구성에 `name` 속성을 설정하여 Workspace Tool의 이름을 변경합니다. 구성 키는 원래 상수로 유지되며 Agent에 노출되는 이름만 변경됩니다. ```typescript import { Workspace } from '@mastra/core/workspace' import { WORKSPACE_TOOLS } from '@mastra/core/workspace' const workspace = new Workspace({ id: 'my-workspace', name: 'My Workspace', tools: { [WORKSPACE_TOOLS.FILESYSTEM.READ_FILE]: { name: 'view' }, [WORKSPACE_TOOLS.FILESYSTEM.GREP]: { name: 'search_content' }, }, }) ``` Tool 이름은 모든 작업공간 Tool에서 고유해야 합니다. 다른 Tool의 기본 또는 사용자 정의 이름과 충돌하는 사용자 정의 이름을 설정하면 오류가 발생합니다. ### Tool 후크 활성화된 모든 Workspace Tool 호출 전후에 로직을 실행하려면 `tools.hooks`를 설정하세요. 훅은 이름 재매핑 후 실행되므로 컨텍스트에 노출된 `toolName`과 원래 `workspaceToolName`이 모두 포함됩니다. ```typescript import { Workspace } from '@mastra/core/workspace' const workspace = new Workspace({ id: 'my-workspace', tools: { hooks: { beforeToolCall: ({ toolName, workspaceToolName, input }) => { console.log(`Running ${toolName} (${workspaceToolName})`, input) }, afterToolCall: ({ toolName, output, error }) => { console.log(`Finished ${toolName}`, { output, error }) }, }, }, }) ``` **beforeToolCall** (`(context: WorkspaceToolHookContext) => void | WorkspaceToolBeforeHookResult | Promise`): Workspace Tool이 실행되기 전에 실행됩니다. { toolName, workspaceToolName, input, context }를 받습니다. Tool 호출을 건너뛰고 output을 결과로 사용하려면 { proceed: false, output }을 반환하세요. **afterToolCall** (`(context: WorkspaceToolAfterHookContext) => void | Promise`): Workspace Tool이 실행된 후 실행됩니다. { toolName, workspaceToolName, input, context, output, error }를 받습니다. Tool에서 예외가 발생하면 output은 undefined이고 대신 error가 설정됩니다. Agent에도 [Tool 훅](https://mastra.zisheng.pro/ko/reference/agents/agent)이 정의되어 있으면 Workspace 훅은 Agent 훅 래퍼 내부에서 실행됩니다. 순서는 Agent `beforeToolCall` → Workspace `beforeToolCall` → Tool → Workspace `afterToolCall` → Agent `afterToolCall`입니다. ## 속성 **id** (`string`): Workspace 식별자입니다. **name** (`string`): Workspace 이름입니다. **status** (`WorkspaceStatus`): 'pending' | 'initializing' | 'ready' | 'paused' | 'error' | 'destroying' | 'destroyed' **filesystem** (`WorkspaceFilesystem | undefined`): 정적 파일 시스템 Provider입니다. 리졸버 함수가 구성된 경우 undefined를 반환합니다. 사용 가능 여부를 확인하려면 hasFilesystemConfig()를 사용하세요. **sandbox** (`WorkspaceSandbox | undefined`): 정적 Sandbox Provider입니다. 리졸버 함수가 구성된 경우 undefined를 반환합니다. 사용 가능 여부를 확인하려면 hasSandboxConfig()를 사용하세요. **skills** (`WorkspaceSkills | undefined`): SKILL.md 파일에 접근하기 위한 Skill 인터페이스입니다. **canBM25** (`boolean`): BM25 검색을 사용할 수 있는지 여부입니다. **canVector** (`boolean`): 벡터 검색을 사용할 수 있는지 여부입니다. **canHybrid** (`boolean`): 하이브리드 검색을 사용할 수 있는지 여부입니다. ## 행동 양식 ### 수명주기 #### `init()` 작업공간을 초기화하고 리소스를 준비합니다. ```typescript await workspace.init() ``` 대부분의 경우 `init()` 호출은 선택 사항입니다. - **Sandbox**: 첫 번째 `executeCommand()` 호출 시 자동으로 시작됩니다. 첫 명령의 지연을 방지하려면 `init()`을 사용하세요. - **파일 시스템**: 기본 디렉터리를 생성하고 Provider별 설정을 실행합니다. 일부 Provider는 첫 번째 작업 시 디렉터리를 자동으로 생성합니다. - **검색**: 자동 인덱싱에 `autoIndexPaths`를 사용하는 경우에만 필요합니다. 초기화는 다음을 수행합니다. - 파일 시스템 Provider를 시작합니다(필요한 경우 기본 디렉터리 생성). - Sandbox Provider를 시작합니다(작업 디렉터리 생성 및 구성된 경우 격리 설정). - 검색을 위해 `autoIndexPaths`의 파일을 인덱싱합니다. #### `destroy()` 작업공간을 삭제하고 리소스를 정리합니다. ```typescript await workspace.destroy() ``` `destroy()`언어 서버, 브라우저, 샌드박스 공급자, 파일 시스템 공급자 순서로 작업 영역 소유 리소스를 닫습니다. 또한 캐시된 샌드박스 참조도 삭제됩니다. 애플리케이션에서 Workspace 사용을 마치면 `destroy()`를 호출하세요. `mastra.shutdown()`은 종료 시 등록된 Workspace에 대해 이 메서드를 호출합니다. Mastra 레지스트리에서 Workspace를 제거하려면 [`mastra.removeWorkspace()`](https://mastra.zisheng.pro/ko/reference/core/removeWorkspace)를 사용하세요. `LocalFilesystem.destroy()`디스크의 파일을 삭제하지 않습니다. 확인자 지원 파일 시스템 및 샌드박스 공급자는 애플리케이션이 소유하며 애플리케이션에서 정리해야 합니다. ### 검색 작업 #### `index(path, content, options?)` 검색을 위해 콘텐츠를 색인화합니다. ```typescript await workspace.index('/docs/guide.md', 'Guide content...') ``` #### `search(query, options?)` 색인화된 콘텐츠를 검색합니다. ```typescript const results = await workspace.search('password reset', { topK: 10, mode: 'hybrid', }) ``` ### 공익사업 #### `getInfo()` 작업공간 정보를 얻으세요. ```typescript const info = await workspace.getInfo() // { id, name, status, createdAt, lastAccessedAt, filesystem?, sandbox? } ``` 리졸버를 호출하지 않고 리졸버 기반 Provider를 런타임 정의로 보고하려면 `resolveDynamicProviders: false`를 전달하세요. ```typescript const info = await workspace.getInfo({ resolveDynamicProviders: false }) ``` **매개변수:** **options.includeFileCount** (`boolean`): 전체 파일 수를 계산할지 여부입니다. 대규모 Workspace에서는 느릴 수 있습니다. **options.requestContext** (`RequestContext`): resolveDynamicProviders가 활성화된 경우 동적 Provider 리졸버에 전달됩니다. **options.resolveDynamicProviders** (`boolean`): 동적 Provider 리졸버를 호출할지 여부입니다. 메타데이터만 필요하고 리졸버 기반 Provider를 dynamic으로 보고하려면 false로 설정하세요. (Default: `true`) #### `getInstructions(opts?)` 파일 시스템 및 샌드박스 공급자의 결합된 명령을 반환합니다. 실행 컨텍스트를 이해하는 데 도움이 되도록 Agent의 시스템 메시지에 삽입됩니다. ```typescript const instructions = workspace.getInstructions() ``` Provider의 `instructions` 옵션이 함수일 때 요청별 사용자 지정을 활성화하려면 `requestContext`를 전달하세요. ```typescript const instructions = workspace.getInstructions({ requestContext }) ``` **매개변수:** **opts.requestContext** (`RequestContext`): 구성된 경우 파일 시스템 또는 Sandbox Provider의 instructions 함수로 전달됩니다. **보고:** `string` #### `getInstructionsAsync(opts?)` 결합된 Workspace 지침을 반환합니다. Workspace가 리졸버 기반 Provider를 사용하는 경우 이를 리졸빙합니다. 런타임 정의 파일 시스템은 요청별로 리졸빙됩니다. 런타임 정의 Sandbox는 `instructions.dynamicSandbox`가 `'resolve'`로 설정된 경우를 제외하고 고정된 자리표시자 텍스트를 제공합니다. ```typescript const instructions = await workspace.getInstructionsAsync({ requestContext }) ``` **매개변수:** **opts.requestContext** (`RequestContext`): 동적 파일 시스템 리졸버에 전달되며, instructions.dynamicSandbox가 'resolve'인 경우 동적 Sandbox 리졸버에도 전달됩니다. **보고:** `Promise` 기본 출력을 재정의하려면 [LocalFilesystem](https://mastra.zisheng.pro/ko/reference/workspace/local-filesystem) 또는 [LocalSandbox](https://mastra.zisheng.pro/ko/reference/workspace/local-sandbox)에 `instructions` 옵션을 지정하세요. #### `getToolsConfig()` 현재 Tool 구성을 가져옵니다. ```typescript const config = workspace.getToolsConfig() ``` **보고:** `WorkspaceToolsConfig | undefined` #### `setToolsConfig(config?)` 런타임에 Tool별 구성을 교체합니다. 전체 구성을 교체하며 이전 구성과 병합하지 않습니다. 기본값으로 재설정하려면 `undefined`를 전달하세요. 변경 사항은 다음 Agent 상호작용(다음 `createWorkspaceTools()` 호출)부터 적용됩니다. ```typescript import { WORKSPACE_TOOLS } from '@mastra/core/workspace' // Disable write tools for read-only mode workspace.setToolsConfig({ [WORKSPACE_TOOLS.FILESYSTEM.WRITE_FILE]: { enabled: false }, [WORKSPACE_TOOLS.FILESYSTEM.EDIT_FILE]: { enabled: false }, }) // Reset to defaults workspace.setToolsConfig(undefined) ``` **매개변수:** **config** (`WorkspaceToolsConfig | undefined`): 적용할 새 Tool 구성입니다. 기본값으로 재설정하려면 undefined를 전달하세요. ### 동적 파일 시스템 #### `hasFilesystemConfig()` 파일 시스템이 정적 인스턴스 또는 리졸버 함수로 구성되어 있는지 확인합니다. 리졸버 기반 Workspace의 `filesystem` 속성은 `undefined`를 반환하므로 `workspace.filesystem`을 직접 확인하는 대신 이 메서드를 사용하세요. ```typescript if (workspace.hasFilesystemConfig()) { // Filesystem tools are available } ``` **보고:** `boolean` #### `resolveFilesystem({ requestContext })` 요청 컨텍스트에 대한 파일 시스템을 리졸빙합니다. 리졸버 함수가 구성되어 있으면 제공된 `requestContext`로 호출합니다. 정적 파일 시스템이 구성되어 있으면 이를 직접 반환합니다. 파일 시스템이 구성되지 않았으면 `undefined`를 반환합니다. ```typescript import { RequestContext } from '@mastra/core/request-context' const ctx = new RequestContext([['agent-role', 'admin']]) const fs = await workspace.resolveFilesystem({ requestContext: ctx }) ``` **매개변수:** **requestContext** (`RequestContext`): 리졸버 함수에 전달할 요청 컨텍스트입니다. **보고:** `Promise` ### 동적 샌드박스 #### `hasSandboxConfig()` Sandbox가 정적 인스턴스 또는 리졸버 함수로 구성되어 있는지 확인합니다. 리졸버 기반 Workspace의 `sandbox` 속성은 `undefined`를 반환하므로 `workspace.sandbox`를 직접 확인하는 대신 이 메서드를 사용하세요. ```typescript if (workspace.hasSandboxConfig()) { // Sandbox tools are available } ``` **보고:** `boolean` #### `resolveSandbox({ requestContext })` 요청 컨텍스트에 대한 Sandbox를 리졸빙합니다. 리졸버 함수가 구성되어 있으면 제공된 `requestContext`로 호출합니다. 정적 Sandbox가 구성되어 있으면 이를 직접 반환합니다. Sandbox가 구성되지 않았으면 `undefined`를 반환합니다. ```typescript import { RequestContext } from '@mastra/core/request-context' const ctx = new RequestContext([['user-id', 'alice']]) const sandbox = await workspace.resolveSandbox({ requestContext: ctx }) ``` **매개변수:** **requestContext** (`RequestContext`): 리졸버 함수에 전달할 요청 컨텍스트입니다. **보고:** `Promise` #### `clearSandboxCache(cacheKey?)` `sandboxCacheKey`로 캐시된 리졸버 기반 Sandbox를 지웁니다. 하나의 항목을 지우려면 캐시 키를 전달하고, 키가 지정된 모든 Sandbox 항목을 지우려면 생략하세요. 이 메서드는 `RequestContext`별 약한 참조 캐시를 지우지 않습니다. 해당 항목은 가비지 컬렉션으로 관리됩니다. 작업 영역에는 확인자가 반환한 샌드박스가 없습니다. 이 방법은 작업공간 참조만 삭제합니다. 자신의 라이프사이클 코드에서 샌드박스를 삭제하세요. ```typescript workspace.clearSandboxCache('thread-123') workspace.clearSandboxCache() ``` **매개변수:** **cacheKey** (`string`): 지울 캐시 키입니다. 키가 지정된 모든 Sandbox 항목을 지우려면 이 값을 생략하세요. **보고:** `void` ## Agent Tool 작업 영역은 구성된 내용에 따라 Agent에 Tool을 제공합니다. ### 파일 시스템 Tool 파일 시스템이 구성되면 추가됩니다. | Tool | 설명 | | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | `mastra_workspace_read_file` | 파일 내용을 읽습니다. 텍스트 파일은 텍스트로 반환됩니다(선택적 줄 범위 지원). 이미지와 PDF는 Model이 직접 볼 수 있는 네이티브 미디어 파트로 반환됩니다. 명시적인 `encoding`을 전달하지 않는 한 그 밖의 바이너리는 메타데이터만 반환합니다. | | `mastra_workspace_write_file` | 새 콘텐츠로 파일을 생성하거나 덮어씁니다. 상위 디렉터리를 자동으로 생성합니다. | | `mastra_workspace_edit_file` | 텍스트를 찾아 바꾸는 방식으로 기존 파일을 편집합니다. 전체 파일을 다시 작성하지 않고 원하는 부분만 변경할 때 유용합니다. | | `mastra_workspace_list_files` | 디렉터리 내용을 트리 구조로 나열합니다. 깊이 제한을 적용한 재귀적 나열, glob 패턴 및 `.gitignore` 필터링(기본적으로 활성화)을 지원합니다. | | `mastra_workspace_delete` | 파일 또는 디렉터리를 삭제합니다. 디렉터리의 재귀적 삭제를 지원합니다. | | `mastra_workspace_file_stat` | 크기, 유형, 수정 시간을 포함한 파일 또는 디렉터리의 메타데이터를 가져옵니다. | | `mastra_workspace_mkdir` | 디렉터리를 생성합니다. 상위 디렉터리가 없으면 자동으로 생성합니다. | | `mastra_workspace_grep` | 정규식 패턴으로 파일 내용을 검색합니다. glob 필터링, 컨텍스트 줄 및 대소문자를 구분하지 않는 검색을 지원합니다. | | 정적 파일 시스템을 사용하면 파일 시스템이 읽기 전용 모드일 때 쓰기 Tool(`write_file`, `edit_file`, `delete`, `mkdir`)이 제외됩니다. [런타임 정의 파일 시스템](https://mastra.zisheng.pro/ko/docs/workspace/filesystem)을 사용하면 쓰기 Tool이 항상 포함되며 읽기 전용 여부는 런타임에 적용됩니다. | | | `read_file` Tool은 `mediaTypes` 및 `maxMediaBytes` 옵션을 받아, 어떤 MIME 유형을 네이티브 미디어 파트로 Model에 제공할지와 해당 파일의 최대 크기를 제어합니다. | | **mediaTypes** (`string[] | ((mimeType: string) => boolean) | false`): 텍스트가 아닌 미디어 파트(파일/이미지 파트)로 Model에 제공할 MIME 유형입니다. glob 배열(예: \['image/\*']), 사용자 지정 조건자 함수 또는 미디어 감지를 비활성화하는 false를 받습니다. 기본값은 여러 Provider에서 안전하게 사용할 수 있는 이미지 형식과 PDF의 교집합입니다. 호출자가 명시적인 encoding을 전달하지 않은 경우에만 적용됩니다. (Default: `['image/png', 'image/jpeg', 'image/webp', 'application/pdf']`) **maxMediaBytes** (`number`): 미디어 파트로 인라인 처리할 최대 파일 크기(바이트)입니다. 이보다 큰 파일은 전체가 base64로 인코딩되어 컨텍스트에 포함되고 리하이드레이션 시 저장소에 유지되는 대신 메타데이터 전용 출력으로 대체됩니다. (Default: `10 * 1024 * 1024 (10 MiB)`) ```typescript const workspace = new Workspace({ filesystem: new LocalFilesystem({ basePath: './workspace' }), tools: { [WORKSPACE_TOOLS.FILESYSTEM.READ_FILE]: { // Broaden to any image (including SVG, BMP, HEIC) — may fail on some providers mediaTypes: ['image/*'], // Raise the inline-media cap to 25 MiB maxMediaBytes: 25 * 1024 * 1024, }, }, }) ``` ### 샌드박스 Tool 샌드박스가 구성되면 추가됩니다. | Tool | 설명 | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | `mastra_workspace_execute_command` | 셸 명령을 실행합니다. stdout, stderr 및 종료 코드를 반환합니다. Sandbox에 프로세스 관리자가 있으면 `background: true`를 받아 장기 실행 프로세스를 생성하고 PID를 반환합니다. | | `mastra_workspace_get_process_output` | PID로 백그라운드 프로세스의 stdout, stderr 및 상태를 가져옵니다. 출력 줄 수를 제한하는 `tail`과 종료될 때까지 차단하는 `wait: true`를 받습니다. Sandbox에 프로세스 관리자가 있는 경우에만 사용할 수 있습니다. | | `mastra_workspace_kill_process` | PID로 백그라운드 프로세스를 종료합니다. 출력의 마지막 50줄을 반환합니다. Sandbox에 프로세스 관리자가 있는 경우에만 사용할 수 있습니다. | | 정적 Sandbox를 사용하면 기능 검사(`executeCommand`, `processes`)를 통해 노출할 Tool 변형을 결정합니다. [런타임 정의 Sandbox](https://mastra.zisheng.pro/ko/docs/workspace/sandbox)를 사용하면 모든 Sandbox Tool이 등록되며, 리졸빙된 Sandbox가 요청된 기능을 구현하지 않은 경우 런타임에서 명확한 오류를 발생시킵니다. | | | `execute_command` Tool은 백그라운드 프로세스의 수명 주기 콜백을 위한 `backgroundProcesses` 옵션을 받습니다. | | **backgroundProcesses** (`BackgroundProcessesConfig`): 백그라운드 프로세스 처리 구성입니다. Sandbox가 백그라운드 실행을 지원하는 경우에만 적용됩니다. **backgroundProcesses.onStdout** (`(data: string, meta: BackgroundProcessMeta) => void`): 백그라운드 프로세스에서 전달되는 stdout 청크의 콜백입니다. **backgroundProcesses.onStderr** (`(data: string, meta: BackgroundProcessMeta) => void`): 백그라운드 프로세스에서 전달되는 stderr 청크의 콜백입니다. **backgroundProcesses.onExit** (`(meta: BackgroundProcessExitMeta) => void`): 백그라운드 프로세스가 종료될 때 호출되는 콜백입니다. Meta에는 pid, exitCode, stdout 및 stderr가 포함됩니다. **backgroundProcesses.abortSignal** (`AbortSignal | null | false`): 백그라운드 프로세스의 중단 신호입니다. undefined(기본값)는 Agent의 신호를 사용합니다. null 또는 false는 중단을 비활성화하므로 Agent가 종료된 후에도 프로세스가 유지됩니다. 사용 예제는 [백그라운드 프로세스 콜백](https://mastra.zisheng.pro/ko/docs/workspace/sandbox)을 참조하세요. ### 검색 Tool BM25 또는 벡터 검색이 구성된 경우 추가됨: | Tool | 설명 | | --------------------------------------- | ------------------------------------------------------------------------------ | | `mastra_workspace_search` | 키워드(BM25), 의미(벡터) 또는 하이브리드 검색을 사용하여 인덱싱된 콘텐츠를 검색합니다. 점수에 따라 순위가 지정된 결과를 반환합니다. | | `mastra_workspace_index` | 검색할 콘텐츠를 인덱싱합니다. 나중에 검색할 수 있도록 콘텐츠를 경로와 연결합니다. | | 파일 시스템이 읽기 전용 모드이면 `index` Tool이 제외됩니다. | | ### 스킬 Tool 스킬 구성 시 추가됨: | Tool | 설명 | | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- | | `skill` | 이름 또는 경로로 Skill을 활성화합니다. Skill의 전체 지침, 참조 자료, 스크립트 및 에셋을 반환합니다. | | `skill_search` | Skill 콘텐츠 전체를 검색합니다. 필터링할 Skill 이름의 선택적 목록과 `topK` 매개변수를 받습니다. | | `skill_read` | Skill 디렉터리에서 특정 파일(참조 자료, 스크립트 또는 에셋)을 읽습니다. | | 여러 Skill이 동일한 이름을 공유하면 `list()`는 모두 반환합니다. 이름으로 `get()`을 호출하면 우선순위 규칙(local > managed > external)이 적용됩니다. 두 Skill의 이름과 소스 유형이 모두 같으면 `get()`에서 오류가 발생합니다. 우선순위 규칙을 적용하지 않으려면 Skill의 전체 경로를 `get()`에 전달하세요. 자세한 내용은 [이름이 같은 Skill](https://mastra.zisheng.pro/ko/docs/workspace/skills)을 참조하세요. | |