Mastra とは？AI開発を加速するTSフレームワーク

こんにちは、スクーティー代表のかけやと申します。
​
弊社は生成AIを強みとするベトナムオフショア開発・ラボ型開発や、生成AIコンサルティングなどのサービスを提供しており、最近はありがたいことに生成AIと連携したシステム開発のご依頼を数多く頂いています。

Mastra は、AIを活用したアプリケーションや機能を開発するための、TypeScript製のフレームワークです。アプリケーション開発に必要な土台となる機能がまとまった「フレームワーク」を使うことで、AIエージェント、ワークフロー、RAG（検索拡張生成）など、最新のAI技術を活用した機能を、より少ないコードで、より簡単に開発できます。

従来の開発手法では、AIモデルとの連携や、複雑な処理フローの構築、外部サービスとの連携など、多くの手間と時間が必要でした。Mastraは、これらの課題を解決し、開発者がより創造的な開発に集中できるよう支援します。具体的には、エージェントが自律的にタスクを実行したり、複数の処理をワークフローで自動化したり、RAGによってユーザーの質問に関連する情報を検索して回答を生成したりできます。

この記事では、Mastraの概要、インストール方法、主要機能の使い方、開発環境の構築、さらに応用的な活用方法まで、Mastraの全てを詳細に解説します。

Mastraとは？：AI開発を効率化するフレームワーク

Mastraの概要：AI開発の課題を解決

Mastraのトップページには、Mastraが提供する主要機能（Agents, Workflows, RAG, Integrations, Evals）が簡潔にまとめられた上記のようなイメージ画像が表示されています。この画像を見ることで、Mastraが一目でどのようなフレームワークであり、どのような機能を提供しているのかを把握できます。

例えば、家を建てるときに、基礎や柱、壁などの基本的な構造がすでに用意されているようなものです。また、”TypeScript agent framework”というキャッチコピーから、TypeScriptを使ってAIエージェントを開発するためのフレームワークであることがわかります。TypeScriptは、JavaScriptに型（数値や文字列など、データの種類）の情報を加えたもので、より安全にプログラムを書くことができます。しかし、現在この画像は直接参照できません。

Mastraは、AI技術を活用したアプリケーション開発の効率化を目指したフレームワークです。従来の開発では、AIモデルの選定、APIとの連携、エラー処理など、多くの煩雑な作業が必要でした。

例えば、AIチャットボットを開発する場合、

• どのLLM(大規模言語モデル)を使うか
• LLMプロバイダーのAPIキーの管理
• APIとの通信処理
• エラー処理

などを考慮し、実装する必要があります。 Mastraはこれらの作業を抽象化し、開発者がより少ないコードでAI機能を実装できるように設計されています。

具体的には、以下のような機能を、レゴブロックのように組み合わせて、アプリケーションを開発できます。

• AIエージェント：ユーザーの代わりに、様々なタスクを実行するAIです。メールの自動返信、スケジュールの調整、情報の検索など、様々な処理を自動化できます。例えば、顧客からの問い合わせメールに対し、過去の対応履歴やFAQを参照しながら、最適な回答を自動生成し返信する、といったことが可能です。
• ワークフロー：複数の処理を、特定の順序で実行するための仕組みです。「ユーザーからの問い合わせ内容を分析」→「適切な回答を生成」→「メールで返信」といった一連の処理を、自動的に実行できます。各ステップでの処理結果を次のステップに渡せるため、複雑な業務フローも自動化できます。
• RAG（検索拡張生成）：ユーザーからの質問に対して、関連する情報を検索し、その情報に基づいて回答を生成する技術です。社内ドキュメントやFAQデータベースなどを検索対象とすることで、より正確で、より詳細な回答を、質問応答システムやチャットボットに提供できます。
• 外部サービス連携：OpenAI、Anthropic、Google Geminiなど、様々な外部のAIサービスと連携できます。これにより、Mastraの機能を拡張し、より高度なAIアプリケーションを開発できます。例えば、OpenAIのGPTモデルを使って文章を生成し、AnthropicのClaudeモデルで文章の要約を行う、といった連携が可能です。

Mastraは、これらの機能を、TypeScriptというプログラミング言語で利用できるように設計されています。

TypeScriptは、JavaScriptに型情報を追加した言語で、より安全で、より保守性の高いコードを書くことができます。型情報があることで、コンパイル時にエラーを検出しやすくなり、大規模なアプリケーション開発でも品質を維持しやすくなります。

似たようなもので、OpenAIが提供するAgents SDKというものがあります。以下の記事に概要をまとめていますので、ぜひご覧ください！

あわせて読みたい

OpenAI Agents SDK : AIエージェントを簡単かつ効率的に開発できる！ OpenAIの Agents SDK と Responses API を使えば、誰でも簡単にAIエージェントを開発できます。Web検索やファイル検索、PC操作も自動化。複数のエージェント連携や安全性確保の機能も充実。開発効率を劇的に向上させ、未来のAIエージェント開発を体験しましょう！

関連記事：OpenAI Agents SDK : AIエージェントを簡単かつ効率的に開発できる！

Mastraのメリット：開発期間短縮と高品質化

