createCodeMode()

Added in: @mastra/core@1.38.0

The createCodeMode() function returns a tool and generated instructions that let an agent run multi-tool computations as one TypeScript function. The generated code runs in a workspace sandbox, and each external_* call runs the real tool on the host with validation, request context, and tracing.

For a conceptual overview, see Code mode.

Usage example

Create a code mode tool, add its generated instructions to the agent, and register the returned tool with the same id.

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

Parameters

config:

CodeModeConfig

Configuration for the code mode tool and generated instructions.

CodeModeConfig

tools:

ToolsInput

Tools exposed to the generated code as external_<id> functions. Only these tools can be called.

sandbox?:

WorkspaceSandbox

Sandbox used to execute the generated code. Required unless the agent runs in a workspace that provides a sandbox, or the transport provides its own execution boundary (such as IsolatedVmCodeModeTransport). Pass new LocalSandbox() to run on the host explicitly.

timeout?:

number

Execution timeout in milliseconds.

id?:

string

The generated tool id.

transport?:

CodeModeTransport

Optional transport implementation used to run the generated code in the sandbox. The default transport uses stdio JSON-RPC over the workspace sandbox process API. Transports that declare requiresSandbox: false (such as IsolatedVmCodeModeTransport and QuickJsCodeModeTransport) run without a sandbox.

Returns

Returns a CodeModeResult object.

tool:

Tool<any, any>

The generated code mode tool. By default, its id is execute_typescript.

instructions:

string

Generated model instructions with typed external_* declarations for the configured tools.

CodeModeToolResult

The generated tool returns a CodeModeToolResult.

success:

boolean

Whether the generated code ran to completion without throwing.

result?:

unknown

The value returned by the generated code.

logs?:

string[]

Captured console output from console.log, console.info, console.warn, and console.error, in order.

error?:

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

Error details when the generated code throws or fails to execute.

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

message:

string

Error message.

name?:

string

Error name, when available.

line?:

number

Line number associated with the failure, when available.

Inspecting instructions

Use createCodeModeInstructions() to inspect the exact prompt content generated for a set of tools.

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

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

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

The instructions include the usage contract and one typed declare function external_<id>(...) line for each configured tool. Tool ids are sanitized into valid TypeScript function names, and conflicting sanitized names throw an error.

createCodeModeTool()

Use createCodeModeTool() when you only need the tool and want to manage instructions separately. Most agents should use createCodeMode() so the tool and matching instructions stay together.

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

Related

• Code mode
• createTool()
• Sandbox