> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ja/llms.txt

# AgentCoreRuntimeSandbox

`InvokeAgentRuntimeCommand` を使用して、[AWS Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-execute-command.html) セッション内でシェルコマンドを実行します。

Agent がすでに AgentCore Runtime で動作しており、Mastra Workspace のコマンド実行にも同じランタイムセッションを使用する場合に `AgentCoreRuntimeSandbox` を使用します。インターフェースの詳細は、[WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)を参照してください。

> **警告:** `AgentCoreRuntimeSandbox` が対応するのは単発のコマンド実行のみです。バックグラウンドプロセス管理、stdin、Filesystem のマウントには対応していません。AgentCore Code Interpreter は別の AWS サービスであり、この Provider には含まれません。

## インストール

**npm**:

```bash
npm install @mastra/agentcore
```

**pnpm**:

```bash
pnpm add @mastra/agentcore
```

**Yarn**:

```bash
yarn add @mastra/agentcore
```

**Bun**:

```bash
bun add @mastra/agentcore
```

## 使用方法

Workspace に `AgentCoreRuntimeSandbox` を追加して Agent に割り当てます。

```typescript
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 を介してプログラムからコマンドを実行します。

```typescript
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** (`string`): コマンドを実行する AgentCore Runtime ARN。

**region** (`string`): Bedrock AgentCore クライアントの AWS リージョン。未指定の場合は AWS SDK のデフォルトリージョンチェーンを使用します。

**runtimeSessionId** (`string`): AgentCore Runtime のセッション ID。デフォルトでは、AgentCore Runtime のセッション ID 長の要件を満たす UUID が生成されます。 (Default: `Generated UUID`)

**qualifier** (`string`): Agent Runtime の修飾子またはエンドポイント。 (Default: `DEFAULT`)

**contentType** (`string`): コマンドリクエストで送信する MIME タイプ。 (Default: `application/json`)

**accept** (`string`): コマンドイベントストリームで使用する Accept ヘッダー。 (Default: `application/vnd.amazon.eventstream`)

**commandTimeout** (`number`): デフォルトのコマンドタイムアウト（ミリ秒）。 (Default: `300000`)

**stopSessionOnLifecycle** (`boolean`): stop() と destroy() で StopRuntimeSession を呼び出すかどうか。AgentCore Runtime セッションは Sandbox インスタンス外の Agent 呼び出しと共有されることが多いため、デフォルトは false です。 (Default: `false`)

**stopClientToken** (`string`): StopRuntimeSession の呼び出し時に使用するクライアントトークン。 (Default: `Generated UUID`)

**client** (`BedrockAgentCoreClient`): 設定済みの AWS SDK クライアント。カスタム認証情報、再試行動作、テストに使用します。

**instructions** (`string | ((opts) => string)`): getInstructions() が返すデフォルトの指示を上書きするカスタム指示。デフォルトを置き換えるには文字列を、拡張するには関数を渡します。

## プロパティ

**id** (`string`): この Sandbox インスタンスが使用する Runtime セッション ID。

**name** (`'AgentCoreRuntimeSandbox'`): 人が読みやすい名前。

**provider** (`'agentcore'`): Provider の種類を表す識別子。

**status** (`ProviderStatus`): 現在のライフサイクルステータス：'pending'、'starting'、'running'、'stopping'、'stopped'、'destroying'、'destroyed'、'error'。

**runtimeSessionId** (`string`): コマンド実行に使用する AgentCore Runtime セッション ID。

**agentRuntimeArn** (`string`): コマンドを実行する AgentCore Runtime ARN。

## メソッド

### コマンド実行

#### `executeCommand(command, args?, options?)`

AgentCore Runtime セッションで単発のシェルコマンドを実行し、stdout、stderr、終了コード、タイムアウトステータスを返します。

```typescript
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()`

Sandbox のライフサイクル開始フックを実行します。この Provider は `start()` 中に AgentCore Runtime セッションを作成しません。

```typescript
await sandbox.start()
```

#### `stop()`

`stopSessionOnLifecycle` が `true` の場合に限り、AgentCore Runtime セッションを停止します。

```typescript
await sandbox.stop()
```

#### `stopRuntimeSession()`

この Sandbox が使用する AgentCore Runtime セッションを明示的に停止します。

Sandbox が Runtime セッションを所有し、直接解放する場合に使用します。AgentCore Runtime セッションは Workspace Sandbox のライフサイクル外の Agent 呼び出しと共有される場合があるため、`stopSessionOnLifecycle` が `true` でなければ `destroy()` はこのメソッドを呼び出しません。

```typescript
await sandbox.stopRuntimeSession()
```

#### `destroy()`

Sandbox インスタンスを破棄します。このインスタンスが AWS SDK クライアントを所有する場合、`destroy()` はそのクライアントも破棄します。`stopSessionOnLifecycle` が `true` の場合は `StopRuntimeSession` を呼び出します。

```typescript
await sandbox.destroy()
```

### メタデータ

#### `getInfo()`

Sandbox のステータスと AgentCore Runtime のメタデータを返します。

```typescript
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 のみです。

## 関連項目

- [WorkspaceSandbox インターフェース](https://mastra.zisheng.pro/ja/reference/workspace/sandbox)
- [Workspace クラス](https://mastra.zisheng.pro/ja/reference/workspace/workspace-class)
- [Sandbox の概要](https://mastra.zisheng.pro/ja/docs/workspace/sandbox)
- [AWS Bedrock AgentCore Runtime のコマンド実行](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-execute-command.html)