Mode code

Ajouté dans : @mastra/core@1.38.0

beta

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

Le mode code permet à un Agent d'effectuer des calculs avec plusieurs outils dans une sandbox isolée et de renvoyer le résultat sous la forme d'une réponse unique et plus précise.

Au lieu d'appeler les outils un à un au fil des tours, le modèle écrit une fonction adaptée à la requête de l'utilisateur. Cette fonction orchestre vos outils existants sous la forme de fonctions external_*, puis réduit ou agrège leurs résultats en une seule réponse structurée.

createCodeMode() renvoie cet outil avec l'id par défaut execute_typescript. L'id est configurable : un Agent peut donc disposer simultanément de plusieurs outils de mode code, chacun limité à un ensemble d'outils différent (consultez la délimitation des outils entre plusieurs outils de code).

Quand utiliser le mode code

Utilisez le mode code lorsqu'un Agent fait appel à plusieurs outils pour répondre à une requête utilisateur ou effectuer un calcul complexe :

• Moins d'allers-retours : une requête utilisant plusieurs outils s'exécute en un seul appel d'outil au lieu de répéter la boucle de l'Agent pour chaque décision.
• Contexte réduit : la fonction peut réduire ou agréger les réponses volumineuses des outils avant de les renvoyer à l'Agent.
• Calculs exacts : les sommes, moyennes et autres opérations arithmétiques s'exécutent en JavaScript au lieu de reposer sur la prédiction de tokens.
• Planification en amont : le filtrage, l'agrégation et les branchements ont lieu dans la fonction plutôt qu'au fil de tours distincts.

Fonctionnement

Sans le mode code, les requêtes qui utilisent plusieurs outils peuvent exécuter plusieurs fois la boucle de l'Agent. Le modèle choisit un outil, lit son résultat, puis répète ce processus au besoin.

Chaque tour ajoute la réponse complète de l'outil à la fenêtre de contexte de l'Agent, ce qui peut dégrader le raisonnement et augmenter la consommation de tokens.

Avec le mode code, vos outils continuent de s'exécuter sur l'hôte avec la validation complète, le contexte de requête et le tracing. Seul le code d'orchestration du modèle s'exécute dans la sandbox. Chaque appel external_* est redirigé vers l'outil réel sur l'hôte, et la fonction peut réduire ou agréger les résultats avant de renvoyer une réponse unique à l'Agent.

La fonction s'exécute dans une sandbox de Workspace. Une sandbox est requise, car le mode code exécute du code écrit par le modèle et la frontière d'exécution doit être choisie explicitement. Transmettez-en une via sandbox, ou exécutez l'Agent dans un Workspace qui en fournit une. Pour exécuter le code sur la machine hôte, transmettez explicitement new LocalSandbox(). La fonction s'exécute alors comme processus node sur l'hôte avec les privilèges de celui-ci ; réservez donc cette configuration au développement local ou à du code de confiance.

Les transports qui fournissent leur propre frontière d'exécution constituent une exception : avec IsolatedVmCodeModeTransport, le programme s'exécute dans un isolate V8 au sein du processus et aucune sandbox n'est nécessaire (consultez l'isolation au sein du processus).

Démarrage rapide

createCodeMode() renvoie l'outil ainsi que les instructions générées. En l'absence d'id, l'outil porte le nom execute_typescript. Ajoutez ces deux éléments à votre Agent :

import { Agent } from '@mastra/core/agent'
import { createCodeMode, createTool } from '@mastra/core/tools'
import { LocalSandbox } from '@mastra/core/workspace'
import { z } from 'zod'

const getTopProducts = createTool({
  id: 'getTopProducts',
  description: 'Get top selling products',
  inputSchema: z.object({ limit: z.number() }),
  outputSchema: z.object({
    products: z.array(z.object({ id: z.string(), name: z.string(), totalSales: z.number() })),
  }),
  execute: async ({ limit }) => fetchTopProducts(limit),
})

const getProductRatings = createTool({
  id: 'getProductRatings',
  description: 'Get ratings for a product',
  inputSchema: z.object({ productId: z.string() }),
  outputSchema: z.object({ ratings: z.array(z.object({ score: z.number() })) }),
  execute: async ({ productId }) => fetchRatings(productId),
})

const { tool, instructions } = createCodeMode({
  tools: { getTopProducts, getProductRatings },
  sandbox: new LocalSandbox(), // required; runs on the host — see "How it works"
})

const agent = new Agent({
  id: 'shop-assistant',
  name: 'shop-assistant',
  instructions: ['You are a helpful shopping assistant.', instructions],
  model: 'openai/gpt-5.6-sol',
  tools: { execute_typescript: tool },
})

