ツールの概要

ツールは、エージェントが特定のタスクを実行したり外部情報にアクセスしたりするために呼び出せる関数です。これにより、単なるテキスト生成を超えて、API、データベース、その他のシステムとやり取りできるように、エージェントの能力が拡張されます。

各ツールは通常、次の要素を定義します:

• 入力: ツールの実行に必要な情報（inputSchema で定義され、Zod がよく用いられます）。
• 出力: ツールが返すデータの構造（outputSchema で定義）。
• 実行ロジック: ツールの機能を実行するコード。
• 説明: ツールの役割と使用すべき場面をエージェントが理解するのに役立つテキスト。

ツールの作成

Mastra では、@mastra/core/tools パッケージの createTool 関数を使ってツールを作成します。

import { createTool } from "@mastra/core/tools";
import { z } from "zod";
 
const getWeatherInfo = async (city: string) => {
  // 実際の天気サービスへの API 呼び出しに置き換えてください
  console.log(`Fetching weather for ${city}...`);
  // データ構造の例
  return { temperature: 20, conditions: "Sunny" };
};
 
export const weatherTool = createTool({
  id: "Get Weather Information",
  description: `Fetches the current weather information for a given city`,
  inputSchema: z.object({
    city: z.string().describe("City name"),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ context: { city } }) => {
    console.log("Using tool to fetch weather information for", city);
    return await getWeatherInfo(city);
  },
});

この例では、都市名の入力スキーマ、天気データの出力スキーマ、そしてツールのロジックを含む execute 関数を備えた weatherTool を定義しています。

ツールを作成する際は、説明文は簡潔にまとめ、ツールが「何をするのか」と「いつ使うべきか」に焦点を当て、主要なユースケースを強調してください。技術的な詳細はパラメータスキーマに記述し、わかりやすい名前、明確な説明、デフォルト値の説明を通じて、エージェントがツールを正しく使えるように導きます。

エージェントにツールを追加する

ツールをエージェントで利用できるようにするには、エージェントの定義でツールを設定します。エージェントのシステムプロンプトに、利用可能なツールとその概要を記載すると、ツールの活用が向上することもあります。詳しい手順や例は、Using Tools and MCP with Agents のガイドをご覧ください。

ツールスキーマの互換性レイヤー

モデルによってスキーマの解釈は異なります。特定のスキーマプロパティが渡されるとエラーになるものもあれば、無視してもエラーを出さないものもあります。Mastra はツールスキーマに互換性レイヤーを追加し、異なるモデルプロバイダー間でツールが一貫して動作し、スキーマの制約が順守されるようにします。

このレイヤーを適用しているプロバイダーの例:

• Google Gemini & Anthropic: 非対応のスキーマプロパティを削除し、関連する制約をツールの説明に追記します。
• OpenAI（推論モデルを含む）: 無視される／非対応のスキーマフィールドを削除または調整し、エージェントのガイダンスとなる説明を追加します。
• DeepSeek & Meta: 同様の互換性ロジックを適用し、スキーマ整合性とツールの利用性を確保します。

このアプローチにより、カスタムツールと MCP ツールのいずれにおいても、より信頼性が高くモデル非依存なツール利用が可能になります。

ローカルでツールをテストする

ツールを実行してテストする方法は2つあります。

import { RuntimeContext } from "@mastra/core/runtime-context";
import { testTool } from "./mastra/tools/test-tool";
 
const runtimeContext = new RuntimeContext();
 
const result = await testTool.execute({
  context: {
    value: "foo"
  },
  runtimeContext
});
 
console.log(result);

npx tsx src/test-tool.ts