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

# 程式碼模式

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

> **Beta:** 此功能目前為 beta 版本。在 API 穩定之前，即使主要版本號不變，亦可能會有破壞性變更。

程式碼模式讓 Agent 在隔離的 Sandbox 中執行涉及多個 Tool 的運算，並將結果以單一而更準確的回應傳回。

模型不會每次輪流呼叫一個 Tool，而是針對用戶查詢編寫專用函式。該函式會將你現有的 Tool 編排為 `external_*` 函式，並歸納或匯總其結果，產生一個結構化答案。

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

## 何時使用程式碼模式

當 Agent 需要使用多個 Tool 來回答用戶查詢或執行複雜運算時，可使用程式碼模式：

- 減少往返次數：涉及多個 Tool 的查詢只需一次 Tool 呼叫即可執行，毋須為每次 Tool 選擇重複執行 Agent 迴圈。
- 縮小上下文：函式可在將大型 Tool 回應傳回 Agent 前，先行歸納或匯總內容。
- 準確運算：總和、平均值及其他算術運算會以 JavaScript 執行，而非透過 token 預測完成。
- 預先規劃：篩選、匯總及分支邏輯均在函式內進行，而非分散於不同輪次。

## 運作方式

不使用程式碼模式時，涉及多個 Tool 的查詢可能會多次執行 Agent 迴圈。模型會選擇一個 Tool 並讀取結果，再按需要重複此過程。

每一輪都會將完整的 Tool 回應加入 Agent 的上下文視窗，可能導致推理質素下降，並增加 token 用量。

使用程式碼模式時，你的 Tool 仍會在主機上執行，並保留完整的驗證、請求上下文及追蹤功能。只有模型編排 Tool 的程式碼會在 Sandbox 中執行。每次呼叫 `external_*` 都會橋接回主機上實際的 Tool，而函式可先歸納或匯總結果，再向 Agent 傳回單一回應。

函式會在 [Workspace Sandbox](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview) 中執行。程式碼模式會執行由模型編寫的程式碼，因此必須使用 Sandbox，並審慎選擇執行邊界。你可以透過 `sandbox` 傳入 Sandbox，或在能提供 Sandbox 的 Workspace 中執行 Agent。如要在主機上執行，請明確傳入 `new LocalSandbox()`。這會以主機權限將函式作為主機的 `node` 程序執行，因此只應用於受信任的程式碼或本機開發。

自帶執行邊界的 Transport 則屬例外：使用 [`IsolatedVmCodeModeTransport`](https://mastra.zisheng.pro/zh-HK/reference/tools/isolated-vm-transport) 時，程式會在程序內的 V8 isolate 中執行，因此不需要 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 },
})
```

當用戶問「銷量最高的五款產品是甚麼？每款產品的平均評分又是多少？」時，模型會發出一次 `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` 並行執行呼叫，程式碼模式最能發揮作用。

請參閱 [`createCodeMode()` 參考資料](https://mastra.zisheng.pro/zh-HK/reference/tools/create-code-mode)，了解設定選項、傳回值、結果結構及如何檢視指示。

## 為多個程式碼 Tool 設定 Tool 範圍

`createCodeMode()` 會擷取其本身的允許清單。多次呼叫此函式，即可為 Agent 提供數個程式碼 Tool，並讓每個 Tool 限定使用不同的 Tool 子集。程式碼 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

程式碼模式預設使用一種 Transport，將程式寫入主機檔案系統，再透過 `node` 執行。這種方式適用於與主機共用環境的 `LocalSandbox`，但不適用於在其本身 micro-VM 中執行的遙距 Sandbox（例如 [E2B](https://mastra.zisheng.pro/zh-HK/reference/workspace/e2b-sandbox)），因為主機路徑在該環境中並不存在。

遙距 Sandbox 需要使用能將程式寫入 Sandbox 檔案系統的 Transport。使用 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-HK/reference/tools/isolated-vm-transport)。它會在程序內的 V8 isolate 中執行程式，因此不需要 Sandbox：該 isolate 無法存取檔案系統、網絡或程序，唯一可用的功能是橋接回主機 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-HK/reference/tools/isolated-vm-transport)。

## 相關內容

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