Mastraを利用することで、開発者は以下のようなメリットを得られます。

• 開発期間の短縮：AIモデルとの連携や、複雑な処理フローの構築といった、時間のかかる作業をMastraが肩代わりします。Mastraが提供する機能を利用することで、ゼロから機能を開発する手間を大幅に削減できます。例えば、エージェント機能を使えば、従来はAPIとの通信処理やエラー処理などを個別に実装する必要がありましたが、Mastraでは数行のコードでエージェントを作成し、必要な機能をツールとして追加するだけで済みます。
• コードの品質向上：TypeScriptの型システムにより、コンパイル時にエラーを検出しやすくなり、バグの少ない、安全なコードを記述できます。Mastraが提供するAPIも型安全であるため、APIの利用方法を間違えるといったミスも防げます。
• 保守性の向上：Mastraは、統一されたインターフェースを提供するため、コードの可読性が向上します。これにより、他の開発者が書いたコードを理解しやすくなり、保守や機能拡張が容易になります。Mastraの提供する機能は、それぞれ独立したモジュールとして設計されているため、変更の影響範囲を局所化できます。
• 最新技術の活用：Mastraは、最新のAI技術を積極的に取り入れています。OpenAIの最新モデルや、新しいRAG技術などを、常に利用可能です。これにより、開発者は常に競争力のあるアプリケーションを開発できます。

Mastraと類似技術との比較：違いはどこにある？

Mastraと同様に、AIアプリケーション開発を支援するフレームワークは他にも存在します。LangChainやLlamaIndexなどがその例です。しかし、Mastraはそれらと比較して、以下のような特徴があります。

この表は、Mastraと、LangChain, LlamaIndexの主な特徴を比較したものです。言語、型安全性、APIのシンプルさ、カスタマイズ性、開発環境について比較しています。

これらの特徴から、Mastraは特に、TypeScriptを使用し、型安全性を重視する開発者にとって、有力な選択肢となります。LangChainやLlamaIndexはPythonでの利用者が多いですが、MastraはTypeScriptに特化することで、より安全で保守性の高い開発を可能にしています。

また、MastraはAPIがシンプルで、学習コストが低いのも特徴です。Mastra Playgroundというローカル開発環境が充実しており、エージェントとの対話や、ツール、ワークフローのテストを簡単に行うことができます。

そしてここ最近Mastraが注目を集め、Githubのスター数でMastraが王者LangChainを一気に追い抜いたというツイートが話題になりました。

Mastraのインストール方法

自動インストール：推奨される方法

Mastraを使い始める最も簡単な方法は、自動インストールです。以下のコマンドをターミナルで実行するだけで、Mastraプロジェクトのひな形が作成され、必要なものがすべて自動的にセットアップされます。

npx create-mastra@latest

このコマンドを実行すると、対話形式でいくつかの質問が表示されます。

What do you want to name your project? my-mastra-app
Choose components to install:
  ◯ Agents (recommended)
  ◯ Tools
  ◯ Workflows
Select default provider:
  ◯ OpenAI (recommended)
  ◯ Anthropic
  ◯ Groq
Would you like to include example code? No / Yes
Turn your IDE into a Mastra expert? (Installs MCP server)
  ◯ Skip for now
  ◯ Cursor
  ◯ Windsurf

ここでは、プロジェクト名、インストールするコンポーネント（エージェント、ツール、ワークフロー）、デフォルトのLLMプロバイダー、サンプルコードを含めるかどうか、Mastra Code Pilot(MCP)サーバーをインストールするかどうかを選択できます。

MCPは、コーディング中にドキュメント、サンプル、ヘルプをすぐに利用できるようにするIDEの拡張機能です。VSCode, Cursor, Windsurfで利用可能です。

各選択肢は以下のような意味を持ち、選択によって生成されるファイルが変わります。

• プロジェクト名: 作成するプロジェクトの名前を指定します。ここでは例として”my-mastra-app”としています。
• コンポーネント:
  • Agents: チェックを入れると、src/mastra/agentsディレクトリと、エージェントのサンプルファイル(index.ts)が生成されます。
  • Tools: チェックを入れると、src/mastra/toolsディレクトリと、ツールのサンプルファイル(index.ts)が生成されます。
  • Workflows: チェックを入れると、src/mastra/workflowsディレクトリと、ワークフローのサンプルファイル(index.ts)が生成されます。
• デフォルトプロバイダ:
  • OpenAI: OpenAIのGPTモデルなどを利用する場合に選択します。選択すると、.env.developmentファイルにOPENAI_API_KEYのプレースホルダーが追加されます。
  • Anthropic: AnthropicのClaudeモデルなどを利用する場合に選択します。選択すると、.env.developmentファイルにANTHROPIC_API_KEYのプレースホルダーが追加されます。
  • Groq: GroqのLPU Inference Engineを利用する場合に選択します。選択すると、.env.developmentファイルにGROQ_API_KEYのプレースホルダーが追加されます。
• サンプルコード: Yesを選択すると、動作するサンプルコードが生成されます。
• MCPサーバー：Mastra Code Pilotサーバーをインストールするかどうかを選びます。対応するIDEを使用している場合、インストールすることで、Mastraに関するドキュメントやサンプルコード、補完機能などが利用できるようになります。

