AgentCoreRuntimeSandbox
InvokeAgentRuntimeCommand を使用して、AWS Bedrock AgentCore Runtime セッション内でシェルコマンドを実行します。
Agent がすでに AgentCore Runtime で動作しており、Mastra Workspace のコマンド実行にも同じランタイムセッションを使用する場合に AgentCoreRuntimeSandbox を使用します。インターフェースの詳細は、WorkspaceSandbox インターフェースを参照してください。
AgentCoreRuntimeSandbox が対応するのは単発のコマンド実行のみです。バックグラウンドプロセス管理、stdin、Filesystem のマウントには対応していません。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
使用方法使用方法への直接リンク
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,
})
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 を呼び出すかどうか。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 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 セッションを所有し、直接解放する場合に使用します。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への直接リンク
Sandbox のステータスと AgentCore Runtime のメタデータを返します。
const info = await sandbox.getInfo()
戻り値：Promise<SandboxInfo>。
制限事項制限事項への直接リンク
AgentCoreRuntimeSandbox は AgentCore Runtime のコマンド実行セマンティクスに従います。
- 単発コマンド：各コマンドは完了またはタイムアウトまで実行されます。
- 永続シェルなし：シェルの状態はコマンド間で引き継がれません。たとえば
cd /workspace && npm testのように、各コマンドに状態を組み込んでください。 - バックグラウンドプロセス非対応：Provider は
processesマネージャーを公開しません。 - 対話型 stdin なし：この Provider による Runtime コマンド実行では、対話型 stdin ストリームを利用できません。
- Workspace Filesystem のマウント非対応：この Provider は Workspace Filesystem のマウントに対応していません。
- コンテナ依存の Tool：コマンドが使用できるのは AgentCore Runtime のコンテナイメージにインストールされた Tool のみです。