Tools

檔案式 Agent 會從其 tools/ 目錄正下方的 .ts 和 .js 檔案探索 Tools。每個探索到的檔案都會在建置時匯入；該檔案必須預設匯出 createTool() 的結果，而不含副檔名的檔案名稱會成為模型可呼叫的 Tool key。

本頁說明檔案式慣例。如需了解 Tool schema、執行選項、輸出塑形及審批選項，請參閱 createTool() 參考資料。

快速開始

在 tools/ 下每個檔案放置一個 Tool。此檔案會以 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' }
  },
})

組織 Tools

每個 Tool 使用一個檔案。檔案名稱應反映模型要執行的操作：

• 使用 get_weather.ts、search_docs.ts 或 create_ticket.ts。
• 避免使用 helper.ts、api.ts 或 utils.ts 等含糊名稱。
• 將測試以 *.test.ts 或 *.spec.ts 的名稱與 Tool 放在一起。探索程序會忽略這些檔案。
• 將共用 helper 程式碼放在 tools/ 以外，或放在 tools/ 下副檔名不符合探索條件的檔案中。

由於巢狀目錄不會被探索為 Tools，請使用清晰的檔案名稱前綴（例如 calendar_create_event.ts 和 calendar_list_events.ts）為相關 Tools 分組，而不要使用子資料夾。

Tool 選項

檔案式慣例只控制 Tool 的所在位置及註冊方式。Tool API 仍由 createTool() 提供：

• 使用 description 告訴模型何時呼叫 Tool。
• 使用 inputSchema 和 outputSchema 定義結構化輸入與輸出。
• 當模型應看到與 execute 傳回的原始值不同的結構時，請使用 toModelOutput。
• 當 Tool 在執行前需要人手確認時，請使用 requireApproval。

如需所有選項，請參閱 createTool() 參考資料；如需審批流程，請參閱 Tool 審批。

執行階段邊界

Agent 呼叫 Tool 時，Tool 程式碼會在你的應用程式／伺服器執行階段中運行。如 Tool 需要檔案系統或 shell 隔離，請明確呼叫 Workspace 或 Sandbox API。

與 config 的優先次序

探索到的 Tools 會與 config.ts 中的所有 tools 合併。如 key 發生衝突，系統會優先採用 config.tools 並記錄警告。

如 config.tools 是函式，探索到的 Tools 會被忽略並記錄警告，因為函式值 Tools 無法靜態合併。