選択後、create-mastraは以下のことを自動的に実行します。

1. TypeScriptを使用したプロジェクトディレクトリのセットアップ: 必要なディレクトリやファイルが自動的に作成されます。
2. 依存関係のインストール: package.jsonに記述された必要なパッケージ（ライブラリ）がインストールされます。
3. 選択したコンポーネントとLLMプロバイダーの設定: 選択した内容に基づいて、初期設定ファイルが生成されます。
4. MCPサーバーの設定（選択した場合）: 選択したIDEに応じて、MCPサーバーがインストールされ、設定されます。

最後に、選択したLLMプロバイダーのAPIキーを.envファイルに追加します。例えば、OpenAIを選択した場合は、以下のようになります。

OPENAI_API_KEY=

の部分を、OpenAIのウェブサイトで取得したAPIキーに置き換えてください。他のプロバイダーを選択した場合も、同様にAPIキーを設定する必要があります。

手動インストール：既存プロジェクトへの導入

既存のプロジェクトにMastraを導入する場合は、手動でインストールすることも可能です。既存のNode.jsプロジェクトや、Next.jsのようなReactフレームワークを使っているプロジェクトに、Mastraの機能を追加できます。

まず、プロジェクトディレクトリを作成し、その中に移動します。

mkdir hello-mastra
cd hello-mastra

次に、以下のコマンドを実行して、必要なパッケージをインストールします。

npm install typescript tsx @types/node mastra --save-dev
npm install @mastra/core zod @ai-sdk/openai

これらのコマンドは、以下のパッケージをインストールします。

• typescript: TypeScriptコンパイラ
• tsx: TypeScriptコードを実行するためのランタイム
• @types/node: Node.jsの型定義ファイル
• mastra: Mastra CLI
• @mastra/core: Mastraのコアライブラリ
• zod: スキーマバリデーションライブラリ
• @ai-sdk/openai: OpenAIのAPIクライアント (Vercel AI SDK)

続いて、TypeScriptの設定ファイル（tsconfig.json）を、プロジェクトのルートディレクトリに作成します。内容は以下のようにします。

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "strict": true,
    "skipLibCheck": true,
    "outDir": "dist"
  },
  "include": [
    "src/**/*"
  ],
  "exclude": [
    "node_modules",
    "dist",
    ".mastra"
  ]
}

この設定ファイルは、TypeScriptコンパイラに対して、どのようにコードをコンパイルするかを指示するものです。主な設定項目は以下の通りです。

• target: コンパイル後のJavaScriptのバージョンをES2022に指定します。
• module: 使用するモジュールシステムをES2022に指定します。
• moduleResolution: モジュールの解決方法を”bundler”に指定します。
• esModuleInterop: CommonJSモジュールとESモジュールの相互運用性を有効にします。
• strict: 厳格な型チェックを有効にします。
• outDir: コンパイル後のファイルを出力するディレクトリを”dist”に指定します。
• include: コンパイル対象のファイルを指定します。
• exclude: コンパイル対象から除外するファイルを指定します。

最後に、.envファイルを作成し、APIキーを設定します。

OPENAI_API_KEY=

これで、Mastraを使用する準備が整いました。既存のプロジェクトに組み込む場合は、src/mastraディレクトリを作成し、その中にエージェント、ツール、ワークフローのファイルを配置します。既存のNext.jsプロジェクトに組み込む場合は、src/app/mastraディレクトリを作成し、その中にファイルを配置します。

Mastraの主要機能：エージェント、ツール、ワークフロー

エージェント：自律的にタスクを実行するAI

Mastraの「エージェント」は、ユーザーの指示に基づいて、自律的にタスクを実行するAIです。エージェントは、複雑なタスクを自動化したり、ユーザーとの対話を通じて情報を提供したりするために使用できます。

エージェントは、以下のような要素で構成されます。

• 指示（Instructions）：エージェントに何をしてほしいかを自然言語で記述します。エージェントの役割や振る舞いを定義します。
• モデル（Model）：エージェントが使用するLLM（大規模言語モデル）を指定します。OpenAIのGPT-4oや、AnthropicのClaudeなどが利用可能です。モデルには、`openai()`関数の引数として、モデル名（例えば’gpt-4o-mini’）を渡します。`openai()`関数には、モデル名の他に、`temperature`や`maxTokens`などのパラメータを渡すことができます。これらのパラメータは、LLMの挙動を調整するために使用します。詳細はOpenAIのドキュメントを参照してください。
• ツール（Tools）：エージェントが利用できる機能（関数）を定義します。ツールは、外部APIを呼び出したり、データベースにアクセスしたり、特定の計算を実行したりできます。
• メモリ (Memory): エージェントは会話の履歴を記憶することができます。これにより、文脈に応じた応答が可能になります。Mastraでは、様々な種類のメモリが提供されています。
• toolChoice: エージェントがツールを呼び出すかどうか、またどのツールを呼び出すかを制御できます。詳細はこちら。

例えば、以下は、OpenAIのGPT-4oモデルを使用し、weatherToolというツールを利用できる、weatherAgentという名前のエージェントを定義する例です。

