AgentCoreRuntimeSandbox
使用 InvokeAgentRuntimeCommand 在 AWS Bedrock AgentCore Runtime 会话中执行 shell 命令。
如果 Agent 已在 AgentCore Runtime 中运行，并且你希望 Mastra Workspace 使用同一个运行时会话执行命令，请使用 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 时使用的客户端令牌。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 拥有该运行时会话且你希望直接清理它时，请使用此方法。destroy() 不会调用此方法，除非 stopSessionOnLifecycle 为 true，因为 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 不可用：运行时命令执行无法通过此 Provider 提供交互式 stdin 流。
- 不支持挂载 Workspace 文件系统：此 Provider 不支持挂载 Workspace 文件系统。
- 依赖容器的 Tool：命令只能使用 AgentCore Runtime 容器镜像中已安装的 Tool。