AgentCoreRuntimeSandbox

Exécute des commandes shell dans une session AWS Bedrock AgentCore Runtime 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.

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

npm install @mastra/agentcore

pnpm

pnpm add @mastra/agentcore

Yarn

yarn add @mastra/agentcore

Bun

bun add @mastra/agentcore

Utilisation

Ajoutez un AgentCoreRuntimeSandbox à un Workspace et attribuez-le à un Agent :

src/mastra/agents/dev-agent.ts

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 :

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

= UUID généré

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.

qualifier?:

string

= DEFAULT

Qualificateur ou endpoint de l'Agent Runtime.

contentType?:

string

= application/json

Type MIME envoyé pour les requêtes de commande.

accept?:

string

= application/vnd.amazon.eventstream

En-tête Accept utilisé pour les flux d'événements de commande.

commandTimeout?:

number

= 300000

Délai d'expiration par défaut des commandes, en millisecondes.

stopSessionOnLifecycle?:

boolean

= false

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.

stopClientToken?:

string

= UUID généré

Token client utilisé lors de l'appel de StopRuntimeSession.

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.

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().

await sandbox.start()

stop()

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

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.

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.

await sandbox.destroy()

Métadonnées

getInfo()

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

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
• Classe Workspace
• Présentation de Sandbox
• Exécution des commandes AWS Bedrock AgentCore Runtime