import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core/agent";
import { weatherTool } from "../tools/weather-tool";

export const weatherAgent = new Agent({
  name: "Weather Agent",
  instructions: `あなたは親切な天気アシスタントで、正確な天気情報を提供します。

あなたの主な機能は、ユーザーが特定の場所の天気の詳細を取得するのを支援することです。応答するときは：
- 場所が提供されていない場合は、常に場所を尋ねてください
- 場所の名前が英語でない場合は、翻訳してください
- 湿度、風の状況、降水量などの関連情報を含めてください
- 簡潔ながらも有益な応答を心がけてください

weatherToolを使用して現在の天気データを取得します。`,
  model: openai("gpt-4o-mini"),
  tools: { weatherTool },
});

このエージェントは、”Weather Agent”という名前を持ち、「あなたは親切な天気アシスタント…」という指示に従って動作します。`model`プロパティでOpenAIのgpt-4o-miniモデルを使用するように指定されており、toolsプロパティでweatherToolを利用できるように設定されています。

このエージェントは、「ロンドンの天気は？」といった質問に対して、weatherToolを使って天気情報を取得し、適切な回答を生成します。エージェントは、指示に基づいて、必要に応じてユーザーに追加の情報を求めたり、ツールを呼び出したりしながら、自律的にタスクを完了します。

エージェントは、Mastraの中核的な機能であり、様々なタスクを自動化するための強力なツールです。

ツール：エージェントが利用できる機能

「ツール」は、エージェントが利用できる機能（関数）です。ツールは、特定のタスクを実行するためにエージェントによって呼び出されます。ツールは、外部APIとの連携、データベースへのアクセス、計算処理など、様々な機能を実装できます。ツールは、以下のような要素で構成されます。

• ID：ツールを識別するためのIDです。エージェントはこのIDを使ってツールを呼び出します。
• 説明（Description）：ツールの機能を説明します。エージェントはこの説明を読んで、どのツールを使うべきかを判断します。
• 入力スキーマ（inputSchema）：ツールの入力パラメータの型を定義します。これにより、エージェントがツールに渡すパラメータの型が正しいことを保証します。Mastraでは、スキーマ定義にZodライブラリを使用します。
• 出力スキーマ（outputSchema）：ツールの出力の型を定義します。エージェントは、ツールの実行結果をこのスキーマに基づいて解釈します。
• 実行関数（execute）：ツールの実際の処理を記述します。この関数は、入力パラメータを受け取り、処理結果を返します。

以下は、指定された場所の現在の天気を取得するweather-toolの例です。

import { createTool } from "@mastra/core/tools";
import { z } from "zod";

interface WeatherResponse {
  current: {
    time: string;
    temperature_2m: number;
    apparent_temperature: number;
    relative_humidity_2m: number;
    wind_speed_10m: number;
    wind_gusts_10m: number;
    weather_code: number;
  };
}

export const weatherTool = createTool({
  id: "get-weather",
  description: "指定された場所の現在の天気を取得します。",
  inputSchema: z.object({
    location: z.string().describe("都市名"),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    feelsLike: z.number(),
    humidity: z.number(),
    windSpeed: z.number(),
    windGust: z.number(),
    conditions: z.string(),
    location: z.string(),
  }),
  execute: async ({ context }) => {
    return await getWeather(context.location);
  },
});

const getWeather = async (location: string) => {
  const geocodingUrl = `https://geocoding-api.open-meteo.com/v1/search?name=${encodeURIComponent(location)}&count=1`;
  const geocodingResponse = await fetch(geocodingUrl);
  const geocodingData = await geocodingResponse.json();

  if (!geocodingData.results?.[0]) {
    throw new Error(`場所 '${location}' が見つかりません`);
  }

  const { latitude, longitude, name } = geocodingData.results[0];

  const weatherUrl = `https://api.open-meteo.com/v1/forecast?latitude=${latitude}&longitude=${longitude}¤t=temperature_2m,apparent_temperature,relative_humidity_2m,wind_speed_10m,wind_gusts_10m,weather_code`;

  const response = await fetch(weatherUrl);
  const data: WeatherResponse = await response.json();

  return {
    temperature: data.current.temperature_2m,
    feelsLike: data.current.apparent_temperature,
    humidity: data.current.relative_humidity_2m,
    windSpeed: data.current.wind_speed_10m,
    windGust: data.current.wind_gusts_10m,
    conditions: getWeatherCondition(data.current.weather_code),
    location: name,
  };
};

function getWeatherCondition(code: number): string {
  const conditions: Record = {
    0: "晴れ",
    1: "おおむね晴れ",
    2: "一部曇り",
    3: "曇り",
    45: "霧",
    48: "着氷性の霧",
    51: "弱い霧雨",
    53: "中程度の霧雨",
    55: "濃い霧雨",
    56: "弱い着氷性の霧雨",
    57: "濃い着氷性の霧雨",
    61: "小雨",
    63: "中程度の雨",
    65: "大雨",
    66: "弱い着氷性の雨",
    67: "強い着氷性の雨",
    71: "小雪",
    73: "中程度の雪",
    75: "大雪",
    77: "雪粒",
    80: "弱い雨",
    81: "中程度の雨",
    82: "激しい雨",
    85: "弱い雪",
    86: "強い雪",
    95: "雷雨",
    96: "雷雨、弱い雹を伴う",
    99: "雷雨、強い雹を伴う",
  };
  return conditions[code] || "不明";
}

