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

# AgentCoreRuntimeSandbox

Exécute des commandes shell dans une session [AWS Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-execute-command.html) au moyen de `InvokeAgentRuntimeCommand`.

Utilisez `AgentCoreRuntimeSandbox` lorsque votre Agent s'exécute déjà dans AgentCore Runtime et que vous souhaitez que l'exécution des commandes du Workspace Mastra utilise la même session d'exécution. Pour plus de détails sur l'interface, consultez [l'interface WorkspaceSandbox](https://mastra.zisheng.pro/fr/reference/workspace/sandbox).

> **Attention:** `AgentCoreRuntimeSandbox` prend uniquement en charge l'exécution ponctuelle de commandes. Il ne prend en charge ni la gestion des processus en arrière-plan, ni stdin, ni les montages de systèmes de fichiers. AgentCore Code Interpreter est un service AWS distinct qui ne fait pas partie de ce Provider.

## Installation

**npm**:

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

**pnpm**:

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

**Yarn**:

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

**Bun**:

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

## Utilisation

Ajoutez un `AgentCoreRuntimeSandbox` à un Workspace et attribuez-le à un 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,
})
```

Exécutez des commandes par programmation au moyen de la 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)
}
```

## Paramètres du constructeur

**agentRuntimeArn** (`string`): ARN d'AgentCore Runtime dans lequel les commandes sont exécutées.

**region** (`string`): Région AWS du client Bedrock AgentCore. Utilise par défaut la chaîne de régions par défaut du SDK AWS.

**runtimeSessionId** (`string`): Identifiant de session AgentCore Runtime. Utilise par défaut un UUID généré qui respecte les exigences de longueur des identifiants de session AgentCore Runtime. (Default: `UUID généré`)

**qualifier** (`string`): Qualificateur ou endpoint de l'Agent Runtime. (Default: `DEFAULT`)

**contentType** (`string`): Type MIME envoyé pour les requêtes de commande. (Default: `application/json`)

**accept** (`string`): En-tête Accept utilisé pour les flux d'événements de commande. (Default: `application/vnd.amazon.eventstream`)

**commandTimeout** (`number`): Délai d'expiration par défaut des commandes, en millisecondes. (Default: `300000`)

**stopSessionOnLifecycle** (`boolean`): Indique si stop() et destroy() doivent appeler StopRuntimeSession. La valeur par défaut est false, car les sessions AgentCore Runtime sont souvent partagées avec des invocations d'Agents extérieures à l'instance de Sandbox. (Default: `false`)

**stopClientToken** (`string`): Token client utilisé lors de l'appel de StopRuntimeSession. (Default: `UUID généré`)

**client** (`BedrockAgentCoreClient`): Client SDK AWS préconfiguré. Utilisez-le pour des identifiants personnalisés, un comportement de nouvelle tentative personnalisé ou des tests.

**instructions** (`string | ((opts) => string)`): Instructions personnalisées qui remplacent les instructions par défaut renvoyées par getInstructions(). Transmettez une chaîne pour remplacer les valeurs par défaut, ou une fonction pour les étendre.

## Propriétés

**id** (`string`): Identifiant de session d'exécution utilisé par cette instance de Sandbox.

**name** (`'AgentCoreRuntimeSandbox'`): Nom lisible par les utilisateurs.

**provider** (`'agentcore'`): Identifiant du type de Provider.

**status** (`ProviderStatus`): État actuel du cycle de vie : 'pending', 'starting', 'running', 'stopping', 'stopped', 'destroying', 'destroyed' ou 'error'.

**runtimeSessionId** (`string`): Identifiant de session AgentCore Runtime utilisé pour l'exécution des commandes.

**agentRuntimeArn** (`string`): ARN d'AgentCore Runtime dans lequel les commandes sont exécutées.

## Méthodes

### Exécution des commandes

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

Exécute une commande shell ponctuelle dans la session AgentCore Runtime et renvoie stdout, stderr, le code de sortie et l'état du délai d'expiration.

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

Renvoie : `Promise<CommandResult>`.

`options.timeout` est exprimé en millisecondes. AgentCore Runtime accepte des délais d'expiration de commande compris entre 1 et 3 600 secondes. Le Provider convertit les millisecondes en secondes avant d'envoyer la requête.

### Cycle de vie

#### `start()`

Exécute le hook de démarrage du cycle de vie de la Sandbox. Ce Provider ne crée pas de session AgentCore Runtime pendant `start()`.

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

#### `stop()`

Arrête la session AgentCore Runtime uniquement lorsque `stopSessionOnLifecycle` vaut `true`.

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

#### `stopRuntimeSession()`

Arrête explicitement la session AgentCore Runtime utilisée par cette Sandbox.

Utilisez cette méthode lorsque la Sandbox possède la session d'exécution et que vous souhaitez la nettoyer directement. `destroy()` n'appelle pas cette méthode sauf si `stopSessionOnLifecycle` vaut `true`, car les sessions AgentCore Runtime peuvent être partagées avec des invocations d'Agents extérieures au cycle de vie de la Sandbox du Workspace.

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

#### `destroy()`

Détruit l'instance de Sandbox. Si cette instance possède son client SDK AWS, `destroy()` détruit également le client. Si `stopSessionOnLifecycle` vaut `true`, la méthode appelle `StopRuntimeSession`.

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

### Métadonnées

#### `getInfo()`

Renvoie l'état de la Sandbox et les métadonnées d'AgentCore Runtime.

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

Renvoie : `Promise<SandboxInfo>`.

## Limitations

`AgentCoreRuntimeSandbox` suit la sémantique d'exécution des commandes d'AgentCore Runtime :

- **Commandes ponctuelles** : chaque commande s'exécute jusqu'à son terme ou jusqu'à l'expiration du délai.
- **Aucun shell persistant** : l'état du shell n'est pas conservé entre les commandes. Encodez l'état dans chaque commande, par exemple `cd /workspace && npm test`.
- **Processus en arrière-plan non pris en charge** : le Provider n'expose pas de gestionnaire `processes`.
- **stdin interactif indisponible** : l'exécution des commandes Runtime ne fournit pas de flux stdin interactif par l'intermédiaire de ce Provider.
- **Montages du système de fichiers Workspace non pris en charge** : ce Provider ne prend pas en charge le montage du système de fichiers Workspace.
- **Tools dépendant du conteneur** : les commandes peuvent uniquement utiliser les Tools installés dans l'image de conteneur AgentCore Runtime.

## Voir aussi

- [Interface WorkspaceSandbox](https://mastra.zisheng.pro/fr/reference/workspace/sandbox)
- [Classe Workspace](https://mastra.zisheng.pro/fr/reference/workspace/workspace-class)
- [Présentation de Sandbox](https://mastra.zisheng.pro/fr/docs/workspace/sandbox)
- [Exécution des commandes AWS Bedrock AgentCore Runtime](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-execute-command.html)