AgentCoreRuntimeSandbox
使用 InvokeAgentRuntimeCommand，在 AWS Bedrock AgentCore Runtime 工作階段中執行 shell 指令。
如果你的 Agent 已在 AgentCore Runtime 中運行，而你想讓 Mastra Workspace 使用同一個 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 的生命週期啟動掛鈎。此 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 容器映像中已安裝的工具。