Code mode

新增於： @mastra/core@1.38.0

beta

此功能目前為 Beta 版。在 API 穩定之前，即使未提升主要版本，也可能出現破壞性變更。

Code mode 可讓 Agent 在隔離的 Sandbox 中執行多 Tool 運算，並將結果以單一且更準確的回應傳回。

模型不再逐回合呼叫 Tool，而是針對使用者查詢撰寫專用函式。此函式會將現有 Tool 編排為 external_* 函式，並縮減或彙整其結果，形成一個結構化答案。

createCodeMode() 會傳回此 Tool，預設 id 為 execute_typescript。id 可自行設定，因此一個 Agent 可同時擁有多個 Code mode Tool，每個 Tool 分別限定使用不同的一組 Tool（請參閱在多個 Code Tool 之間限定 Tool 範圍）。

何時使用 Code mode

當 Agent 需要操作多個 Tool 來回答使用者查詢或執行複雜運算時，請使用 Code mode：

• 減少往返次數：多 Tool 查詢只需一次 Tool 呼叫，不必為每個 Tool 決策重複 Agent 循環。
• 縮小情境：函式可先縮減或彙整大型 Tool 回應，再傳回給 Agent。
• 正確運算：加總、平均值與其他算術由 JavaScript 執行，而非透過 token 預測。
• 預先規劃：篩選、彙整與分支都在函式內進行，不必分散至多個回合。

運作方式

若未使用 Code mode，多 Tool 查詢可能需要執行數次 Agent 循環。模型選擇 Tool 並讀取結果，再視需要重複此流程。

每個回合都會將完整 Tool 回應加入 Agent 的情境視窗，可能導致推理品質下降並增加 token 用量。

使用 Code mode 時，Tool 仍在主機上執行，並保有完整的驗證、請求情境和追蹤功能。只有模型的編排程式碼會在 Sandbox 中執行。每次 external_* 呼叫都會橋接回主機上真正的 Tool，函式則可先縮減或彙整結果，再向 Agent 傳回一個回應。

函式會在 Workspace Sandbox 中執行。由於 Code mode 會執行模型撰寫的程式碼，且必須審慎選擇執行邊界，因此必須使用 Sandbox。請透過 sandbox 傳入 Sandbox，或在提供 Sandbox 的 Workspace 中執行 Agent。若要在主機上執行，請明確傳入 new LocalSandbox()。這會以主機權限將函式作為主機 node 處理程序執行，因此只能用於受信任或本機開發情境。

自帶執行邊界的傳輸方式是例外：使用 IsolatedVmCodeModeTransport 時，程式會在處理程序內的 V8 隔離環境中執行，因此不需要 Sandbox（請參閱處理程序內隔離）。

快速入門

createCodeMode() 會傳回 Tool 與產生的指令。未提供 id 時，Tool 名稱為 execute_typescript。請將兩者都加入 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 },
})

當使用者詢問「銷量最高的 5 項產品是哪些？各自的平均評分是多少？」時，模型會發出一次 execute_typescript 呼叫，而非多次個別 Tool 呼叫：

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

五次評分查詢會全部平行執行，平均值由 JavaScript 計算，而 Agent 只會收到一個結構化結果。

若要讓 createCodeMode() 發揮良好效果，請留意以下事項：

• 讓每個 Tool 專注做好一件事，以便模型在程式碼中組合它們。
• 呼叫能以 Promise.all 平行執行時，Code mode 最能發揮效益。

如需設定選項、傳回值、結果結構與指令檢查方式，請參閱 createCodeMode() 參考文件。

在多個 Code Tool 之間限定 Tool 範圍

createCodeMode() 會擷取自己的允許清單。多次呼叫它，即可為 Agent 提供多個 Code Tool，並分別限定至不同的 Tool 子集。每個 Code Tool 只能呼叫傳入自身 createCodeMode() 呼叫之 Tool 所對應的 external_* 函式，因此各子集會保持隔離。

請為每個 Tool 指定不同的 id，避免 ID 衝突，並將每個 Tool 的指令加入 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 },
})

為 sales_code 產生的程式碼無法呼叫庫存 Tool，反之亦然。你可以運用這項特性落實最低權限範圍，並縮小每個 Tool 的提示詞表面。

遠端 Sandbox

Code mode 預設會使用一種傳輸方式，將程式寫入主機檔案系統，並以 node 執行。這適用於與主機共用環境的 LocalSandbox，但不適用於在自身微型 VM 中執行的遠端 Sandbox（例如 E2B），因為主機路徑不存在於其中。

遠端 Sandbox 需要能將程式寫入 Sandbox 檔案系統的傳輸方式。使用 E2B 時，請將隨附的 E2BCodeModeTransport 作為第二個引數傳入 createCodeMode：

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

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

處理程序內隔離

若要在不產生處理程序或執行遠端 Sandbox 的情況下取得安全邊界，請使用 @mastra/isolated-vm 的 IsolatedVmCodeModeTransport。它會在處理程序內的 V8 隔離環境執行程式，因此不需要 Sandbox：此隔離環境無法存取檔案系統、網路或處理程序，唯一能力是橋接回主機 Tool 的 external_* 函式。

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 是原生附加元件；在 Node.js 20 以上版本中，必須使用 --no-node-snapshot 旗標啟動主機處理程序。如需設定詳細資訊，請參閱 IsolatedVmCodeModeTransport 參考文件。

相關內容

• createCodeMode() 參考文件
• IsolatedVmCodeModeTransport 參考文件
• Tool
• Workspace 概觀