> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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 使用同一個 runtime 工作階段執行指令，便可使用 `AgentCoreRuntimeSandbox`。介面詳情請參閱 [WorkspaceSandbox 介面](https://mastra.zisheng.pro/zh-HK/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。預設為產生的 UUID，符合 AgentCore Runtime 對工作階段 ID 長度的要求。 (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 的生命週期啟動掛鈎。此 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-HK/reference/workspace/sandbox)
- [Workspace 類別](https://mastra.zisheng.pro/zh-HK/reference/workspace/workspace-class)
- [Sandbox 概覽](https://mastra.zisheng.pro/zh-HK/docs/workspace/sandbox)
- [AWS Bedrock AgentCore Runtime 指令執行](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-execute-command.html)