跳到主要内容

createCodeMode()

加入版本： @mastra/core@1.38.0

createCodeMode() 函数会返回一个 Tool 与产生的 instructions，让 Agent 能以单一 TypeScript 函数运行多 Tool 运算。产生的代码会在 Workspace Sandbox 中运行，每次 external_* 调用则会在主机上运行实际 Tool，并套用验证、request context 与 tracing。

概念说明请参阅 Code mode。

使用示例
使用示例的直接链接

创建 Code mode Tool、将产生的 instructions 加入 Agent，并以相同 ID 注册返回的 Tool。

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

参数
参数的直接链接

config:

CodeModeConfig
Code mode Tool 与产生之 instructions 的设置。
CodeModeConfig

tools:

ToolsInput
以 external_<id> 函数形式提供给产生代码的 Tool。只有这些 Tool 可以被调用。

sandbox?:

WorkspaceSandbox
用于运行产生代码的 Sandbox。除非 Agent 在提供 Sandbox 的 Workspace 中运行，或 transport 本身提供运行边界（例如 IsolatedVmCodeModeTransport），否则此值为必填。若要明确在主机上运行，请传入 new LocalSandbox()。

timeout?:

number
运行逾时时间（毫秒）。

id?:

string
产生的 Tool ID。

transport?:

CodeModeTransport
选填的 transport 实作，用来在 Sandbox 中运行产生的代码。缺省 transport 会通过 Workspace Sandbox process API，使用 stdio JSON-RPC。声明 requiresSandbox: false 的 transport（例如 IsolatedVmCodeModeTransport）可在没有 Sandbox 的情况下运行。

返回值
返回值的直接链接

返回 CodeModeResult 对象。

tool:

Tool<any, any>
生成的 Code mode Tool。其 ID 默认为 execute_typescript。

instructions:

string
产生的模型 instructions，包含已设置 Tool 的具类型 external_* 声明。

CodeModeToolResult
CodeModeToolResult的直接链接

产生的 Tool 会返回 CodeModeToolResult。

success:

boolean
产生的代码是否在未掷回例外的情况下运行完成。

result?:

unknown
产生的代码所返回的值。

logs?:

string[]
依序截取自 console.log、console.info、console.warn 与 console.error 的主控台输出。

error?:

{ message: string; name?: string; line?: number }
产生的代码掷回例外或运行失败时的错误详细信息。
{ message: string; name?: string; line?: number }

message:

string
错误消息。

name?:

string
错误名称（如有）。

line?:

number
与失败相关的行号（如有）。

检查 instructions
检查 instructions的直接链接

使用 createCodeModeInstructions() 检查为一组 Tool 生成的确切 prompt 内容。

src/mastra/tools/code-mode-instructions.ts
import { createCodeModeInstructions } from '@mastra/core/tools'

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

Instructions 包含使用约定，并为每个已配置的 Tool 提供一行带类型的 declare function external_<id>(...)。Tool ID 会经过清理，转换为有效的 TypeScript 函数名；如果清理后的名称相互冲突，则会抛出错误。

createCodeModeTool()
createCodeModeTool()的直接链接

如果你只需要 Tool，并想自行管理 instructions，请使用 createCodeModeTool()。多数 Agent 应使用 createCodeMode()，让 Tool 与相符的 instructions 保持配对。

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