このツールは、get-weatherというIDを持ち、「指定された場所の現在の天気を取得します。」という説明がついています。inputSchemaでは、locationという文字列型のプロパティを持つオブジェクトを入力として受け取ることを定義しています。outputSchemaでは、気温や湿度などを含むオブジェクトを出力として返すことを定義しています。execute関数では、Open-Meteo APIを呼び出して天気情報を取得し、整形して返しています。

ツールを定義することで、エージェントは複雑な処理を直接実行する代わりに、ツールを呼び出すだけでタスクを完了できます。これにより、エージェントの定義がシンプルになり、保守性も向上します。また、ツールは再利用可能なコンポーネントとして、複数のエージェントやワークフローで共有できます。

ツールは、createTool関数を使って定義します。この関数は、ツールの設定オブジェクトを引数として受け取り、ツールオブジェクトを返します。ツールオブジェクトは、エージェントのtoolsプロパティに追加することで、エージェントから利用できるようになります。

ワークフロー：複数の処理を組み合わせる

「ワークフロー」は、複数の処理（ステップ）を、特定の順序で実行するための仕組みです。ワークフローは、複雑なタスクを自動化したり、複数のエージェントやツールを連携させたりするために使用できます。ワークフローは、以下のような要素で構成されます。

• ステップ（Steps）：実行する個々の処理を定義します。各ステップは、入力と出力を持ち、ツールを呼び出したり、他のワークフローを呼び出したりできます。
• トリガー（Trigger）：ワークフローを開始する条件を定義します。トリガーは、特定のイベントが発生したときや、スケジュールに基づいてワークフローを開始できます。
• 変数（Variables）：ワークフロー内で使用する変数を定義します。変数は、ステップ間でデータを共有したり、ワークフローの実行中に状態を保持したりするために使用できます。

以下は、logCatNameという単一のステップを持つ、非常にシンプルなワークフローの例です。

import { Workflow, Step } from '@mastra/core';
import { z } from 'zod';

const logCatName = new Step({
  id: 'logCatName',
  inputSchema: z.object({
    name: z.string(),
  }),
  outputSchema: z.object({
    rawText: z.string(),
  }),
  execute: async ({ context }) => {
    console.log('こんにちは、 ${context.name} 🐈‍⬛');
    return { rawText: 'Hello ${context.name}' };
  },
});

export const logCatWorkflow = new Workflow({
  name: 'hello-workflow',
  triggerSchema: z.object({
    name: z.string(),
  }),
  variables: {
    step: 'trigger',
    path: '', // ペイロード全体を渡す
  },
  logCatWorkflow.step(logCatName),
});

このワークフローは、hello-workflowという名前を持ち、nameという文字列型の入力を受け取るトリガーを持っています。logCatNameというステップが定義されており、このステップは、入力されたnameを使ってコンソールにメッセージを出力し、rawTextとして”Hello [name]”を返します。variablesプロパティでは、トリガーからの入力をlogCatNameステップに渡すように設定しています。

ワークフローを使うことで、複数のステップを組み合わせて複雑な処理を自動化できます。例えば、ユーザーからの入力を受け取り、複数のツールを順番に呼び出し、最終的な結果をユーザーに返す、といった処理をワークフローとして定義できます。

ワークフローは、Workflowクラスを使って定義します。Workflowクラスのコンストラクタには、ワークフローの名前、トリガースキーマ、変数、ステップなどを設定します。ステップは、Stepクラスを使って定義し、workflow.step()メソッドを使ってワークフローに追加します。

Mastraのワークフローは、柔軟性が高く、様々なユースケースに対応できます。例えば、以下のようなワークフローを構築できます。

• 複数のエージェントを連携させ、複雑なタスクを自動化するワークフロー
• ユーザーからの入力を受け取り、条件分岐やループ処理を含むワークフロー
• 定期的なスケジュールに基づいて実行されるワークフロー
• 外部イベント（例えば、Webhook）をトリガーとして実行されるワークフロー

Mastraの開発環境：ローカルでのテストとデバッグ

mastra dev：ローカル開発サーバーの起動

Mastraには、ローカルでエージェントやワークフローをテスト・デバッグするための開発サーバーが用意されています。以下のコマンドを実行することで、開発サーバーを起動できます。

npm run dev

または、Mastra CLIがグローバルにインストールされている場合は、以下のコマンドを実行します。

mastra dev

このコマンドを実行すると、デフォルトではローカルホストの4111番ポート（http://localhost:4111）で開発サーバーが起動し、Mastra Playgroundと呼ばれるWeb UIが表示されます。Mastra Playgroundを使うと、ブラウザ上でエージェントやツール、ワークフローの動作を確認できます。

Mastra Playgroundは、開発中のエージェントやワークフローの動作を視覚的に確認しながら開発を進められる、強力なツールです。Playgroundでは、エージェントとの対話、ツールの実行テスト、ワークフローの実行と状態確認などが可能です。Playgroundの各機能については、以降のセクションで詳しく説明します。

