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

# 생성Tool()

그만큼`createTool()`기능은 Mastra Agent가 실행할 수 있는 사용자 정의 Tool을 정의하는 데 사용됩니다. Tool은 Agent가 외부 시스템과 상호 작용하거나 계산을 수행할 수 있도록 하여 Agent의 기능을 확장합니다. 특정 데이터에 액세스할 수도 있습니다.

## 사용예

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Get the current weather for a location',
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
})
```

첫 번째 `execute` 매개변수는 `inputSchema`에서 검증된 값입니다. `{ location }` 예시처럼 함수 시그니처에서 스키마 필드를 직접 구조 분해하세요. 선택적인 두 번째 매개변수에는 실행 컨텍스트가 포함됩니다.

## 매개변수

**id** (`string`): Tool의 고유 식별자입니다.

**description** (`string`): Tool이 수행하는 작업에 대한 설명입니다. Agent는 이 설명을 사용하여 Tool을 언제 사용할지 결정합니다.

**inputSchema** (`StandardJSONSchemaV1`): Tool의 execute 함수에 필요한 입력 매개변수를 정의하는 Standard JSON Schema입니다.

**outputSchema** (`StandardJSONSchemaV1`): Tool의 execute 함수에서 예상되는 출력 구조를 정의하는 Standard JSON Schema입니다.

**strict** (`boolean`): true이면 Mastra가 이를 지원하는 Model 어댑터에서 엄격한 Tool 입력 생성을 활성화합니다. 이를 통해 지원되는 Provider가 Tool 스키마에 더 잘 맞는 인수를 반환할 수 있습니다.

**toModelOutput** (`(output: TSchemaOut) => unknown`): Tool의 execute 출력을 Model로 다시 보내기 전에 변환하는 선택적 함수입니다. 애플리케이션 코드에는 전체 원시 출력을 유지하면서 text, json 또는 content 형태의 출력(이미지/파일 같은 멀티모달 부분 포함)을 Model에 반환할 때 사용하세요.

**transform** (`ToolPayloadTransform`): Tool 페이로드가 런타임을 떠나 표시 스트림이나 사용자에게 보이는 트랜스크립트 메시지로 전달되기 전에 적용되는 선택적 대상 인식 변환입니다. input, inputDelta, output, error, approval, suspend, resume 등의 단계에 대해 display 및 transcript 변환을 구성하세요.

**suspendSchema** (`StandardJSONSchemaV1`): suspend()에 전달되는 페이로드의 구조를 정의하는 Standard JSON Schema입니다. Tool이 실행을 일시 중단하면 이 페이로드가 클라이언트에 반환됩니다.

**resumeSchema** (`StandardJSONSchemaV1`): Tool이 재개될 때 예상되는 resumeData 구조를 정의하는 Standard JSON Schema입니다. autoResumeSuspendedTools가 활성화된 경우 Agent가 사용자 메시지에서 데이터를 추출하는 데 사용합니다.

**requireApproval** (`boolean`): true이면 Tool을 실행하기 전에 명시적인 승인이 필요합니다. Agent는 tool-call-approval 청크를 방출하고 승인되거나 거부될 때까지 일시 중지합니다.

**mcp** (`MCPToolProperties`): Model Context Protocol을 통해 노출되는 Tool의 MCP 전용 속성입니다. annotations(title, readOnlyHint, destructiveHint, idempotentHint, openWorldHint 같은 Tool 동작 힌트)와 \_meta(MCP 클라이언트로 그대로 전달되는 임의의 메타데이터)를 포함합니다.

**requestContextSchema** (`StandardJSONSchemaV1`): 요청 컨텍스트 값을 검증하기 위한 Standard JSON Schema입니다. 제공하면 execute()가 실행되기 전에 컨텍스트를 검증하고, 검증에 실패하면 오류 객체를 반환합니다.

**providerOptions** (`Record<string, Record<string, unknown>>`): 이 Tool을 사용할 때 Model에 전달되는 Provider별 옵션입니다. 키는 anthropic 또는 openai 같은 Provider 이름이고, 값은 Provider별 구성 객체입니다.

**inputExamples** (`Array<{ input: Record<string, unknown> }>`): 지원되는 Model Provider가 입력 예시로 사용할 수 있는 유효한 Tool 입력의 예시입니다.

**background** (`ToolBackgroundConfig`): 이 Tool의 백그라운드 작업 구성입니다. 활성화하면 Agent 대화가 계속되는 동안 Tool을 백그라운드에서 실행할 수 있습니다.

**execute** (`function`): Tool의 로직을 포함하는 함수입니다. 일반적인 사용자 정의 Tool은 대개 execute를 제공하지만, 다른 위치에서 실행되거나 조정되는 Tool 정의에서는 생략할 수 있도록 타입이 허용합니다. 두 매개변수를 받습니다. 첫 번째는 inputSchema를 기반으로 검증된 입력 데이터이고, 두 번째는 requestContext, abortSignal 및 기타 실행 메타데이터를 포함하는 실행 컨텍스트 객체입니다.

**execute.input** (`z.infer<TInput>`): inputSchema를 기반으로 검증된 입력 데이터

**execute.context** (`ToolExecutionContext`): 메타데이터를 포함하는 선택적 실행 컨텍스트

**execute.context.requestContext** (`RequestContext`): 공유 상태와 종속성에 액세스하기 위한 요청 컨텍스트

**execute.context.abortSignal** (`AbortSignal`): Tool 실행을 중단하기 위한 신호

**execute.context.agent** (`AgentToolExecutionContext`): Agent별 컨텍스트로, Agent가 Tool을 실행할 때 사용할 수 있습니다.

**execute.context.workflow** (`WorkflowToolExecutionContext`): Workflow별 컨텍스트(state, setState, suspend 등)

**execute.context.mcp** (`MCPToolExecutionContext`): MCP별 컨텍스트(elicitation 등)

**execute.context.observe** (`ToolObserve`): Tool의 execute 함수 내부에서 하위 span과 구조화된 로그를 기록하기 위한 Observability 헬퍼입니다. 항상 제공되며, 활성화된 tracing 컨텍스트가 없으면 span은 함수를 직접 실행하고 log는 아무 작업도 하지 않습니다.

**onInputStart** (`function`): Tool 호출 입력 스트리밍이 시작될 때 호출되는 선택적 콜백입니다. 시그니처: (options: ToolCallOptions) => void | PromiseLike\<void>.

**onInputDelta** (`function`): 입력 텍스트가 스트리밍될 때 각 증분 청크마다 호출되는 선택적 콜백입니다. 시그니처: ({ inputTextDelta, ...options }: { inputTextDelta: string } & ToolCallOptions) => void | PromiseLike\<void>.

**onInputAvailable** (`function`): 전체 Tool 입력을 사용할 수 있고 파싱이 완료되었을 때 호출되는 선택적 콜백입니다. 시그니처: ({ input, ...options }: { input: TSchemaIn } & ToolCallOptions) => void | PromiseLike\<void>.

**onOutput** (`function`): Tool이 성공적으로 실행되어 출력을 반환한 후 호출되는 선택적 콜백입니다. 시그니처: ({ output, toolName, ...options }: { output: TSchemaOut; toolName: string } & Omit\<ToolCallOptions, 'messages'>) => void | PromiseLike\<void>.

런타임에 채워지는 `mastra` 및 `mcpMetadata` 필드는 소스 타입에 나타나지만 Mastra 또는 MCP 어댑터에서 설정합니다. 일반적인 `createTool()` 사용 시에는 이를 구성할 필요가 없습니다.

## 보고

`createTool()` 함수는 `Tool` 객체를 반환합니다.

**Tool** (`object`): 정의된 Tool을 나타내며 Agent에 추가할 준비가 된 객체입니다.

## 스키마 정의

[Standard JSON Schema](https://standardschema.dev/json-schema)를 지원하는 모든 라이브러리로 Tool의 `inputSchema` 및 `outputSchema`를 정의할 수 있습니다. 여기에는 [Zod](https://zod.dev/), [Valibot](https://valibot.dev/), [ArkType](https://arktype.io/) 같은 라이브러리가 포함됩니다.

**Zod**:

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Fetches weather for a location',
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return { location, temperatureCelsius: 21, conditions: 'sunny' }
  },
})
```

