AgentCoreRuntimeSandbox
使用 InvokeAgentRuntimeCommand，在 AWS Bedrock AgentCore Runtime 工作階段中執行 shell 指令。
如果 Agent 已在 AgentCore Runtime 中執行，且你希望 Mastra Workspace 的指令執行沿用相同的 AgentCore Runtime 工作階段，請使用 AgentCoreRuntimeSandbox。介面詳情請參閱 WorkspaceSandbox 介面。
AgentCoreRuntimeSandbox 僅支援一次性指令執行，不支援背景處理程序管理、stdin 或檔案系統掛載。AgentCore Code Interpreter 是另一項 AWS 服務，不屬於此 Provider。
安裝「安裝」的直接連結
- npm
- pnpm
- Yarn
- Bun
npm install @mastra/agentcore
pnpm add @mastra/agentcore
yarn add @mastra/agentcore
bun add @mastra/agentcore
使用方式「使用方式」的直接連結
將 AgentCoreRuntimeSandbox 加入 Workspace，並指派給 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,
})
以程式方式透過 Sandbox 執行指令：
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。預設為 false，因為 AgentCore Runtime 工作階段通常會與此 Sandbox 執行個體以外的 Agent 呼叫共用。stopClientToken?:
StopRuntimeSession 時使用的使用者端 Token。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 工作階段中執行一次性 shell 指令，並傳回 stdout、stderr、結束程式碼與逾時狀態。
const result = await sandbox.executeCommand('npm', ['test'], {
cwd: '/workspace',
env: {
NODE_ENV: 'test',
},
timeout: 300_000,
})
傳回：Promise<CommandResult>。
options.timeout 以毫秒指定。AgentCore Runtime 接受 1 至 3600 秒的指令逾時時間。此 Provider 會在傳送請求前將毫秒轉換為秒。
生命週期「生命週期」的直接連結
start()「start」的直接連結
執行 Sandbox 生命週期的啟動 hook。此 Provider 不會在 start() 期間建立 AgentCore Runtime 工作階段。
await sandbox.start()
stop()「stop」的直接連結
只有在 stopSessionOnLifecycle 為 true 時，才會停止 AgentCore Runtime 工作階段。
await sandbox.stop()
stopRuntimeSession()「stopruntimesession」的直接連結
明確停止此 Sandbox 使用的 AgentCore Runtime 工作階段。
當 Sandbox 擁有 Runtime 工作階段，且你想直接清除它時，請使用此方法。除非 stopSessionOnLifecycle 為 true，否則 destroy() 不會呼叫此方法，因為 AgentCore Runtime 工作階段可能會與 Workspace Sandbox 生命週期以外的 Agent 呼叫共用。
await sandbox.stopRuntimeSession()
destroy()「destroy」的直接連結
銷毀 Sandbox 執行個體。如果此執行個體擁有 AWS SDK 使用者端，destroy() 也會銷毀該使用者端。如果 stopSessionOnLifecycle 為 true，則會呼叫 StopRuntimeSession。
await sandbox.destroy()
中繼資料「中繼資料」的直接連結
getInfo()「getinfo」的直接連結
傳回 Sandbox 狀態與 AgentCore Runtime 中繼資料。
const info = await sandbox.getInfo()
傳回：Promise<SandboxInfo>。
限制「限制」的直接連結
AgentCoreRuntimeSandbox 遵循 AgentCore Runtime 的指令執行語意：
- 一次性指令：每個指令會執行到完成或逾時為止。
- 沒有持久 shell：shell 狀態不會在指令之間保留。請將狀態編入每個指令，例如
cd /workspace && npm test。 - 不支援背景處理程序：此 Provider 不會公開
processes管理器。 - 無法使用互動式 stdin：Runtime 指令執行無法透過此 Provider 提供互動式 stdin 串流。
- 不支援 Workspace 檔案系統掛載：此 Provider 不支援 Workspace 檔案系統掛載。
- 依賴容器的工具：指令只能使用 AgentCore Runtime 容器映像中已安裝的工具。