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

# createCodeMode()

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

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

如需概念概覽，請參閱[代碼模式](https://mastra.zisheng.pro/zh-HK/docs/agents/code-mode)。

## 使用範例

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

**config.tools** (`ToolsInput`): 以 external\_\<id> 函數形式向產生代碼公開的 Tools。只可呼叫這些 Tools。

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

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

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

產生的 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`): 與失敗相關的行號（如有）。

## 檢視指示

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

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

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

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

## createCodeModeTool()

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

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

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

## 相關內容

- [代碼模式](https://mastra.zisheng.pro/zh-HK/docs/agents/code-mode)
- [createTool()](https://mastra.zisheng.pro/zh-HK/reference/tools/create-tool)
- [Workspace 概覽](https://mastra.zisheng.pro/zh-HK/docs/workspace/overview)