Tools

ファイルベース Agent は、tools/ ディレクトリの直下にある .ts ファイルと .js ファイルから Tool を検出します。検出された各ファイルはビルド時に import されます。ファイルは createTool() の結果を default export する必要があり、拡張子を除いたファイル名が Model から呼び出せる Tool Key になります。

ファイルベースの規約については、このページを参照してください。Tool の Schema、実行オプション、出力形式の調整、承認オプションについては、createTool() リファレンスを参照してください。

クイックスタート

tools/ 配下に Tool ごとのファイルを1つずつ配置します。このファイルは get_weather として Agent に公開されます。

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 ごとに1つのファイルを使用します。Model に実行させる Action に合わせてファイル名を付けてください。

• get_weather.ts、search_docs.ts、create_ticket.ts のような名前を使用します。
• helper.ts、api.ts、utils.ts のような曖昧な名前は避けます。
• テストは *.test.ts または *.spec.ts として Tool の隣に配置します。これらのファイルは検出時に無視されます。
• 共有 Helper コードは tools/ の外、または tools/ 配下でも検出対象の拡張子に一致しないファイルに配置します。

ネストされたディレクトリは Tool として検出されないため、関連する Tool はサブフォルダーではなく、calendar_create_event.ts や calendar_list_events.ts のように、明確なファイル名 Prefix でグループ化してください。

Tool のオプション

ファイルベースの規約が制御するのは、Tool の配置場所と登録方法だけです。Tool API は引き続き createTool() によって提供されます。

• Model に Tool を呼び出すタイミングを伝えるには、description を使用します。
• 構造化された入力と出力には、inputSchema と outputSchema を使用します。
• execute が返す未加工の値とは異なる形式を Model に提示する場合は、toModelOutput を使用します。
• Tool の実行前に人間による確認が必要な場合は、requireApproval を使用します。

すべてのオプションについては createTool() リファレンスを、承認フローについては Tool の承認を参照してください。

Runtime の境界

Agent が Tool を呼び出すと、Tool のコードはアプリケーション／Server の Runtime で実行されます。Tool で File System や Shell の分離が必要な場合は、Workspaceまたは Sandbox API を明示的に呼び出してください。

config との優先順位

検出された Tool は、config.ts 内の tools とマージされます。Key が重複した場合は config.tools が優先され、警告がログに記録されます。

config.tools が関数の場合、関数値の Tool は静的にマージできないため、検出された Tool は警告とともに無視されます。