さらに、mastra devコマンドで起動する開発サーバーは、OpenAPI仕様のAPIドキュメントを自動生成します。これにより、開発中のエージェントやワークフローのAPIを、Swagger UIなどのツールを使って簡単に確認できます。Swagger UIは、APIのエンドポイント、リクエスト/レスポンスのスキーマ、パラメータなどを視覚的に表示し、APIのテストも行えるツールです。Swagger UI にアクセスするには、ブラウザで http://localhost:4111/openapi.jsonを開いてください。

Mastra Playground：エージェントとの対話

Mastra Playgroundでエージェントと対話する様子は、こちらの記事に画像が掲載されています。

Playgroundの左側には、利用可能なエージェントのリストが表示されます。各エージェントには、名前、指示（Instruction）、モデル、アクション（Action）が表示されており、エージェントの概要を一目で確認できます。「Chat with agent」ボタンをクリックすると、特定のエージェントとの対話を開始するためのチャットウィンドウが開きます。

チャットウィンドウでは、ユーザーがエージェントに対して質問を送信し、エージェントが応答を返す様子がリアルタイムで表示されます。

例えば、上記画像では、”Hotel Assistant”エージェントとの対話が示されています。

この画像では、ユーザーが”I would like informations about my bookings”（予約情報を知りたい）とリクエストすると、エージェントはアカウントIDを尋ね、ユーザーがアカウントID “def245” を入力すると、エージェントは、パリ（エッフェル塔プラザ）と東京（パークハイアット）の2件の予約情報を提示しています。

これらの画像から、Mastra Playgroundを使って、開発中のエージェントと会話形式でやり取りし、その動作を簡単に確認できることがわかります。具体的には、エージェントに質問を送信し、エージェントからの応答をリアルタイムで確認できます。また、エージェントがツールを呼び出した場合（この例では予約情報を取得するツール）、そのツールの入力と出力も表示されるため、エージェントがどのように思考し、どのようにツールを利用しているのかを詳細に把握できます。

Mastra Playground：ツールのテスト

実際動作を確認できていませんが、Mastraの設計思想から、Toolsタブでは以下のような機能が提供されていると推測できます。

• 登録されているツールのリストが表示される。
• 各ツールには、名前と説明が表示される。
• 各ツールの「Run」ボタンをクリックすることで、ツールを単体で実行できる。
• ツールの実行時には、入力パラメータを指定できる。
• ツールの実行結果は、JSON形式で表示される。
• ツールに問題がある場合は、エラーメッセージが表示される。

Mastara PlaygroundのToolsタブは、開発者がツールを個別にテストし、その動作を確認するための機能を提供します。 これにより、エージェントに組み込む前に、ツールの機能が正しく実装されていることを確認できます。

Mastra Playground：ワークフローの確認

こちらも実際動作を確認できていませんが、Mastraの設計思想から、Workflowsタブでは以下のような機能が提供されていると推測できます。

• 登録されているワークフローの一覧が表示される。
• 各ワークフローには名前が表示される。
• 各ワークフローの「View Workflow」ボタンをクリックすることで、ワークフローの詳細画面に遷移できる。
• 詳細画面では、ワークフローがどのようなステップで構成されているか、各ステップがどのように接続されているかが視覚的に表示される。
• 各ステップの入力と出力、実行状態（成功、失敗、実行中など）を確認できる。
• ワークフローの実行履歴がリスト形式で表示され、各実行のトリガーとなったデータ、実行結果、実行時間などを確認できる。
• ワークフローに問題がある場合は、エラーメッセージが表示され、どのステップでエラーが発生したのかを特定できる。

Mastara PlaygroundのWorkflowsタブは、開発者が作成したワークフローを視覚的に確認し、テスト・デバッグするための機能を提供します。これにより、複雑なワークフローも効率的に開発できます。

Mastraの応用：REST APIとしての利用

エンドポイントの確認と利用

Mastra PlaygroundのEndpointsタブの画像は、提供された資料の中には存在しません。しかし、Mastraの設計思想と、mastra devコマンドの機能から、Endpointsタブでは以下のような情報が提供されていると推測できます。

• Mastraで作成したエージェントやワークフローが、REST APIとして公開されていること。
• 各エンドポイントのHTTPメソッド（GET, POSTなど）とURLパスが表示されていること。
• 各エンドポイントのリクエストとレスポンスの形式（JSONなど）が示されていること。

これらのエンドポイントに対して、curlコマンドやfetch関数などを使ってHTTPリクエストを送信することで、エージェントやワークフローを実行できます。これにより、Mastraで開発した機能を、Webアプリケーション、モバイルアプリケーション、その他の外部システムから簡単に利用できます。

例えば、weatherAgentのgenerateエンドポイントに対して、curlコマンドを使ってリクエストを送信する場合は、以下のようになります。

curl -X POST http://localhost:4111/api/agents/weatherAgent/generate \
-H "Content-Type: application/json" \
-d '{"messages": ["ロンドンの天気は？"]}'

fetch関数を使う場合は、以下のようになります。

