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

# AgentCoreRuntimeSandbox

使用 `InvokeAgentRuntimeCommand`，在 [AWS Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-execute-command.html) 工作階段中執行 shell 指令。

如果 Agent 已在 AgentCore Runtime 中執行，且你希望 Mastra Workspace 的指令執行沿用相同的 AgentCore Runtime 工作階段，請使用 `AgentCoreRuntimeSandbox`。介面詳情請參閱 [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/sandbox)。

> **警告:** `AgentCoreRuntimeSandbox` 僅支援一次性指令執行，不支援背景處理程序管理、stdin 或檔案系統掛載。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
```

## 使用方式

將 `AgentCoreRuntimeSandbox` 加入 Workspace，並指派給 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: `自動產生的 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。預設為 false，因為 AgentCore Runtime 工作階段通常會與此 Sandbox 執行個體以外的 Agent 呼叫共用。 (Default: `false`)

**stopClientToken** (`string`): 呼叫 StopRuntimeSession 時使用的使用者端 Token。 (Default: `自動產生的 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 工作階段中執行一次性 shell 指令，並傳回 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 生命週期的啟動 hook。此 Provider 不會在 `start()` 期間建立 AgentCore Runtime 工作階段。

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

#### `stop()`

只有在 `stopSessionOnLifecycle` 為 `true` 時，才會停止 AgentCore Runtime 工作階段。

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

#### `stopRuntimeSession()`

明確停止此 Sandbox 使用的 AgentCore Runtime 工作階段。

當 Sandbox 擁有 Runtime 工作階段，且你想直接清除它時，請使用此方法。除非 `stopSessionOnLifecycle` 為 `true`，否則 `destroy()` 不會呼叫此方法，因為 AgentCore Runtime 工作階段可能會與 Workspace Sandbox 生命週期以外的 Agent 呼叫共用。

```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 的指令執行語意：

- **一次性指令**：每個指令會執行到完成或逾時為止。
- **沒有持久 shell**：shell 狀態不會在指令之間保留。請將狀態編入每個指令，例如 `cd /workspace && npm test`。
- **不支援背景處理程序**：此 Provider 不會公開 `processes` 管理器。
- **無法使用互動式 stdin**：Runtime 指令執行無法透過此 Provider 提供互動式 stdin 串流。
- **不支援 Workspace 檔案系統掛載**：此 Provider 不支援 Workspace 檔案系統掛載。
- **依賴容器的工具**：指令只能使用 AgentCore Runtime 容器映像中已安裝的工具。

## 相關內容

- [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-TW/reference/workspace/sandbox)
- [Workspace 類別](https://mastra.zisheng.pro/zh-TW/reference/workspace/workspace-class)
- [Sandbox 概觀](https://mastra.zisheng.pro/zh-TW/docs/workspace/sandbox)
- [AWS Bedrock AgentCore Runtime 指令執行](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-execute-command.html)