본문으로 건너뛰기

createCodeMode()

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

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

사용예
사용예에 대한 직접 링크

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

src/mastra/agents/shop-agent.ts
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 및 생성되는 지침의 구성입니다.
CodeModeConfig

tools:

ToolsInput
생성된 코드에 external_<id> 함수로 노출되는 Tool입니다. 이 Tool만 호출할 수 있습니다.

sandbox?:

WorkspaceSandbox
생성된 코드를 실행하는 데 사용되는 Sandbox입니다. Agent가 Sandbox를 제공하는 Workspace에서 실행되거나 전송 계층이 자체 실행 경계(예: IsolatedVmCodeModeTransport)를 제공하지 않는 한 필수입니다. 호스트에서 명시적으로 실행하려면 new LocalSandbox()를 전달하세요.

timeout?:

number
실행 제한 시간(밀리초)입니다.

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결과에 대한 직접 링크

생성된 Tool은CodeModeToolResult.

success:

boolean
생성된 코드가 예외를 발생시키지 않고 완료될 때까지 실행되었는지 여부입니다.

result?:

unknown
생성된 코드가 반환한 값입니다.

logs?:

string[]
console.log, console.info, console.warn, console.error에서 캡처한 콘솔 출력을 순서대로 나열합니다.

error?:

{ message: string; name?: string; line?: number }
생성된 코드가 예외를 발생시키거나 실행에 실패한 경우의 오류 세부 정보입니다.
{ message: string; name?: string; line?: number }

message:

string
오류 메시지입니다.

name?:

string
사용 가능한 경우 오류 이름입니다.

line?:

number
사용 가능한 경우 실패와 관련된 줄 번호입니다.

검사 지침
검사 지침에 대한 직접 링크

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

src/mastra/tools/code-mode-instructions.ts
import { createCodeModeInstructions } from '@mastra/core/tools'

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

지침에는 사용 계약과 구성된 각 Tool에 대해 형식이 지정된 declare function external_<id>(...) 줄이 포함됩니다. Tool ID는 유효한 TypeScript 함수 이름으로 정리되며, 정리된 이름이 충돌하면 오류가 발생합니다.

createCodeModeTool()
createCodeModeTool()에 대한 직접 링크

Tool만 필요하고 지침을 별도로 관리하려면 createCodeModeTool()을 사용하세요. 대부분의 Agent는 Tool과 일치하는 지침을 함께 유지할 수 있도록 createCodeMode()을 사용해야 합니다.

src/mastra/tools/code-mode-tool.ts
import { createCodeModeTool } from '@mastra/core/tools'
import { LocalSandbox } from '@mastra/core/workspace'

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