**Valibot**:

```typescript
import { createTool } from '@mastra/core/tools'
import * as v from 'valibot'
import { toStandardJsonSchema } from '@valibot/to-json-schema'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Fetches weather for a location',
  inputSchema: toStandardJsonSchema(
    v.object({
      location: v.string(),
    }),
  ),
  outputSchema: toStandardJsonSchema(
    v.object({
      location: v.string(),
      temperatureCelsius: v.number(),
      conditions: v.string(),
    }),
  ),
  execute: async ({ location }) => {
    return { location, temperatureCelsius: 21, conditions: 'sunny' }
  },
})
```

**ArkType**:

```typescript
import { createTool } from '@mastra/core/tools'
import { type } from 'arktype'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Fetches weather for a location',
  inputSchema: type({
    location: 'string',
  }),
  outputSchema: type({
    location: 'string',
    temperatureCelsius: 'number',
    conditions: 'string',
  }),
  execute: async ({ location }) => {
    return { location, temperatureCelsius: 21, conditions: 'sunny' }
  },
})
```

## 엄격한 Tool 입력의 예

Mastra가 지원되는 Model Provider에 Tool 스키마와 정확히 일치하는 Tool 인수를 생성하도록 요청하게 하려면 `strict: true`를 설정하세요.

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Get the current weather for a location',
  strict: true,
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
})
```

Mastra는 엄격한 Tool 호출을 지원하는 Model 어댑터에 `strict: true`를 전달합니다. 엄격한 Tool 호출을 지원하지 않는 어댑터에서는 Mastra가 이 옵션을 무시합니다.

## 예`toModelOutput`

Tool이 앱에는 풍부한 내부 데이터를 반환하되 Model에는 단순화된 값이나 멀티모달 콘텐츠를 전달해야 할 때 `toModelOutput`을 사용하세요.

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Get the current weather for a location',
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
    radarImageUrl: z.string().url(),
  }),
  execute: async ({ location }) => ({
    location,
    temperatureCelsius: 21,
    conditions: 'sunny',
    radarImageUrl: 'https://example.com/radar/seattle.png',
  }),
  toModelOutput: output => {
    return {
      type: 'content',
      value: [
        {
          type: 'text',
          text: `${output.location}: ${output.temperatureCelsius}°C and ${output.conditions}`,
        },
        { type: 'image-url', url: output.radarImageUrl },
      ],
    }
  },
})
```

