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

# createCodeMode()

**加入版本：** `@mastra/core@1.38.0`

`createCodeMode()` 函式會回傳一個 Tool 與產生的 instructions，讓 Agent 能以單一 TypeScript 函式執行多 Tool 運算。產生的程式碼會在 Workspace Sandbox 中執行，每次 `external_*` 呼叫則會在主機上執行實際 Tool，並套用驗證、request context 與 tracing。

概念說明請參閱 [Code mode](https://mastra.zisheng.pro/zh-TW/docs/agents/code-mode)。

## 使用範例

建立 Code mode Tool、將產生的 instructions 加入 Agent，並以相同 ID 註冊回傳的 Tool。

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

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 的設定。

**config.tools** (`ToolsInput`): 以 external\_\<id> 函式形式提供給產生程式碼的 Tool。只有這些 Tool 可以被呼叫。

**config.sandbox** (`WorkspaceSandbox`): 用於執行產生程式碼的 Sandbox。除非 Agent 在提供 Sandbox 的 Workspace 中執行，或 transport 本身提供執行邊界（例如 IsolatedVmCodeModeTransport），否則此值為必填。若要明確在主機上執行，請傳入 new LocalSandbox()。

**config.timeout** (`number`): 執行逾時時間（毫秒）。

**config.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

產生的 Tool 會回傳 `CodeModeToolResult`。

**success** (`boolean`): 產生的程式碼是否在未擲回例外的情況下執行完成。

**result** (`unknown`): 產生的程式碼所回傳的值。

**logs** (`string[]`): 依序擷取自 console.log、console.info、console.warn 與 console.error 的主控台輸出。

**error** (`{ message: string; name?: string; line?: number }`): 產生的程式碼擲回例外或執行失敗時的錯誤詳細資訊。

**error.message** (`string`): 錯誤訊息。

**error.name** (`string`): 錯誤名稱（如有）。

**error.line** (`number`): 與失敗相關的行號（如有）。

## 檢查 instructions

使用 `createCodeModeInstructions()` 檢查為一組 Tool 產生的確切 prompt 內容。

```typescript
import { createCodeModeInstructions } from '@mastra/core/tools'

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

Instructions 會包含使用契約，並為每個已設定的 Tool 提供一行具型別的 `declare function external_<id>(...)`。Tool ID 會經過清理，轉為有效的 TypeScript 函式名稱；若清理後的名稱互相衝突，則會擲回錯誤。

## createCodeModeTool()

如果你只需要 Tool，並想自行管理 instructions，請使用 `createCodeModeTool()`。多數 Agent 應使用 `createCodeMode()`，讓 Tool 與相符的 instructions 保持配對。

```typescript
import { createCodeModeTool } from '@mastra/core/tools'
import { LocalSandbox } from '@mastra/core/workspace'

export const codeModeTool = createCodeModeTool({
  tools: { getTopProducts, getProductRatings },
  sandbox: new LocalSandbox(),
})
```

## 相關內容

- [Code mode](https://mastra.zisheng.pro/zh-TW/docs/agents/code-mode)
- [createTool()](https://mastra.zisheng.pro/zh-TW/reference/tools/create-tool)
- [Workspace 概覽](https://mastra.zisheng.pro/zh-TW/docs/workspace/overview)