fetch('http://localhost:4111/api/agents/weatherAgent/generate', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    messages: ['ロンドンの天気は？'],
  }),
})
  .then(response => response.json())
  .then(data => {
    console.log('エージェントの応答:', data.text);
  })
  .catch(error => {
    console.error('エラー:', error);
  });

エンドポイントは、エージェントやワークフローの名前に基づいて自動的に生成されます。例えば、weatherAgentという名前のエージェントには、/api/agents/weatherAgent/generateというエンドポイントが割り当てられます。他にも、ストリーミング用のエンドポイント(/api/agents/catOne/stream)など、いくつかのエンドポイントが自動的に生成されます。

MastraのREST APIは、OpenAPI仕様に準拠しているため、Swagger UIなどのツールを使ってAPIドキュメントを自動生成することも可能です。これにより、APIの仕様を簡単に確認したり、APIをテストしたりできます。このAPIドキュメントは、mastra dev コマンドで開発サーバーを起動した際に、http://localhost:4111/openapi.jsonで確認できます。

これらのエンドポイントを利用することで、Mastraで構築したAIの機能を、様々なアプリケーションから簡単に呼び出すことができます。これにより、既存のシステムにAI機能を統合したり、新しいAIサービスを迅速に開発したりすることが可能になります。 REST APIとして公開することで、Mastraで開発した機能を、Webアプリケーション、モバイルアプリケーション、デスクトップアプリケーション、さらにはIoTデバイスなど、様々なクライアントから利用できるようになります。

Mastra CLI: コマンドラインからの実行

スクリプトの作成と実行

Mastraでは、コマンドラインから直接エージェントを呼び出して実行することも可能です。これは、ちょっとしたタスクを自動化したり、Mastraの機能をバッチ処理で利用したりする場合に便利です。また、Mastraの機能を他のプログラムから利用する際の、インターフェースとしても活用できます。

そのためには、まずエージェントを取得し、呼び出すためのスクリプトを作成します。例えば、src/index.tsというファイルを作成し、以下のように記述します。

import { mastra } from "./mastra";

async function main() {
  try {
    const agent = await mastra.getAgent("weatherAgent");

    const result = await agent.generate("ロンドンの天気は？");

    console.log("エージェントの応答:", result.text);
  } catch (error) {
    console.error("エラーが発生しました:", error);
  }
}

main();

このスクリプトは、mastraオブジェクトからweatherAgentを取得し、generateメソッドを呼び出して、結果をコンソールに出力します。

各部分の役割は以下の通りです。

• import { mastra } from "./mastra";: src/mastra/index.tsでエクスポートされたmastraオブジェクトをインポートします。これにより、登録されているエージェントやワークフローにアクセスできます。
• async function main() { ... }: 非同期処理を行うためのmain関数を定義します。MastraのAPIの多くは非同期処理であるため、async/await構文を使用します。
• const agent = await mastra.getAgent("weatherAgent");: mastra.getAgent()メソッドを使って、weatherAgentという名前のエージェントを取得します。このメソッドは、Promiseを返すため、awaitキーワードを使ってエージェントが取得できるまで待機します。
• const result = await agent.generate("ロンドンの天気は？");: 取得したエージェントのgenerateメソッドを呼び出し、”ロンドンの天気は？”というメッセージを渡します。generateメソッドもPromiseを返すため、awaitキーワードを使って応答を待ちます。応答はresult変数に格納されます。
• console.log("エージェントの応答:", result.text);: エージェントからの応答（result.text）をコンソールに出力します。
• } catch (error) { ... }: try...catch構文を使い、エラーを捕捉します。エージェントの呼び出し中にエラーが発生した場合、catchブロック内のコードが実行され、エラーメッセージがコンソールに出力されます。
• main();: 定義したmain関数を実行します。

スクリプトを作成したら、以下のコマンドで実行できます。

npx tsx src/index.ts

これにより、Node.js環境でスクリプトが実行され、エージェントの応答がコンソールに表示されます。このスクリプトは、あくまで一例です。例えば、以下のような応用が考えられます。

• コマンドライン引数の利用: スクリプトの引数として、エージェントに送信するメッセージや、エージェント名を渡せるようにする。これにより、スクリプトをより汎用的に使用できます。例えば、npx tsx src/index.ts weatherAgent "ニューヨークの天気は？" のように実行できるように改造できます。
• 複数のエージェントの呼び出し: 複数のエージェントを取得し、それぞれのエージェントに異なるメッセージを送信する。例えば、天気エージェントとニュースエージェントを連携させ、今日の天気と主要ニュースを組み合わせたレポートを生成する、といったことが可能です。
• ファイルからの入力: テキストファイルからメッセージを読み込み、エージェントに送信する。これにより、大量のメッセージを一括処理できます。例えば、顧客からの問い合わせメールをファイルに保存しておき、各メールに対してエージェントに回答を生成させることができます。
• 結果のファイル出力: エージェントからの応答を、コンソールに出力する代わりに、ファイルに保存する。これにより、エージェントの応答を後で分析したり、他のシステムで利用したりできます。

このように、MastraとTypeScriptを組み合わせることで、コマンドラインから簡単にAIエージェントを操作するスクリプトを作成し、実行できます。これにより、Mastraで開発したAI機能を、他のシステムやツールと連携させることが容易になります。

