Aller au contenu principal

IsolatedVmCodeModeTransport

beta

Cette fonctionnalité est en version bêta. Des modifications incompatibles peuvent intervenir sans changement de version majeure tant que l’API n’est pas stable.

La classe IsolatedVmCodeModeTransport exécute les programmes en Code Mode dans un isolat V8 intégré au processus, fourni par isolated-vm. L’isolat constitue la limite d’exécution ; aucun Sandbox de Workspace n’est donc requis : le programme n’a accès ni au système de fichiers, ni au réseau, ni aux processus, ni aux modules. Ses seules capacités sont les fonctions external_*, qui rappellent les véritables Tools sur l’hôte.

Contrairement au transport StdioCodeModeTransport par défaut, celui-ci ne crée aucun processus et n’écrit aucun fichier temporaire. Il convient donc bien aux hôtes serverless et multilocataires sur lesquels aucune isolation au niveau du système d’exploitation n’est disponible.

Installation
Lien direct vers Installation

npm install @mastra/isolated-vm

isolated-vm est un module complémentaire natif. Il fournit des binaires précompilés pour les plateformes courantes ; son installation ne nécessite donc généralement aucune configuration supplémentaire. Une chaîne d’outils C++ n’est requise que sur les plateformes pour lesquelles aucun binaire précompilé compatible n’existe, car le module est alors compilé à partir des sources.

Avec Node.js 20 et les versions ultérieures, le processus hôte doit être démarré avec l’option --no-node-snapshot. Sans elle, la création d’un isolat provoque l’arrêt brutal du processus. Le constructeur génère une erreur si l’option est absente. Transmettez-la au démarrage de votre serveur ou définissez-la avec NODE_OPTIONS :

NODE_OPTIONS=--no-node-snapshot npm run dev

Utilisation
Lien direct vers Utilisation

Transmettez le transport comme deuxième argument de createCodeMode(). Aucun sandbox n’est nécessaire :

import { createCodeMode } from '@mastra/core/tools'
import { IsolatedVmCodeModeTransport } from '@mastra/isolated-vm'

const { tool, instructions } = createCodeMode(
  { tools: { getTopProducts, getProductRatings } },
  new IsolatedVmCodeModeTransport({ memoryLimitMb: 128 }),
)

Paramètres du constructeur
Lien direct vers Paramètres du constructeur

options?:

IsolatedVmCodeModeTransportOptions
Configuration de l’isolat.
IsolatedVmCodeModeTransportOptions

memoryLimitMb?:

number
Limite du tas de l’isolat V8 en Mio. Tout programme qui dépasse cette limite est interrompu et le Tool renvoie un résultat d’erreur.

Fonctionnement
Lien direct vers Fonctionnement

Chaque exécution crée un nouvel isolat avec son propre tas. TypeScript est supprimé sur l’hôte avec esbuild, puis le programme est évalué dans l’isolat. Chaque appel external_* franchit la limite de l’isolat sous forme de chaînes JSON dans les deux sens ; aucune référence à un objet de l’hôte ne peut donc se retrouver dans le code produit par le modèle. La liste d’autorisation, la validation des Tools, le contexte de requête et le traçage s’exécutent tous sur l’hôte, comme avec les autres transports.

Le timeout configuré dans createCodeMode() s’applique à la fois aux blocages asynchrones et aux boucles infinies synchrones, et l’isolat est libéré après chaque exécution.

On this page