> Discover all available pages from the documentation index: https://mastra.zisheng.pro/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 使用同一个运行时会话执行命令，请使用 `AgentCoreRuntimeSandbox`。有关接口的详细信息，请参阅 [WorkspaceSandbox 接口](https://mastra.zisheng.pro/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 运行时限定符或端点。 (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 时使用的客户端令牌。 (Default: `生成的 UUID`)

**client** (`BedrockAgentCoreClient`): 预配置的 AWS SDK 客户端。可用于自定义凭证、重试行为或测试。

**instructions** (`string | ((opts) => string)`): 自定义说明，用于覆盖 getInstructions() 返回的默认说明。传入字符串可替换默认说明，传入函数可扩展默认说明。

## 属性

**id** (`string`): 此 Sandbox 实例使用的运行时会话 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 拥有该运行时会话且你希望直接清理它时，请使用此方法。`destroy()` 不会调用此方法，除非 `stopSessionOnLifecycle` 为 `true`，因为 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 不可用**：运行时命令执行无法通过此 Provider 提供交互式 stdin 流。
- **不支持挂载 Workspace 文件系统**：此 Provider 不支持挂载 Workspace 文件系统。
- **依赖容器的 Tool**：命令只能使用 AgentCore Runtime 容器镜像中已安装的 Tool。

## 相关内容

- [WorkspaceSandbox 接口](https://mastra.zisheng.pro/reference/workspace/sandbox)
- [Workspace 类](https://mastra.zisheng.pro/reference/workspace/workspace-class)
- [Sandbox 概述](https://mastra.zisheng.pro/docs/workspace/sandbox)
- [AWS Bedrock AgentCore Runtime 命令执行](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-execute-command.html)