Tool은 여전히 전체 `execute` 결과를 애플리케이션에 반환하지만, Model은 변환된 `toModelOutput` 값을 받습니다. `toModelOutput`다음을 반환할 수 있습니다:

- `type: 'text'`
- `type: 'json'`
- `text`, `image-url`, `image-data`, `file-url`, `file-data`, `file-id`, `image-file-id` 또는 `custom` 같은 부분으로 구성된 `type: 'content'`

## 예`transform`

Tool이 런타임 동작을 위해 원시 입력이나 출력을 유지하되 표시 스트림이나 대화 기록 메시지에는 더 작거나 안전한 형태를 전달해야 할 때 `transform`을 사용하세요.

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const customerTool = createTool({
  id: 'lookup-customer',
  description: 'Looks up a customer',
  inputSchema: z.object({
    customerId: z.string(),
    internalPath: z.string(),
  }),
  outputSchema: z.object({
    displayName: z.string(),
    apiKey: z.string(),
    debugScore: z.number(),
  }),
  execute: async () => {
    return {
      displayName: 'Acme',
      apiKey: 'secret-value',
      debugScore: 0.97,
    }
  },
  transform: {
    display: {
      input: ({ input }) => ({ customerId: input?.customerId }),
      output: ({ output }) => ({ displayName: output?.displayName }),
      error: () => ({ message: 'Customer lookup failed' }),
    },
    transcript: {
      input: ({ input }) => ({ customerId: input?.customerId }),
      output: ({ output }) => ({ displayName: output?.displayName }),
      error: () => ({ message: 'Customer lookup failed' }),
    },
  },
})
```

Tool은 여전히 원시 `inputSchema` 값을 받고 원시 `execute` 결과를 반환합니다. Mastra는 스트리밍되는 UI 페이로드에 `display` 변환을 적용하고 사용자에게 표시되는 대화 기록 메시지에 `transcript` 변환을 적용합니다.

## MCP 주석의 예

MCP(Model 컨텍스트 프로토콜)를 통해 Tool을 노출할 때 주석을 추가하여 Tool 동작을 설명하고 클라이언트가 Tool을 표시하는 방법을 사용자 지정할 수 있습니다. 이러한 MCP 관련 속성은 다음 아래에 그룹화되어 있습니다.`mcp` property:

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Get the current weather for a location',
  inputSchema: z.object({
    location: z.string().describe('City name or coordinates'),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  // MCP-specific properties
  mcp: {
    // Annotations for client behavior hints
    annotations: {
      title: 'Weather Lookup', // Human-readable display name
      readOnlyHint: true, // Tool doesn't modify environment
      destructiveHint: false, // Tool doesn't perform destructive updates
      idempotentHint: true, // Same args = same result
      openWorldHint: true, // Interacts with external API
    },
    // Custom metadata for client-specific functionality
    _meta: {
      version: '1.0.0',
      category: 'weather',
    },
  },
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
})
```

