AgentCoreRuntime샌드박스
쉘 명령을 실행합니다.AWS Bedrock AgentCore Runtime을 사용하여 세션InvokeAgentRuntimeCommand.
Agent가 이미 AgentCore Runtime에서 실행 중이고 Mastra Workspace 명령 실행에서도 동일한 런타임 세션을 사용하려면 AgentCoreRuntimeSandbox를 사용하세요. 인터페이스 세부 정보는 WorkspaceSandbox 인터페이스를 참조하세요.
AgentCoreRuntimeSandbox일회성 명령 실행만 지원합니다. 백그라운드 프로세스 관리, stdin 또는 파일 시스템 마운트를 지원하지 않습니다. AgentCore Code Interpreter는 별도의 AWS 서비스이며 이 공급자의 일부가 아닙니다.
설치설치에 대한 직접 링크
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/agentcore
pnpm add @mastra/agentcore
yarn add @mastra/agentcore
bun add @mastra/agentcore
용법용법에 대한 직접 링크
Workspace에 AgentCoreRuntimeSandbox를 추가하고 Agent에 할당하세요.
import { Agent } from '@mastra/core/agent'
import { Workspace } from '@mastra/core/workspace'
import { AgentCoreRuntimeSandbox } from '@mastra/agentcore'
const workspace = new Workspace({
sandbox: new AgentCoreRuntimeSandbox({
region: 'us-west-2',
agentRuntimeArn: process.env.AGENTCORE_RUNTIME_ARN!,
runtimeSessionId: '12345678-1234-1234-1234-123456789012',
}),
})
const agent = new Agent({
id: 'dev-agent',
name: 'dev-agent',
model: 'anthropic/claude-sonnet-4-6',
instructions: 'You are a helpful development assistant.',
workspace,
})
샌드박스를 통해 프로그래밍 방식으로 명령을 실행합니다.
const result = await workspace.sandbox?.executeCommand?.('npm', ['test'], {
cwd: '/workspace',
env: {
NODE_ENV: 'test',
},
timeout: 300_000,
})
if (!result?.success) {
console.error(result?.stderr)
}
생성자 매개변수생성자 매개변수에 대한 직접 링크
agentRuntimeArn:
region?:
runtimeSessionId?:
qualifier?:
contentType?:
accept?:
commandTimeout?:
stopSessionOnLifecycle?:
stop()과 destroy()가 StopRuntimeSession을 호출할지 여부입니다. AgentCore Runtime 세션은 Sandbox 인스턴스 외부의 Agent 호출과 공유되는 경우가 많으므로 기본값은 false입니다.stopClientToken?:
StopRuntimeSession 호출 시 사용되는 클라이언트 토큰입니다.client?:
instructions?:
getInstructions()가 반환하는 기본 지침을 재정의하는 사용자 지정 지침입니다. 기본값을 대체하려면 문자열을 전달하고, 확장하려면 함수를 전달하세요.속성속성에 대한 직접 링크
id:
name:
provider:
status:
'pending', 'starting', 'running', 'stopping', 'stopped', 'destroying', 'destroyed' 또는 'error'.runtimeSessionId:
agentRuntimeArn:
행동 양식행동 양식에 대한 직접 링크
명령 실행명령 실행에 대한 직접 링크
executeCommand(command, args?, options?)executecommandcommand-args-options에 대한 직접 링크
AgentCore Runtime 세션에서 원샷 셸 명령을 실행하고 stdout, stderr, 종료 코드 및 시간 초과 상태를 반환합니다.
const result = await sandbox.executeCommand('npm', ['test'], {
cwd: '/workspace',
env: {
NODE_ENV: 'test',
},
timeout: 300_000,
})
보고:Promise<CommandResult>.
options.timeout밀리초 단위로 지정됩니다. AgentCore 런타임은 1~3600초의 명령 시간 초과를 허용합니다. 공급자는 요청을 보내기 전에 밀리초를 초로 변환합니다.
수명주기수명주기에 대한 직접 링크
start()start에 대한 직접 링크
샌드박스 수명 주기 시작 후크를 실행합니다. 이 공급자는 실행 중에 AgentCore 런타임 세션을 생성하지 않습니다.start().
await sandbox.start()
stop()stop에 대한 직접 링크
stopSessionOnLifecycle이 true인 경우에만 AgentCore Runtime 세션을 중지합니다.
await sandbox.stop()
stopRuntimeSession()stopruntimesession에 대한 직접 링크
이 샌드박스에서 사용하는 AgentCore 런타임 세션을 명시적으로 중지합니다.
Sandbox가 런타임 세션을 소유하고 이를 직접 정리하려는 경우 사용하세요. AgentCore Runtime 세션은 Workspace Sandbox 수명 주기 외부의 Agent 호출과 공유될 수 있으므로, stopSessionOnLifecycle이 true가 아니면 destroy()는 이 메서드를 호출하지 않습니다.
await sandbox.stopRuntimeSession()
destroy()destroy에 대한 직접 링크
Sandbox 인스턴스를 삭제합니다. 이 인스턴스가 AWS SDK 클라이언트를 소유한 경우 destroy()는 클라이언트도 삭제합니다. stopSessionOnLifecycle이 true이면 StopRuntimeSession을 호출합니다.
await sandbox.destroy()
메타데이터메타데이터에 대한 직접 링크
getInfo()getinfo에 대한 직접 링크
샌드박스 상태 및 AgentCore 런타임 메타데이터를 반환합니다.
const info = await sandbox.getInfo()
보고:Promise<SandboxInfo>.
제한사항제한사항에 대한 직접 링크
AgentCoreRuntimeSandboxAgentCore Runtime 명령 실행 의미 체계를 따릅니다.
- 일회성 명령: 각 명령은 완료되거나 시간 초과될 때까지 실행됩니다.
- 영구 쉘 없음: 쉘 상태는 명령 간에 전달되지 않습니다. 예를 들어 각 명령의 상태를 인코딩합니다.
cd /workspace && npm test. - 백그라운드 프로세스는 지원되지 않습니다.: 공급자는
processesmanager. - 대화형 표준 입력을 사용할 수 없습니다.: 런타임 명령 실행은 이 공급자를 통해 대화형 stdin 스트림을 제공하지 않습니다.
- Workspace 파일 시스템 마운트는 지원되지 않습니다.: 이 공급자는 작업공간 파일 시스템 마운트를 지원하지 않습니다.
- 컨테이너 종속 Tool: 명령은 AgentCore Runtime 컨테이너 이미지에 설치된 Tool만 사용할 수 있습니다.