createCodeMode()

Ajouté dans : @mastra/core@1.38.0

La fonction createCodeMode() renvoie un Tool et des instructions générées qui permettent à un Agent d'exécuter des calculs faisant appel à plusieurs Tools sous la forme d'une seule fonction TypeScript. Le code généré s'exécute dans le Sandbox d'un Workspace, et chaque appel external_* exécute le véritable Tool sur l'hôte avec validation, contexte de requête et Tracing.

Pour une présentation conceptuelle, consultez le mode Code.

Exemple d'utilisation

Créez un Tool de mode Code, ajoutez les instructions générées à l'Agent et enregistrez le Tool renvoyé avec le même identifiant.

src/mastra/agents/shop-agent.ts

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(),
})

export const shopAgent = 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 },
})

Paramètres

config:

CodeModeConfig

Configuration du Tool de mode Code et des instructions générées.

CodeModeConfig

tools:

ToolsInput

Tools exposés au code généré sous la forme de fonctions external_<id>. Seuls ces Tools peuvent être appelés.

sandbox?:

WorkspaceSandbox

Sandbox utilisé pour exécuter le code généré. Obligatoire, sauf si l'Agent s'exécute dans un Workspace qui fournit un Sandbox ou si le transport fournit sa propre limite d'exécution (telle que IsolatedVmCodeModeTransport). Transmettez new LocalSandbox() pour exécuter explicitement le code sur l'hôte.

timeout?:

number

Délai d'expiration de l'exécution, en millisecondes.

id?:

string

Identifiant du Tool généré.

transport?:

CodeModeTransport

Implémentation de transport facultative utilisée pour exécuter le code généré dans le Sandbox. Le transport par défaut utilise JSON-RPC sur stdio au moyen de l'API de processus du Sandbox du Workspace. Les transports qui déclarent requiresSandbox: false (tels que IsolatedVmCodeModeTransport) s'exécutent sans Sandbox.

Valeur renvoyée

Renvoie un objet CodeModeResult.

tool:

Tool<any, any>

Tool de mode Code généré. Par défaut, son identifiant est execute_typescript.

instructions:

string

Instructions générées pour le modèle, avec des déclarations external_* typées pour les Tools configurés.

CodeModeToolResult

Le Tool généré renvoie un CodeModeToolResult.

success:

boolean

Indique si l'exécution du code généré s'est terminée sans lever d'erreur.

result?:

unknown

Valeur renvoyée par le code généré.

logs?:

string[]

Sorties de console capturées dans l'ordre depuis console.log, console.info, console.warn et console.error.

error?:

{ message: string; name?: string; line?: number }

Détails de l'erreur lorsque le code généré lève une erreur ou ne parvient pas à s'exécuter.

{ message: string; name?: string; line?: number }

message:

string

Message d'erreur.

name?:

string

Nom de l'erreur, lorsqu'il est disponible.

line?:

number

Numéro de ligne associé à l'échec, lorsqu'il est disponible.

Inspection des instructions

Utilisez createCodeModeInstructions() pour examiner le contenu exact du prompt généré pour un ensemble de Tools.

src/mastra/tools/code-mode-instructions.ts

import { createCodeModeInstructions } from '@mastra/core/tools'

console.log(
  createCodeModeInstructions({
    tools: { getTopProducts, getProductRatings },
  }),
)

Les instructions comprennent le contrat d'utilisation et une ligne declare function external_<id>(...) typée pour chaque Tool configuré. Les identifiants des Tools sont nettoyés afin de former des noms de fonctions TypeScript valides, et les noms nettoyés en conflit lèvent une erreur.

createCodeModeTool()

Utilisez createCodeModeTool() lorsque vous avez uniquement besoin du Tool et souhaitez gérer les instructions séparément. La plupart des Agents doivent utiliser createCodeMode() afin que le Tool et les instructions correspondantes restent groupés.

src/mastra/tools/code-mode-tool.ts

import { createCodeModeTool } from '@mastra/core/tools'
import { LocalSandbox } from '@mastra/core/workspace'

export const codeModeTool = createCodeModeTool({
  tools: { getTopProducts, getProductRatings },
  sandbox: new LocalSandbox(),
})

Voir aussi

• Mode Code
• createTool()
• Présentation de Workspace