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

# createCodeMode()

**추가된 항목:** `@mastra/core@1.38.0`

`createCodeMode()` 함수는 Agent가 여러 Tool을 사용하는 계산을 하나의 TypeScript 함수로 실행할 수 있도록 Tool과 생성된 지침을 반환합니다. 생성된 코드는 Workspace Sandbox에서 실행되며, 각 `external_*` 호출은 유효성 검사, 요청 컨텍스트 및 Tracing을 거쳐 호스트에서 실제 Tool을 실행합니다. 개념적 개요는 다음을 참조하세요.[Code mode](https://mastra.zisheng.pro/ko/docs/agents/code-mode).

## 사용예

코드 모드 Tool을 만들고, 생성된 지침을 Agent에 추가하고, 반환된 Tool을 동일한 ID로 등록합니다.

```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> 함수로 노출되는 Tool입니다. 이 Tool만 호출할 수 있습니다.

**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` object.

**tool** (`Tool<any, any>`): 생성된 코드 모드 Tool입니다. 기본 ID는 execute\_typescript입니다.

**instructions** (`string`): 구성된 Tool에 대한 형식 지정된 external\_\* 선언이 포함된 생성된 Model 지침입니다.

## 코드모드Tool결과

생성된 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`): 사용 가능한 경우 실패와 관련된 줄 번호입니다.

## 검사 지침

Tool 집합에 대해 생성되는 정확한 Prompt 내용을 확인하려면 `createCodeModeInstructions()`를 사용하세요.

```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는 Tool과 일치하는 지침을 함께 유지할 수 있도록 `createCodeMode()`을 사용해야 합니다.

```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/ko/docs/agents/code-mode)
- [생성Tool()](https://mastra.zisheng.pro/ko/reference/tools/create-tool)
- [작업공간 개요](https://mastra.zisheng.pro/ko/docs/workspace/overview)