> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# Code mode

**新增於：** `@mastra/core@1.38.0`

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

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

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

[`createCodeMode()`](https://mastra.zisheng.pro/zh-TW/reference/tools/create-code-mode) 會傳回此 Tool，預設 `id` 為 `execute_typescript`。`id` 可自行設定，因此一個 Agent 可同時擁有多個 Code mode Tool，每個 Tool 分別限定使用不同的一組 Tool（請參閱[在多個 Code Tool 之間限定 Tool 範圍](#scoping-tools-across-multiple-code-tools)）。

## 何時使用 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](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview) 中執行。由於 Code mode 會執行模型撰寫的程式碼，且必須審慎選擇執行邊界，因此必須使用 Sandbox。請透過 `sandbox` 傳入 Sandbox，或在提供 Sandbox 的 Workspace 中執行 Agent。若要在主機上執行，請明確傳入 `new LocalSandbox()`。這會以主機權限將函式作為主機 `node` 處理程序執行，因此只能用於受信任或本機開發情境。

自帶執行邊界的傳輸方式是例外：使用 [`IsolatedVmCodeModeTransport`](https://mastra.zisheng.pro/zh-TW/reference/tools/isolated-vm-transport) 時，程式會在處理程序內的 V8 隔離環境中執行，因此不需要 Sandbox（請參閱[處理程序內隔離](#in-process-isolation)）。

## 快速入門

`createCodeMode()` 會傳回 Tool 與產生的指令。未提供 `id` 時，Tool 名稱為 `execute_typescript`。請將兩者都加入 Agent：

```typescript
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 呼叫：

```typescript
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()` 參考文件](https://mastra.zisheng.pro/zh-TW/reference/tools/create-code-mode)。

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

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

請為每個 Tool 指定不同的 `id`，避免 ID 衝突，並將每個 Tool 的指令加入 Agent：

```typescript
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](https://mastra.zisheng.pro/zh-TW/reference/workspace/e2b-sandbox)），因為主機路徑不存在於其中。

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

```typescript
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`](https://mastra.zisheng.pro/zh-TW/reference/tools/isolated-vm-transport)。它會在處理程序內的 V8 隔離環境執行程式，因此不需要 Sandbox：此隔離環境無法存取檔案系統、網路或處理程序，唯一能力是橋接回主機 Tool 的 `external_*` 函式。

```typescript
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 參考文件](https://mastra.zisheng.pro/zh-TW/reference/tools/isolated-vm-transport)。

## 相關內容

- [createCodeMode() 參考文件](https://mastra.zisheng.pro/zh-TW/reference/tools/create-code-mode)
- [IsolatedVmCodeModeTransport 參考文件](https://mastra.zisheng.pro/zh-TW/reference/tools/isolated-vm-transport)
- [Tool](https://mastra.zisheng.pro/zh-TW/docs/agents/using-tools)
- [Workspace 概觀](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview)