エージェントでのツールの使用

ツールは、エージェントやワークフローから実行できる型付き関数です。各ツールは、入力を定義するスキーマ、ロジックを実装する実行関数、そして必要に応じて設定済みのインテグレーションへのアクセスで構成されます。

Mastra では、エージェントにツールを提供するために次の2つのパターンをサポートしています:

直接割り当て: 初期化時に利用可能な静的なツール
関数ベース: 実行時のコンテキストに基づいて動的に解決されるツール

ツールの作成

ツールを作成する基本的な例を示します：

src/mastra/tools/weatherInfo.ts


import { createTool } from "@mastra/core/tools";
import { z } from "zod";
 
export const weatherInfo = createTool({
  id: "天気情報の取得",
  inputSchema: z.object({
    city: z.string(),
  }),
  description: `指定した都市の現在の天気情報を取得します`,
  execute: async ({ context: { city } }) => {
    // ツールのロジックをここに記述（例：API 呼び出し）
    console.log("ツールを使用して天気情報を取得中:", city);
    return { temperature: 20, conditions: "晴れ" }; // 例の戻り値
  },
});

ツールの作成や設計の詳細は、Tools Overviewをご覧ください。

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

ツールをエージェントで利用できるようにするには、エージェントの設定の tools プロパティに追加します。

src/mastra/agents/weatherAgent.ts


import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { weatherInfo } from "../tools/weatherInfo";
 
export const weatherAgent = new Agent({
  name: "Weather Agent",
  instructions:
    "あなたは現在の天気情報を提供する頼りになるアシスタントです。天気について尋ねられたら、weather information ツールを使ってデータを取得してください。",
  model: openai("gpt-4o-mini"),
  tools: {
    weatherInfo,
  },
});

エージェントを呼び出すと、エージェントは自身の指示とユーザーのプロンプトに基づいて、設定済みのツールを使用するかどうかを判断できるようになりました。

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

Model Context Protocol (MCP) は、AI モデルが外部のツールやリソースを発見し、やり取りできるようにする標準化された方法を提供します。サードパーティ製のツールを利用するために、Mastra エージェントを MCP サーバーに接続できます。

MCP の概念や MCP クライアント／サーバーのセットアップ方法の詳細は、MCP の概要を参照してください。

インストール

まず、Mastra MCP パッケージをインストールします。


npm install @mastra/mcp@latest


pnpm add @mastra/mcp@latest


yarn add @mastra/mcp@latest


bun add @mastra/mcp@latest

MCP ツールの使い方

選べる MCP サーバーのレジストリが多数あるため、MCP サーバー探しに役立つ MCP Registry Registry を用意しました。

エージェントで使いたいサーバーが見つかったら、Mastra の MCPClient をインポートし、サーバー設定を追加します。

src/mastra/mcp.ts


import { MCPClient } from "@mastra/mcp";
 
// MCPClient を構成してサーバーに接続します
export const mcp = new MCPClient({
  servers: {
    filesystem: {
      command: "npx",
      args: [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Downloads",
      ],
    },
  },
});

次に、エージェントをサーバーツールに接続します。

src/mastra/agents/mcpAgent.ts


import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { mcp } from "../mcp";
 
// MCP クライアントのツールを追加してエージェントを作成する
const agent = new Agent({
  name: "MCP ツール対応エージェント",
  instructions: "接続中の MCP サーバーのツールを使用できます。",
  model: openai("gpt-4o-mini"),
  tools: await mcp.getTools(),
});

同じリポジトリ内で接続先となる MCP サーバーを利用するエージェントを作成する場合は、競合状態を防ぐため、必ず関数ベースのツールを使用してください。

src/mastra/agents/selfReferencingAgent.ts


import { Agent } from "@mastra/core/agent";
import { MCPServer } from "@mastra/mcp";
import { MCPClient } from "@mastra/mcp";
import { openai } from "@ai-sdk/openai";
 
const myAgent = new Agent({
  name: "My Agent",
  description: "HTTP MCP サーバーのツールを利用できるエージェント",
  instructions: "リモート計算ツールを使用できます。",
  model: openai("gpt-4o-mini"),
  tools: async () => {
    // ツールは初期化時ではなく、必要になったときに読み込まれます
    const mcpClient = new MCPClient({
      servers: {
        myServer: {
          url: new URL("http://localhost:4111/api/mcp/mcpServer/mcp"),
        },
      },
    });
    return await mcpClient.getTools();
  },
});
 
// サーバー起動後にツールが読み込まれるため、これは動作します
export const mcpServer = new MCPServer({
  name: "My MCP Server",
  agents: {
    myAgent
  },
});

MCPClient の設定方法や、静的・動的な MCP サーバー構成の違いの詳細については、MCP Overview を参照してください。

MCP リソースへのアクセス

ツールに加えて、MCP サーバーはリソース（アプリケーションで取得して利用できるデータやコンテンツ）も公開できます。

src/mastra/resources.ts


import { mcp } from "./mcp";
 
// 接続中のすべての MCP サーバーからリソースを取得する
const resources = await mcp.getResources();
 
// 特定のサーバーのリソースにアクセスする
if (resources.filesystem) {
  const resource = resources.filesystem.find(
    (r) => r.uri === "filesystem://Downloads",
  );
  console.log(`リソース: ${resource?.name}`);
}

各リソースには URI、名前、説明、MIME タイプがあります。getResources() メソッドはエラーを適切に処理し、サーバーが障害を起こしたりリソースをサポートしていない場合は結果から除外します。

MCPプロンプトへのアクセス

MCPサーバーは、エージェント向けの構造化メッセージテンプレートや会話コンテキストを表すプロンプトを公開することもできます。

プロンプト一覧

src/mastra/prompts.ts


import { mcp } from "./mcp";
 
// 接続中のすべての MCP サーバーからプロンプトを取得する
const prompts = await mcp.prompts.list();
 
// 特定のサーバーのプロンプトにアクセスする
if (prompts.weather) {
  const prompt = prompts.weather.find(
    (p) => p.name === "current"
  );
  console.log(`Prompt: ${prompt?.name}`);
}

各プロンプトには、名前、説明、（任意）でバージョンがあります。

プロンプトとそのメッセージの取得

src/mastra/prompts.ts


const { prompt, messages } = await mcp.prompts.get({ serverName: "weather", name: "current" });
console.log(prompt);    // { name: "current", version: "v1", ... }
console.log(messages);  // [ { role: "assistant", content: { type: "text", text: "..." } }, ... ]

MCPServer を介してエージェントをツールとして公開する

MCP サーバー由来のツールを使うだけでなく、Mastra の MCPServer を利用すると、Mastra のエージェント自体を MCP 互換クライアント向けのツールとして公開できます。

Agent インスタンスを MCPServer の設定に渡すと:

自動的に呼び出し可能なツールに変換されます。
ツール名は ask_<agentKey> となり、<agentKey> は MCPServer の agents 設定にエージェントを追加した際に使用した識別子です。
エージェントの description プロパティ（空でない文字列である必要があります）が、ツールの説明の生成に使用されます。

これにより、他の AI モデルや MCP クライアントは、通常は「質問する」形で、標準的なツールと同様に Mastra のエージェントと対話できるようになります。

エージェントを含む MCPServer の設定例:

src/mastra/mcp.ts


import { Agent } from "@mastra/core/agent";
import { MCPServer } from "@mastra/mcp";
import { openai } from "@ai-sdk/openai";
import { weatherInfo } from "../tools/weatherInfo";
import { generalHelper } from "../agents/generalHelper";
 
const server = new MCPServer({
  name: "エージェントツール搭載のカスタムサーバー",
  version: "1.0.0",
  tools: {
    weatherInfo,
  },
  agents: { generalHelper }, // 「ask_generalHelper」ツールを公開
});

エージェントを MCPServer でツールとして正しく変換するには、コンストラクターの設定で description プロパティを空でない文字列に設定する必要があります。description が未設定または空の場合、初期化時に MCPServer はエラーをスローします。

MCPServer のセットアップおよび設定の詳細は、MCPServer リファレンスドキュメントを参照してください。

エージェントでのツールの使用

Mastra では、エージェントにツールを提供するために次の2つのパターンをサポートしています:

直接割り当て: 初期化時に利用可能な静的なツール
関数ベース: 実行時のコンテキストに基づいて動的に解決されるツール

ツールの作成

ツールを作成する基本的な例を示します：

src/mastra/tools/weatherInfo.ts


import { createTool } from "@mastra/core/tools";
import { z } from "zod";
 
export const weatherInfo = createTool({
  id: "天気情報の取得",
  inputSchema: z.object({
    city: z.string(),
  }),
  description: `指定した都市の現在の天気情報を取得します`,
  execute: async ({ context: { city } }) => {
    // ツールのロジックをここに記述（例：API 呼び出し）
    console.log("ツールを使用して天気情報を取得中:", city);
    return { temperature: 20, conditions: "晴れ" }; // 例の戻り値
  },
});

ツールの作成や設計の詳細は、Tools Overviewをご覧ください。

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

ツールをエージェントで利用できるようにするには、エージェントの設定の tools プロパティに追加します。

src/mastra/agents/weatherAgent.ts


import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { weatherInfo } from "../tools/weatherInfo";
 
export const weatherAgent = new Agent({
  name: "Weather Agent",
  instructions:
    "あなたは現在の天気情報を提供する頼りになるアシスタントです。天気について尋ねられたら、weather information ツールを使ってデータを取得してください。",
  model: openai("gpt-4o-mini"),
  tools: {
    weatherInfo,
  },
});

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

MCP の概念や MCP クライアント／サーバーのセットアップ方法の詳細は、MCP の概要を参照してください。

インストール

まず、Mastra MCP パッケージをインストールします。


npm install @mastra/mcp@latest


pnpm add @mastra/mcp@latest


yarn add @mastra/mcp@latest


bun add @mastra/mcp@latest

MCP ツールの使い方

選べる MCP サーバーのレジストリが多数あるため、MCP サーバー探しに役立つ MCP Registry Registry を用意しました。

エージェントで使いたいサーバーが見つかったら、Mastra の MCPClient をインポートし、サーバー設定を追加します。

src/mastra/mcp.ts


import { MCPClient } from "@mastra/mcp";
 
// MCPClient を構成してサーバーに接続します
export const mcp = new MCPClient({
  servers: {
    filesystem: {
      command: "npx",
      args: [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/username/Downloads",
      ],
    },
  },
});

次に、エージェントをサーバーツールに接続します。

src/mastra/agents/mcpAgent.ts


import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { mcp } from "../mcp";
 
// MCP クライアントのツールを追加してエージェントを作成する
const agent = new Agent({
  name: "MCP ツール対応エージェント",
  instructions: "接続中の MCP サーバーのツールを使用できます。",
  model: openai("gpt-4o-mini"),
  tools: await mcp.getTools(),
});

src/mastra/agents/selfReferencingAgent.ts


import { Agent } from "@mastra/core/agent";
import { MCPServer } from "@mastra/mcp";
import { MCPClient } from "@mastra/mcp";
import { openai } from "@ai-sdk/openai";
 
const myAgent = new Agent({
  name: "My Agent",
  description: "HTTP MCP サーバーのツールを利用できるエージェント",
  instructions: "リモート計算ツールを使用できます。",
  model: openai("gpt-4o-mini"),
  tools: async () => {
    // ツールは初期化時ではなく、必要になったときに読み込まれます
    const mcpClient = new MCPClient({
      servers: {
        myServer: {
          url: new URL("http://localhost:4111/api/mcp/mcpServer/mcp"),
        },
      },
    });
    return await mcpClient.getTools();
  },
});
 
// サーバー起動後にツールが読み込まれるため、これは動作します
export const mcpServer = new MCPServer({
  name: "My MCP Server",
  agents: {
    myAgent
  },
});

MCPClient の設定方法や、静的・動的な MCP サーバー構成の違いの詳細については、MCP Overview を参照してください。

MCP リソースへのアクセス

ツールに加えて、MCP サーバーはリソース（アプリケーションで取得して利用できるデータやコンテンツ）も公開できます。

src/mastra/resources.ts


import { mcp } from "./mcp";
 
// 接続中のすべての MCP サーバーからリソースを取得する
const resources = await mcp.getResources();
 
// 特定のサーバーのリソースにアクセスする
if (resources.filesystem) {
  const resource = resources.filesystem.find(
    (r) => r.uri === "filesystem://Downloads",
  );
  console.log(`リソース: ${resource?.name}`);
}

MCPプロンプトへのアクセス

MCPサーバーは、エージェント向けの構造化メッセージテンプレートや会話コンテキストを表すプロンプトを公開することもできます。

プロンプト一覧

src/mastra/prompts.ts


import { mcp } from "./mcp";
 
// 接続中のすべての MCP サーバーからプロンプトを取得する
const prompts = await mcp.prompts.list();
 
// 特定のサーバーのプロンプトにアクセスする
if (prompts.weather) {
  const prompt = prompts.weather.find(
    (p) => p.name === "current"
  );
  console.log(`Prompt: ${prompt?.name}`);
}

各プロンプトには、名前、説明、（任意）でバージョンがあります。

プロンプトとそのメッセージの取得

src/mastra/prompts.ts


const { prompt, messages } = await mcp.prompts.get({ serverName: "weather", name: "current" });
console.log(prompt);    // { name: "current", version: "v1", ... }
console.log(messages);  // [ { role: "assistant", content: { type: "text", text: "..." } }, ... ]

MCPServer を介してエージェントをツールとして公開する

Agent インスタンスを MCPServer の設定に渡すと:

自動的に呼び出し可能なツールに変換されます。
ツール名は ask_<agentKey> となり、<agentKey> は MCPServer の agents 設定にエージェントを追加した際に使用した識別子です。
エージェントの description プロパティ（空でない文字列である必要があります）が、ツールの説明の生成に使用されます。

エージェントを含む MCPServer の設定例:

src/mastra/mcp.ts


import { Agent } from "@mastra/core/agent";
import { MCPServer } from "@mastra/mcp";
import { openai } from "@ai-sdk/openai";
import { weatherInfo } from "../tools/weatherInfo";
import { generalHelper } from "../agents/generalHelper";
 
const server = new MCPServer({
  name: "エージェントツール搭載のカスタムサーバー",
  version: "1.0.0",
  tools: {
    weatherInfo,
  },
  agents: { generalHelper }, // 「ask_generalHelper」ツールを公開
});

MCPServer のセットアップおよび設定の詳細は、MCPServer リファレンスドキュメントを参照してください。