À la question « Quels sont les cinq produits les plus vendus et la note moyenne de chacun ? », le modèle émet un seul appel execute_typescript au lieu de nombreux appels d'outils distincts :

const top = await external_getTopProducts({ limit: 5 })
const ratings = await Promise.all(
  top.products.map(p => external_getProductRatings({ productId: p.id })),
)
return top.products.map((product, i) => {
  const scores = ratings[i].ratings.map(r => r.score)
  const avg = scores.reduce((sum, s) => sum + s, 0) / scores.length
  return {
    name: product.name,
    sales: product.totalSales,
    averageRating: Math.round(avg * 100) / 100,
  }
})

Les cinq recherches de notes s'exécutent en parallèle, les moyennes sont calculées en JavaScript et l'Agent reçoit un résultat structuré unique.

Pour tirer le meilleur parti de createCodeMode(), gardez ces conseils à l'esprit :

• Veillez à ce que chaque outil se concentre sur une seule tâche bien définie, afin que le modèle puisse les composer dans le code.
• Le mode code est particulièrement efficace lorsque les appels peuvent être parallélisés avec Promise.all.

Consultez la référence de createCodeMode() pour les options de configuration, les valeurs de retour, la forme du résultat et l'inspection des instructions.

Délimiter les outils entre plusieurs outils de code

createCodeMode() conserve sa propre liste d'autorisation. Appelez-la plusieurs fois pour fournir à un Agent plusieurs outils de code, chacun limité à un sous-ensemble différent. Chaque outil ne peut appeler que les fonctions external_* correspondant aux outils transmis à son propre appel createCodeMode() ; les sous-ensembles restent donc isolés.

Attribuez à chaque outil un id distinct pour éviter les collisions, puis ajoutez les instructions de chaque outil à l'Agent :

const sales = createCodeMode({
  id: 'sales_code',
  tools: { listRecentOrders, getCustomer },
  sandbox,
})

const inventory = createCodeMode({
  id: 'inventory_code',
  tools: { listProducts, getSupplier },
  sandbox,
})

const agent = new Agent({
  id: 'ops-assistant',
  name: 'ops-assistant',
  instructions: ['You are an ops assistant.', sales.instructions, inventory.instructions],
  model: 'openai/gpt-5.6-sol',
  tools: { sales_code: sales.tool, inventory_code: inventory.tool },
})

Le code généré pour sales_code ne peut pas appeler un outil d'inventaire, et l'inverse est également vrai. Utilisez cette approche pour appliquer le principe du moindre privilège et limiter la surface de prompt de chaque outil.

Sandboxes distantes

Par défaut, le mode code utilise un transport qui écrit le programme dans le système de fichiers de l'hôte puis l'exécute avec node. Cela fonctionne avec LocalSandbox, qui partage l'hôte, mais pas avec les sandboxes distantes exécutées dans leur propre micro-VM, comme E2B, où les chemins de l'hôte n'existent pas.

Les sandboxes distantes nécessitent un transport qui écrit le programme dans leur système de fichiers. Pour E2B, transmettez le E2BCodeModeTransport inclus comme deuxième argument de createCodeMode :

import { createCodeMode } from '@mastra/core/tools'
import { E2BSandbox, E2BCodeModeTransport } from '@mastra/e2b'

const { tool, instructions } = createCodeMode(
  { tools, sandbox: new E2BSandbox() },
  new E2BCodeModeTransport(),
)

Isolation au sein du processus

Pour obtenir une frontière sécurisée sans créer de processus ni exécuter de sandbox distante, utilisez IsolatedVmCodeModeTransport du package @mastra/isolated-vm. Il exécute le programme dans un isolate V8 au sein du processus, sans nécessiter de sandbox : l'isolate n'a accès ni au système de fichiers, ni au réseau, ni aux processus ; ses seules capacités sont les fonctions external_* reliées à vos outils sur l'hôte.

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

const { tool, instructions } = createCodeMode(
  { tools }, // no sandbox needed
  new IsolatedVmCodeModeTransport({ memoryLimitMb: 128 }),
)

isolated-vm est un module complémentaire natif. Avec Node.js 20 et versions ultérieures, le processus hôte doit être démarré avec l'option --no-node-snapshot. Consultez la référence de IsolatedVmCodeModeTransport pour les détails de configuration.

Voir aussi

• Référence de createCodeMode()
• Référence de IsolatedVmCodeModeTransport
• Tools
• Présentation de Workspace