## Tool 수명주기 후크

Tool은 Tool 실행의 다양한 단계를 모니터링하고 대응할 수 있는 수명 주기 후크를 지원합니다. 이러한 후크는 스트리밍 중 로깅, 분석, 검증 및 실시간 업데이트에 특히 유용합니다.

다음 예에서는 모든 수명 주기 후크가 구성된 Tool을 보여줍니다.

```typescript
import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

export const weatherTool = createTool({
  id: 'weather-tool',
  description: 'Get the current weather for a location',
  inputSchema: z.object({
    location: z.string(),
  }),
  outputSchema: z.object({
    location: z.string(),
    temperatureCelsius: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ location }) => {
    return {
      location,
      temperatureCelsius: 21,
      conditions: 'sunny',
    }
  },
  onInputStart: ({ toolCallId }) => {
    console.log(`Tool call ${toolCallId} input started`)
  },
  onInputDelta: ({ inputTextDelta, toolCallId }) => {
    console.log(`Tool call ${toolCallId} received input chunk: ${inputTextDelta}`)
  },
  onInputAvailable: ({ input, toolCallId }) => {
    console.log(`Tool call ${toolCallId} received location: ${input.location}`)
  },
  onOutput: ({ output, toolCallId, toolName }) => {
    console.log(`Tool ${toolName} call ${toolCallId} returned conditions: ${output.conditions}`)
  },
})
```

### 사용 가능한 후크

#### `onInputStart`

입력 데이터가 수신되기 전에 Tool 호출 입력 스트리밍이 시작될 때 호출됩니다.

```typescript
export const tool = createTool({
  id: 'example-tool',
  description: 'Example tool with hooks',
  onInputStart: ({ toolCallId, messages, abortSignal }) => {
    console.log(`Tool ${toolCallId} input streaming started`)
  },
})
```

#### `onInputDelta`

스트리밍되는 입력 텍스트의 각 증분 청크에 대해 호출됩니다. 실시간 진행률을 표시하거나 부분 JSON을 구문 분석하는 데 유용합니다.

```typescript
export const tool = createTool({
  id: 'example-tool',
  description: 'Example tool with hooks',
  onInputDelta: ({ inputTextDelta, toolCallId, messages, abortSignal }) => {
    console.log(`Received input chunk: ${inputTextDelta}`)
  },
})
```

#### `onInputAvailable`

전체 Tool 입력이 사용 가능하고 구문 분석 및 검증되었을 때 호출됩니다.`inputSchema`.

```typescript
export const tool = createTool({
  id: 'example-tool',
  description: 'Example tool with hooks',
  inputSchema: z.object({
    location: z.string(),
  }),
  onInputAvailable: ({ input, toolCallId, messages, abortSignal }) => {
    console.log(`Tool received complete input:`, input)
    // input is fully typed based on inputSchema
  },
})
```

#### `onOutput`

Tool이 성공적으로 실행되고 출력을 반환한 후에 호출됩니다. 결과 로깅, 후속 조치 트리거 또는 분석에 유용합니다.

```typescript
export const tool = createTool({
  id: 'example-tool',
  description: 'Example tool with hooks',
  outputSchema: z.object({
    result: z.string(),
  }),
  execute: async input => {
    return { result: 'Success' }
  },
  onOutput: ({ output, toolCallId, toolName, abortSignal }) => {
    console.log(`${toolName} execution completed:`, output)
    // output is fully typed based on outputSchema
  },
})
```

