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

# AgentCoreRuntime샌드박스

쉘 명령을 실행합니다.[AWS Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-execute-command.html)을 사용하여 세션`InvokeAgentRuntimeCommand`.

Agent가 이미 AgentCore Runtime에서 실행 중이고 Mastra Workspace 명령 실행에서도 동일한 런타임 세션을 사용하려면 `AgentCoreRuntimeSandbox`를 사용하세요. 인터페이스 세부 정보는 [WorkspaceSandbox 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/sandbox)를 참조하세요.

> **경고:** `AgentCoreRuntimeSandbox`일회성 명령 실행만 지원합니다. 백그라운드 프로세스 관리, stdin 또는 파일 시스템 마운트를 지원하지 않습니다. AgentCore Code Interpreter는 별도의 AWS 서비스이며 이 공급자의 일부가 아닙니다.

## 설치

**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,
})
```

샌드박스를 통해 프로그래밍 방식으로 명령을 실행합니다.

```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 런타임 한정자 또는 엔드포인트입니다. (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: `생성된 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 세션에서 원샷 셸 명령을 실행하고 stdout, stderr, 종료 코드 및 시간 초과 상태를 반환합니다.

```typescript
const result = await sandbox.executeCommand('npm', ['test'], {
  cwd: '/workspace',
  env: {
    NODE_ENV: 'test',
  },
  timeout: 300_000,
})
```

보고:`Promise<CommandResult>`.

`options.timeout`밀리초 단위로 지정됩니다. AgentCore 런타임은 1\~3600초의 명령 시간 초과를 허용합니다. 공급자는 요청을 보내기 전에 밀리초를 초로 변환합니다.

### 수명주기

#### `start()`

샌드박스 수명 주기 시작 후크를 실행합니다. 이 공급자는 실행 중에 AgentCore 런타임 세션을 생성하지 않습니다.`start()`.

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

#### `stop()`

`stopSessionOnLifecycle`이 `true`인 경우에만 AgentCore Runtime 세션을 중지합니다.

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

#### `stopRuntimeSession()`

이 샌드박스에서 사용하는 AgentCore 런타임 세션을 명시적으로 중지합니다.

Sandbox가 런타임 세션을 소유하고 이를 직접 정리하려는 경우 사용하세요. 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()`

샌드박스 상태 및 AgentCore 런타임 메타데이터를 반환합니다.

```typescript
const info = await sandbox.getInfo()
```

보고:`Promise<SandboxInfo>`.

## 제한사항

`AgentCoreRuntimeSandbox`AgentCore Runtime 명령 실행 의미 체계를 따릅니다.

- **일회성 명령**: 각 명령은 완료되거나 시간 초과될 때까지 실행됩니다.
- **영구 쉘 없음**: 쉘 상태는 명령 간에 전달되지 않습니다. 예를 들어 각 명령의 상태를 인코딩합니다.`cd /workspace && npm test`.
- **백그라운드 프로세스는 지원되지 않습니다.**: 공급자는`processes` manager.
- **대화형 표준 입력을 사용할 수 없습니다.**: 런타임 명령 실행은 이 공급자를 통해 대화형 stdin 스트림을 제공하지 않습니다.
- **Workspace 파일 시스템 마운트는 지원되지 않습니다.**: 이 공급자는 작업공간 파일 시스템 마운트를 지원하지 않습니다.
- **컨테이너 종속 Tool**: 명령은 AgentCore Runtime 컨테이너 이미지에 설치된 Tool만 ​​사용할 수 있습니다.

## 관련된

- [WorkspaceSandbox 인터페이스](https://mastra.zisheng.pro/ko/reference/workspace/sandbox)
- [작업실 수업](https://mastra.zisheng.pro/ko/reference/workspace/workspace-class)
- [샌드박스 개요](https://mastra.zisheng.pro/ko/docs/workspace/sandbox)
- [AWS Bedrock AgentCore 런타임 명령 실행](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-execute-command.html)