작업실 수업
추가된 항목: @mastra/core@1.1.0
Workspace 클래스는 파일 시스템과 Sandbox를 결합하여 Agent에 파일 저장 및 명령 실행 기능을 제공합니다. 또한 인덱싱된 콘텐츠에 대한 BM25 및 벡터 검색을 지원합니다.
사용예사용예에 대한 직접 링크
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?:
name?:
filesystem?:
requestContext를 받아 요청별 파일 시스템을 반환하는 리졸버 함수입니다. 동적 파일 시스템을 참조하세요.sandbox?:
requestContext를 받아 요청별 Sandbox를 반환하는 리졸버 함수입니다. 동적 Sandbox를 참조하세요.instructions.dynamicSandbox?:
sandbox가 Workspace 지침에 반영되는 방식을 제어합니다. 'placeholder'(기본값)은 리졸버를 호출하지 않고 고정된 텍스트를 출력합니다. 'resolve'는 리졸버를 호출하고 Sandbox 자체 지침을 사용합니다. 함수를 지정하면 리졸빙하지 않고 사용자 지정 텍스트를 반환합니다. 정적 Sandbox에는 영향을 주지 않습니다.sandboxCacheKey?:
sandbox의 고정 캐시 키입니다. 설정하면 리졸빙된 Sandbox가 RequestContext 인스턴스별이 아닌 키별로 메모이제이션되므로, 백그라운드 프로세스 Tool이 후속 요청에서도 동일한 Sandbox에 접근합니다. 정적 Sandbox에는 영향을 주지 않습니다.bm25?:
vectorStore?:
embedder?:
vectorStore가 설정된 경우 필수입니다. 단일 텍스트 함수 (text: string) => Promise<number[]> 또는 batch: true 속성과 선택적 maxBatchSize를 갖는 배치 지원 함수 (texts: string[]) => Promise<number[][]>를 받습니다. 배치 임베딩을 참조하세요.autoIndexPaths?:
skills?:
skillSource?:
onMount?:
searchIndexName?:
tools?:
enabled?:
requireApproval?:
name?:
mastra_workspace_* 이름을 대체합니다. 구성 키에는 여전히 원래 WORKSPACE_TOOLS 상수를 사용해야 합니다.requireReadBeforeWrite?:
maxOutputTokens?:
writeLockTimeoutMs?:
hooks?:
operationTimeout?:
Tool 구성Tool 구성에 대한 직접 링크
tools 옵션은 활성화할 Workspace Tool과 안전 설정을 제어하는 WorkspaceToolsConfig 객체를 받습니다.
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 개요를 참조하세요.
Tool 이름 다시 매핑Tool 이름 다시 매핑에 대한 직접 링크
개별 Tool 구성에 name 속성을 설정하여 Workspace Tool의 이름을 변경합니다. 구성 키는 원래 상수로 유지되며 Agent에 노출되는 이름만 변경됩니다.
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 후크Tool 후크에 대한 직접 링크
활성화된 모든 Workspace Tool 호출 전후에 로직을 실행하려면 tools.hooks를 설정하세요. 훅은 이름 재매핑 후 실행되므로 컨텍스트에 노출된 toolName과 원래 workspaceToolName이 모두 포함됩니다.
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?:
{ toolName, workspaceToolName, input, context }를 받습니다. Tool 호출을 건너뛰고 output을 결과로 사용하려면 { proceed: false, output }을 반환하세요.afterToolCall?:
{ toolName, workspaceToolName, input, context, output, error }를 받습니다. Tool에서 예외가 발생하면 output은 undefined이고 대신 error가 설정됩니다.Agent에도 Tool 훅이 정의되어 있으면 Workspace 훅은 Agent 훅 래퍼 내부에서 실행됩니다. 순서는 Agent beforeToolCall → Workspace beforeToolCall → Tool → Workspace afterToolCall → Agent afterToolCall입니다.
속성속성에 대한 직접 링크
id:
name:
status:
filesystem:
undefined를 반환합니다. 사용 가능 여부를 확인하려면 hasFilesystemConfig()를 사용하세요.sandbox:
undefined를 반환합니다. 사용 가능 여부를 확인하려면 hasSandboxConfig()를 사용하세요.skills:
canBM25:
canVector:
canHybrid:
행동 양식행동 양식에 대한 직접 링크
수명주기수명주기에 대한 직접 링크
init()init에 대한 직접 링크
작업공간을 초기화하고 리소스를 준비합니다.
await workspace.init()
대부분의 경우 init() 호출은 선택 사항입니다.
-
Sandbox: 첫 번째
executeCommand()호출 시 자동으로 시작됩니다. 첫 명령의 지연을 방지하려면init()을 사용하세요. -
파일 시스템: 기본 디렉터리를 생성하고 Provider별 설정을 실행합니다. 일부 Provider는 첫 번째 작업 시 디렉터리를 자동으로 생성합니다.
-
검색: 자동 인덱싱에
autoIndexPaths를 사용하는 경우에만 필요합니다. 초기화는 다음을 수행합니다. -
파일 시스템 Provider를 시작합니다(필요한 경우 기본 디렉터리 생성).
-
Sandbox Provider를 시작합니다(작업 디렉터리 생성 및 구성된 경우 격리 설정).
-
검색을 위해
autoIndexPaths의 파일을 인덱싱합니다.
destroy()destroy에 대한 직접 링크
작업공간을 삭제하고 리소스를 정리합니다.
await workspace.destroy()
destroy()언어 서버, 브라우저, 샌드박스 공급자, 파일 시스템 공급자 순서로 작업 영역 소유 리소스를 닫습니다. 또한 캐시된 샌드박스 참조도 삭제됩니다.
애플리케이션에서 Workspace 사용을 마치면 destroy()를 호출하세요. mastra.shutdown()은 종료 시 등록된 Workspace에 대해 이 메서드를 호출합니다. Mastra 레지스트리에서 Workspace를 제거하려면 mastra.removeWorkspace()를 사용하세요.
LocalFilesystem.destroy()디스크의 파일을 삭제하지 않습니다. 확인자 지원 파일 시스템 및 샌드박스 공급자는 애플리케이션이 소유하며 애플리케이션에서 정리해야 합니다.
검색 작업검색 작업에 대한 직접 링크
index(path, content, options?)indexpath-content-options에 대한 직접 링크
검색을 위해 콘텐츠를 색인화합니다.
await workspace.index('/docs/guide.md', 'Guide content...')
search(query, options?)searchquery-options에 대한 직접 링크
색인화된 콘텐츠를 검색합니다.
const results = await workspace.search('password reset', {
topK: 10,
mode: 'hybrid',
})
공익사업공익사업에 대한 직접 링크
getInfo()getinfo에 대한 직접 링크
작업공간 정보를 얻으세요.
const info = await workspace.getInfo()
// { id, name, status, createdAt, lastAccessedAt, filesystem?, sandbox? }
리졸버를 호출하지 않고 리졸버 기반 Provider를 런타임 정의로 보고하려면 resolveDynamicProviders: false를 전달하세요.
const info = await workspace.getInfo({ resolveDynamicProviders: false })
매개변수:
options.includeFileCount?:
options.requestContext?:
resolveDynamicProviders가 활성화된 경우 동적 Provider 리졸버에 전달됩니다.options.resolveDynamicProviders?:
dynamic으로 보고하려면 false로 설정하세요.getInstructions(opts?)getinstructionsopts에 대한 직접 링크
파일 시스템 및 샌드박스 공급자의 결합된 명령을 반환합니다. 실행 컨텍스트를 이해하는 데 도움이 되도록 Agent의 시스템 메시지에 삽입됩니다.
const instructions = workspace.getInstructions()
Provider의 instructions 옵션이 함수일 때 요청별 사용자 지정을 활성화하려면 requestContext를 전달하세요.
const instructions = workspace.getInstructions({ requestContext })
매개변수:
opts.requestContext?:
instructions 함수로 전달됩니다.보고: string
getInstructionsAsync(opts?)getinstructionsasyncopts에 대한 직접 링크
결합된 Workspace 지침을 반환합니다. Workspace가 리졸버 기반 Provider를 사용하는 경우 이를 리졸빙합니다. 런타임 정의 파일 시스템은 요청별로 리졸빙됩니다. 런타임 정의 Sandbox는 instructions.dynamicSandbox가 'resolve'로 설정된 경우를 제외하고 고정된 자리표시자 텍스트를 제공합니다.
const instructions = await workspace.getInstructionsAsync({ requestContext })
매개변수:
opts.requestContext?:
instructions.dynamicSandbox가 'resolve'인 경우 동적 Sandbox 리졸버에도 전달됩니다.보고: Promise<string>
기본 출력을 재정의하려면 LocalFilesystem 또는 LocalSandbox에 instructions 옵션을 지정하세요.
getToolsConfig()gettoolsconfig에 대한 직접 링크
현재 Tool 구성을 가져옵니다.
const config = workspace.getToolsConfig()
보고: WorkspaceToolsConfig | undefined
setToolsConfig(config?)settoolsconfigconfig에 대한 직접 링크
런타임에 Tool별 구성을 교체합니다. 전체 구성을 교체하며 이전 구성과 병합하지 않습니다. 기본값으로 재설정하려면 undefined를 전달하세요. 변경 사항은 다음 Agent 상호작용(다음 createWorkspaceTools() 호출)부터 적용됩니다.
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?:
동적 파일 시스템동적 파일 시스템에 대한 직접 링크
hasFilesystemConfig()hasfilesystemconfig에 대한 직접 링크
파일 시스템이 정적 인스턴스 또는 리졸버 함수로 구성되어 있는지 확인합니다. 리졸버 기반 Workspace의 filesystem 속성은 undefined를 반환하므로 workspace.filesystem을 직접 확인하는 대신 이 메서드를 사용하세요.
if (workspace.hasFilesystemConfig()) {
// Filesystem tools are available
}
보고: boolean
resolveFilesystem({ requestContext })resolvefilesystem-requestcontext-에 대한 직접 링크
요청 컨텍스트에 대한 파일 시스템을 리졸빙합니다. 리졸버 함수가 구성되어 있으면 제공된 requestContext로 호출합니다. 정적 파일 시스템이 구성되어 있으면 이를 직접 반환합니다. 파일 시스템이 구성되지 않았으면 undefined를 반환합니다.
import { RequestContext } from '@mastra/core/request-context'
const ctx = new RequestContext([['agent-role', 'admin']])
const fs = await workspace.resolveFilesystem({ requestContext: ctx })
매개변수:
requestContext:
보고: Promise<WorkspaceFilesystem | undefined>
동적 샌드박스동적 샌드박스에 대한 직접 링크
hasSandboxConfig()hassandboxconfig에 대한 직접 링크
Sandbox가 정적 인스턴스 또는 리졸버 함수로 구성되어 있는지 확인합니다. 리졸버 기반 Workspace의 sandbox 속성은 undefined를 반환하므로 workspace.sandbox를 직접 확인하는 대신 이 메서드를 사용하세요.
if (workspace.hasSandboxConfig()) {
// Sandbox tools are available
}
보고: boolean
resolveSandbox({ requestContext })resolvesandbox-requestcontext-에 대한 직접 링크
요청 컨텍스트에 대한 Sandbox를 리졸빙합니다. 리졸버 함수가 구성되어 있으면 제공된 requestContext로 호출합니다. 정적 Sandbox가 구성되어 있으면 이를 직접 반환합니다. Sandbox가 구성되지 않았으면 undefined를 반환합니다.
import { RequestContext } from '@mastra/core/request-context'
const ctx = new RequestContext([['user-id', 'alice']])
const sandbox = await workspace.resolveSandbox({ requestContext: ctx })
매개변수:
requestContext:
보고: Promise<WorkspaceSandbox | undefined>
clearSandboxCache(cacheKey?)clearsandboxcachecachekey에 대한 직접 링크
sandboxCacheKey로 캐시된 리졸버 기반 Sandbox를 지웁니다. 하나의 항목을 지우려면 캐시 키를 전달하고, 키가 지정된 모든 Sandbox 항목을 지우려면 생략하세요.
이 메서드는 RequestContext별 약한 참조 캐시를 지우지 않습니다. 해당 항목은 가비지 컬렉션으로 관리됩니다.
작업 영역에는 확인자가 반환한 샌드박스가 없습니다. 이 방법은 작업공간 참조만 삭제합니다. 자신의 라이프사이클 코드에서 샌드박스를 삭제하세요.
workspace.clearSandboxCache('thread-123')
workspace.clearSandboxCache()
매개변수:
cacheKey?:
보고: void
Agent ToolAgent Tool에 대한 직접 링크
작업 영역은 구성된 내용에 따라 Agent에 Tool을 제공합니다.
파일 시스템 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)이 제외됩니다. 런타임 정의 파일 시스템을 사용하면 쓰기 Tool이 항상 포함되며 읽기 전용 여부는 런타임에 적용됩니다. | |
read_file Tool은 mediaTypes 및 maxMediaBytes 옵션을 받아, 어떤 MIME 유형을 네이티브 미디어 파트로 Model에 제공할지와 해당 파일의 최대 크기를 제어합니다. |
mediaTypes?:
['image/*']), 사용자 지정 조건자 함수 또는 미디어 감지를 비활성화하는 false를 받습니다. 기본값은 여러 Provider에서 안전하게 사용할 수 있는 이미지 형식과 PDF의 교집합입니다. 호출자가 명시적인 encoding을 전달하지 않은 경우에만 적용됩니다.maxMediaBytes?:
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에 대한 직접 링크
샌드박스가 구성되면 추가됩니다.
| 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를 사용하면 모든 Sandbox Tool이 등록되며, 리졸빙된 Sandbox가 요청된 기능을 구현하지 않은 경우 런타임에서 명확한 오류를 발생시킵니다. | |
execute_command Tool은 백그라운드 프로세스의 수명 주기 콜백을 위한 backgroundProcesses 옵션을 받습니다. |
backgroundProcesses?:
onStdout?:
onStderr?:
onExit?:
abortSignal?:
사용 예제는 백그라운드 프로세스 콜백을 참조하세요.
검색 Tool검색 Tool에 대한 직접 링크
BM25 또는 벡터 검색이 구성된 경우 추가됨:
| Tool | 설명 |
|---|---|
mastra_workspace_search | 키워드(BM25), 의미(벡터) 또는 하이브리드 검색을 사용하여 인덱싱된 콘텐츠를 검색합니다. 점수에 따라 순위가 지정된 결과를 반환합니다. |
mastra_workspace_index | 검색할 콘텐츠를 인덱싱합니다. 나중에 검색할 수 있도록 콘텐츠를 경로와 연결합니다. |
파일 시스템이 읽기 전용 모드이면 index Tool이 제외됩니다. |
스킬 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을 참조하세요. |