Tool

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

파일 기반 규칙에 대해서는 이 페이지를 사용하십시오. Tool 스키마, 실행 옵션, 출력 형성 및 승인 옵션은 다음을 참조하세요.createTool() reference.

빠른 시작

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

src/mastra/agents/weather/tools/get_weather.ts

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() 참조를, 승인 흐름은 Tool 승인을 참조하세요.

런타임 경계

Tool 코드는 Agent가 Tool을 호출할 때 앱/서버 런타임에서 실행됩니다. Tool에 파일 시스템 또는 셸 격리가 필요하면 Workspace 또는 Sandbox API를 명시적으로 호출하세요.

구성 우선순위

검색된 Tool은 config.ts의 tools와 병합됩니다. 키가 충돌하면 config.tools가 우선하며 경고가 기록됩니다. config.tools가 함수이면 함수형 Tool을 정적으로 병합할 수 없으므로 검색된 Tool이 경고와 함께 무시됩니다.