### Hook 실행 순서

일반적인 스트리밍 Tool 호출의 경우 후크는 다음 순서로 호출됩니다.

1. **onInputStart**: 입력 스트리밍이 시작됩니다.
2. **onInputDelta**: 청크가 도착하면 여러 번 호출됩니다.
3. **onInput 사용 가능**: 완전한 입력이 구문 분석되고 검증됩니다.
4. Tool**execute** function runs
5. **onOutput**: Tool이 성공적으로 완료되었습니다.

### 후크 매개변수

후크 콜백은 다음과 같은 소스 지원 매개변수 형태를 받습니다.

- `onInputStart`: `toolCallId`, `messages`, `abortSignal` 등의 필드를 포함하는 `ToolCallOptions`를 받습니다.
- `onInputDelta`: `{ inputTextDelta: string } & ToolCallOptions`를 받습니다.
- `onInputAvailable`: `{ input: TSchemaIn } & ToolCallOptions`를 받으며, `input`의 타입은 `inputSchema`에서 지정됩니다.
- `onOutput`: `{ output: TSchemaOut; toolName: string } & Omit<ToolCallOptions, 'messages'>`를 받으며, `output`의 타입은 `outputSchema`에서 지정됩니다. 이 훅은 `messages`를 받지 않습니다.

### 오류 처리

후크 오류는 자동으로 포착되어 기록되지만 Tool 실행이 계속되는 것을 방해하지는 않습니다. 후크에서 오류가 발생하면 콘솔에 기록되지만 Tool 호출은 실패하지 않습니다.

## MCP Tool 주석

MCP(Model Context Protocol)를 통해 Tool을 노출할 때 Tool 동작을 설명하는 주석을 제공할 수 있습니다. 이러한 주석은 OpenAI Apps SDK와 같은 MCP 클라이언트가 Tool을 표시하고 처리하는 방법을 이해하는 데 도움이 됩니다.

MCP 관련 속성은 `annotations`와 `_meta`를 포함하는 `mcp` 속성 아래에 그룹화됩니다.

```typescript
mcp: {
  annotations: { /* behavior hints */ },
  _meta: { /* custom metadata */ },
}
```

### `ToolAnnotations`속성

**title** (`string`): 사람이 읽을 수 있는 Tool 제목입니다. UI 구성 요소에 표시하는 용도로 사용됩니다.

**readOnlyHint** (`boolean`): true이면 Tool은 환경을 수정하지 않습니다. 이 힌트는 Tool이 데이터만 읽고 부작용이 없음을 나타냅니다. 기본값은 false입니다.

**destructiveHint** (`boolean`): true이면 Tool이 환경에 파괴적인 업데이트를 수행할 수 있습니다. false이면 Tool은 추가형 업데이트만 수행합니다. 이 힌트는 클라이언트가 확인이 필요한지 판단하는 데 도움이 됩니다. 기본값은 true입니다.

**idempotentHint** (`boolean`): true이면 같은 인수로 Tool을 반복 호출해도 환경에 추가적인 영향이 없습니다. 이 힌트는 멱등 동작을 나타냅니다. 기본값은 false입니다.

**openWorldHint** (`boolean`): true이면 이 Tool이 외부 엔터티의 '열린 세계'(예: 웹 검색, 외부 API)와 상호 작용할 수 있습니다. false이면 Tool의 도메인이 닫혀 있고 완전히 정의되어 있습니다. 기본값은 true입니다.

이러한 주석은 [MCP 사양](https://spec.modelcontextprotocol.io/specification/2025-03-26/server/tools/#tool-annotations)을 따르며 MCP를 통해 Tool을 나열할 때 그대로 전달됩니다.

## 관련된

- [MCP 개요](https://mastra.zisheng.pro/ko/docs/mcp/overview)
- [Agent와 함께 Tool 사용](https://mastra.zisheng.pro/ko/docs/agents/using-tools)
- [대리인 승인](https://mastra.zisheng.pro/ko/docs/agents/agent-approval)
- [Tool 스트리밍](https://mastra.zisheng.pro/ko/docs/agents/using-tools)
- [요청 컨텍스트](https://mastra.zisheng.pro/ko/docs/server/request-context)