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

# Tool

파일 기반 Agent는 다음에서 Tool을 검색합니다.`.ts`그리고`.js`파일 바로 아래에`tools/`예배 규칙서. 발견된 각 파일은 빌드 시 가져오며, 파일은 기본적으로[`createTool()`](https://mastra.zisheng.pro/ko/reference/tools/create-tool)확장자가 없는 파일 이름은 Model이 호출할 수 있는 Tool 키가 됩니다.

파일 기반 규칙에 대해서는 이 페이지를 사용하십시오. Tool 스키마, 실행 옵션, 출력 형성 및 승인 옵션은 다음을 참조하세요.[`createTool()` reference](https://mastra.zisheng.pro/ko/reference/tools/create-tool).

## 빠른 시작

`tools/` 아래에 파일당 하나의 Tool을 배치하세요. 이 파일은 Agent에 `get_weather`로 노출됩니다.

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

export default createTool({
  id: 'get_weather',
  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' }
  },
})
```

## Tool 정리

Tool당 하나의 파일을 사용하십시오. Model이 수행해야 하는 작업 뒤에 파일 이름을 지정합니다.

- `get_weather.ts`, `search_docs.ts`, `create_ticket.ts`와 같은 이름을 사용하세요.
- `helper.ts`, `api.ts`, `utils.ts`와 같은 모호한 이름은 피하세요.
- `*.test.ts` 또는 `*.spec.ts`와 같이 Tool 옆에 테스트를 배치하세요. 검색 과정에서는 해당 파일을 무시합니다.
- 공유 헬퍼 코드는 `tools/` 외부나 `tools/` 아래에서 검색 대상 확장자와 일치하지 않는 파일에 두세요. 중첩된 디렉터리는 Tool로 검색되지 않으므로 하위 폴더 대신 `calendar_create_event.ts`와 `calendar_list_events.ts`처럼 명확한 파일 이름 접두사를 사용하여 관련 Tool을 그룹화하세요.

## Tool 옵션

파일 기반 규칙은 Tool의 위치와 등록 방법만 제어합니다. Tool API는 여전히 다음에서 제공됩니다.`createTool()`:

- `description`을 사용하여 Model에 Tool을 호출할 시점을 알려주세요.
- 구조화된 입력과 출력에는 `inputSchema`와 `outputSchema`를 사용하세요.
- Model에 `execute`가 반환한 원시 값과 다른 형태를 보여줘야 하면 `toModelOutput`을 사용하세요.
- 실행 전에 사람의 확인이 필요한 Tool에는 `requireApproval`을 사용하세요. 모든 옵션은 [`createTool()` 참조](https://mastra.zisheng.pro/ko/reference/tools/create-tool)를, 승인 흐름은 [Tool 승인](https://mastra.zisheng.pro/ko/docs/harness/agent-controller)을 참조하세요.

## 런타임 경계

Tool 코드는 Agent가 Tool을 호출할 때 앱/서버 런타임에서 실행됩니다. Tool에 파일 시스템 또는 셸 격리가 필요하면 [Workspace](https://mastra.zisheng.pro/ko/reference/file-based-agents/workspace) 또는 Sandbox API를 명시적으로 호출하세요.

## 구성 우선순위

검색된 Tool은 [`config.ts`](https://mastra.zisheng.pro/ko/reference/file-based-agents/config)의 `tools`와 병합됩니다. 키가 충돌하면 `config.tools`가 우선하며 경고가 기록됩니다. `config.tools`가 함수이면 함수형 Tool을 정적으로 병합할 수 없으므로 검색된 Tool이 경고와 함께 무시됩니다.