跳至主要內容

createCodeMode()

新增於： @mastra/core@1.38.0

createCodeMode() 函數會傳回一個 Tool 及產生的指示，讓 Agent 將涉及多個 Tool 的運算作為單一 TypeScript 函數執行。產生的代碼會在 Workspace Sandbox 中執行，而每次 external_* 呼叫都會在主機上執行實際的 Tool，並套用驗證、請求上下文及追蹤。

如需概念概覽，請參閱代碼模式。

使用範例
使用範例 的直接連結

建立代碼模式 Tool，將產生的指示加入 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
代碼模式 Tool 及產生指示的設定。
CodeModeConfig

tools:

ToolsInput
以 external_<id> 函數形式向產生代碼公開的 Tools。只可呼叫這些 Tools。

sandbox?:

WorkspaceSandbox
用於執行產生代碼的 Sandbox。除非 Agent 在提供 Sandbox 的 Workspace 中執行，或傳輸本身提供執行邊界（例如 IsolatedVmCodeModeTransport），否則必須設定。傳入 new LocalSandbox() 可明確在主機上執行。

timeout?:

number
執行逾時時間（毫秒）。

id?:

string
產生的 Tool id。

transport?:

CodeModeTransport
可選的傳輸實作，用於在 Sandbox 中執行產生的代碼。預設傳輸會透過 Workspace Sandbox 的程序 API 使用 stdio JSON-RPC。宣告 requiresSandbox: false 的傳輸（例如 IsolatedVmCodeModeTransport）無需 Sandbox 即可執行。

傳回值
傳回值 的直接連結

傳回 CodeModeResult 物件。

tool:

Tool<any, any>
產生的代碼模式 Tool。其 id 預設為 execute_typescript。

instructions:

string
為已設定 Tools 產生的模型指示，當中包含具型別的 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
與失敗相關的行號（如有）。

檢視指示
檢視指示 的直接連結

使用 createCodeModeInstructions() 檢視為一組 Tools 產生的確切提示內容。

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

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

指示包含使用規範，以及每個已設定 Tool 各一行具型別的 declare function external_<id>(...)。Tool id 會經過清理，轉換成有效的 TypeScript 函數名稱；如清理後的名稱發生衝突，便會拋出錯誤。

createCodeModeTool()
createCodeModeTool() 的直接連結

如果只需要 Tool，並希望分開管理指示，請使用 createCodeModeTool()。大多數 Agent 應使用 createCodeMode()，讓 Tool 與相符的指示保持在一起。

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