Mastraのプロジェクト構造

ファイルとディレクトリの役割

Mastraプロジェクトは、以下のようなディレクトリ構造を持ちます。この構造は、create-mastraコマンドでプロジェクトを作成した際に自動的に生成されます。

my-mastra-app/
├── node_modules/
├── src/
│   └── mastra/
│       ├── agents/
│       │   └── index.ts
│       ├── tools/
│       │   └── index.ts
│       ├── workflows/
│       │   └── index.ts
│       └── index.ts
├── .env.development
├── .gitignore
├── package-lock.json
├── package.json
└── tsconfig.json

各ファイルとディレクトリの役割は以下の通りです。より詳細な情報を表形式でまとめます。

この構造に従うことで、Mastraアプリケーションのコードを整理し、保守性を高めることができます。

src/mastra/index.ts：Mastraのエントリポイント

src/mastra/index.tsは、Mastraアプリケーションのエントリポイントとなるファイルです。このファイルで、Mastraオブジェクトを作成し、エージェント、ツール、ワークフローを登録します。Mastraオブジェクトは、アプリケーション全体の設定を保持し、エージェントやワークフローへのアクセスを提供します。

以下は、src/mastra/index.tsの例です。

import { Mastra, createLogger } from '@mastra/core';
import { catOne } from './agents/index';

export const mastra = new Mastra({
  agents: { catOne },
  logger: createLogger({
    type: 'CONSOLE',
    level: 'INFO',
  }),
});

この例では、Mastraオブジェクトを作成し、agentsプロパティにcatOneエージェントを登録しています。

agentsプロパティには、キーと値のペアの形式でエージェントを登録します。キーはエージェントの名前（エージェント定義ファイル中で指定）、値はエージェントのオブジェクトです。

また、loggerプロパティには、ログ出力に関する設定をしています。ここでは、コンソールに出力するロガーを設定しており、ログレベルはINFOに設定されています。ログレベルは、DEBUG, INFO, WARN, ERRORから選択できます。

src/mastra/index.tsに登録されたエージェント、ツール、ワークフローは、mastra devコマンドで起動する開発サーバーで利用できるようになります。また、このファイルで設定した内容は、アプリケーション全体に適用されます。

このファイルには、他にも以下のような設定を追加できます。

• tools: グローバルに利用可能なツールを登録します。ここに登録されたツールは、すべてのエージェントで利用できます。
• workflows: ワークフローを登録します。
• defaultAgent: デフォルトで使用するエージェントを指定します。
• cors: CORS (Cross-Origin Resource Sharing) の設定を行います。これにより、異なるオリジンからのリクエストを許可できます。

これらの設定を適切に行うことで、Mastraアプリケーションの動作を細かく制御できます。例えば、特定のエージェントのみに特定のツールへのアクセスを許可したり、特定のオリジンからのリクエストのみを許可したりできます。

Mastraの今後の展望

Mastraは、現在ベータ版であり、活発に開発が進められています。今後、以下のような機能の追加や改善が予定されています。Mastraのトップページに、”Roadmap”というセクションがあり、今後の開発予定が記載されています。

• より多くのLLMプロバイダーのサポート：OpenAI、Anthropic、Google Geminiに加えて、さらに多くのLLMプロバイダーをサポートする予定です。これにより、開発者は自分のニーズや好みに合わせて、最適なLLMプロバイダーを選択できるようになります。
• より多くのインテグレーション：様々な外部サービス（例えば、データベース、CRM、プロジェクト管理ツールなど）との連携を強化し、より多くのインテグレーションを提供する予定です。これにより、エージェントやワークフローから、より多くの外部リソースにアクセスできるようになります。
• ビジュアルなワークフローエディタ：ワークフローを視覚的に編集できるエディタを開発中です。これにより、開発者はドラッグ＆ドロップ操作でステップを配置したり、接続したりすることで、ワークフローを簡単に構築できるようになります。
• 高度なRAG機能：より高度なRAG機能（例えば、マルチモーダルRAG、構造化データRAGなど）を開発中です。これにより、エージェントは、より多様な情報源（画像、音声、構造化データなど）から情報を取得し、より高度な推論を行えるようになります。
• コミュニティとの連携強化：コミュニティからのフィードバックを積極的に取り入れ、Mastraをより使いやすく、より強力なフレームワークに成長させていく予定です。GitHub DiscussionsやDiscordサーバーなどを通じて、ユーザーとのコミュニケーションを密にし、要望や改善提案を収集します。
• Eval機能の強化: 既存の評価指標に加えて、より高度な評価指標（例えば、忠実性、安全性、公平性など）を追加し、カスタム評価指標の作成を容易にする予定です。具体的には、MastraのEvalsでは、モデルの評価、ルールベースの評価、統計的手法を用いた評価など、自動化された評価指標を提供します。毒性、偏見、関連性、事実の正確さなどについて評価できます。また、独自のEvalを定義することも可能です。

Mastraは、AIアプリケーション開発の未来を担う、強力なフレームワークです。ぜひ、Mastraを使って、あなたのアイデアを形にしてください。