Zenn
🥷

Mastraで爆速AIエージェント開発したい人向けサンプル

に公開
AI
TypeScript
AIエージェント
Mastra
elv2
tech

Mastraで爆速AIエージェント開発したい

AIAgent開発とその導入をしていて
Mastraというフレームワークが優れているので紹介したいです。

MastraはAIAgentの定義と、MCPの定義をすぐに設定できて
とにかく「開発が早い」ところが良い点です。

簡単な要件の場合だとAgentが20分ぐらいで作れたこともありました。

最近AIShiftでもmastraが紹介されたようです。

記事URL

今回、このフレームワークをある程度セットアップしたサンプルをリポジトリにアップしたので、紹介させていただきたいです。

作成したサンプルのリポジトリURL

https://github.com/musoukun/mastra-multi-agent-mcp-sample

Mastraって何がすごいの？

MastraはTypeScriptで構築されたAIエージェントフレームワークです。特に以下の点が優秀：

  • 統一されたモデルAPI: OpenAI、Anthropic、Google Geminiなど、どのLLMプロバイダーでも同じように扱える
  • エージェントメモリ: 会話履歴を永続化して文脈を維持
  • MCP（Model Context Protocol）連携: 外部ツールとの連携が簡単
  • ワークフローグラフ: 複雑な処理を視覚的に定義可能

でも、一番の売りだと思っている点は
「npmのプレイグラウンドですぐにテストできる」
ところです。

プレイグラウンドが最高に便利

MastraはAIAgentをテストできるプレイグラウンドが標準で備わっています。
とりあえずenvファイルに、APIキーを設定して、Mastraを起動するだけで使える。

npm run dev

これだけで以下のURLでサービスが利用可能になります：

  • プレイグラウンド: http://localhost:4111/
  • API: http://localhost:4111/api
  • Swagger UI: http://localhost:4111/swagger-ui
  • OpenAPI仕様: http://localhost:4111/openapi.json

実際の動作イメージ：

その場でデモが出来る点が素晴らしいです。

このサンプルプロジェクトの構成

src/
└── mastra/
    ├── agents/     # エージェント定義
    ├── index.ts    # Mastraインスタンス
    └── memory.ts   # メモリ設定

エージェント定義（agents/index.ts）

エージェントを定義して、MCPツールを自動で読み込んでいます。

export const agentConfigs = [
  {
    name: "Gemini Flash Experimental",
    model: google("gemini-2.0-flash-exp"),
    instructions: instructions,
    memory: memory,
  },
  // 他のエージェントを追加可能
];

ここが優れている点：

  • 複数のエージェントを配列で定義するだけ
  • モデル切り替えはプロバイダを変更するだけ
  • MCPツールは自動で全エージェントに配布される（この辺は調整してみてください）

MCPサーバー設定（mcp-servers.json）

外部ツール連携の設定もJSONファイルでstdio形式で設定できます。

{
  "servers": {
    "brave-search": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
      "env": {
        "BRAVE_API_KEY": "your_brave_api_key_here"
      }
    }
  }
}

メモリ設定（memory.ts）

会話履歴の管理も少ないコード数で設定できます。

export const memory = new Memory({
  storage: new LibSQLStore({
    config: { url: "file:.mastra/memory.db" },
  }),
  vector: new LibSQLVector({
    connectionUrl: "file:.mastra/vector.db",
  }),
  options: {
    lastMessages: 20,  // 最新20件を記憶
    semanticRecall: {
      topK: 3,  // 類似した過去の会話3件を参照
    },
  },
});

セマンティック検索まで備えています 過去の会話から関連する内容を自動で引っ張ってきて、より良い回答をしてくれます。

Mastraのメモリ・ストレージDB対応状況

Mastraのメモリ機能は非常に豊富なデータベース選択肢を提供しています。

ストレージ（会話履歴・ワークフロー状態）

  • LibSQL （デフォルト・開発用）
  • PostgreSQL （本格運用向け）
  • Upstash Redis （サーバーレス向け）
  • Cloudflare KV （エッジコンピューティング向け）
  • Cloudflare D1 （SQLiteライク）
  • DynamoDB （AWS環境）

ベクトルDB

  • LibSQL Vector （デフォルト）
  • Pinecone （専用ベクトルDB）
  • pgvector （PostgreSQL拡張）
  • Qdrant （オープンソース、Mem0とかのやつ）
  • Chroma （軽量）
  • Upstash Vector （サーバーレス）
  • Cloudflare Vectorize （エッジ向け）
  • MongoDB Vector （ドキュメントDB）
  • OpenSearch （Elasticsearch系）
  • Astra Vector （DataStax）

MastraをBackendAPIサーバーとして利用できる

MastraはAPIサーバーとしても標準でエンドポイントを持っていて、Backendサーバーとして機能します。

API仕様書を確認するための、openapiのページも用意されている点も非常に優れています。

  • プロトタイプはプレイグラウンドで確認
  • API仕様はSwagger UIで確認
  • 開発はAPI経由でfrontend等から呼び出し

この流れが全部揃ってるところが素晴らしい。

フロントエンド開発はassistant-uiがよかった

注意点は、mastraのライセンスElastic License 2.0 (ELv2)の規約上
MastraのPlayground等をそのままホスティングサービスとして利用はできないので
frontendを作ってMastraを隠した状態で商用利用する必要があります。

そこで採用しているのがassistant-uiです。
https://www.assistant-ui.com/docs/getting-started

これもまた基本的なAIチャットの機能が素早く作成できるものです。

標準で備わっている機能：

  • 履歴管理
  • すでに送信したメッセージの編集
  • Markdownの表示
  • メッセージのコピーボタン
  • Tool実行のUIカスタマイズ機能
  • 添付ファイル機能

その他いろいろの機能が最初から備わっているので
frontendもリッチなものが素早く開発出来ます。

ClaudeのCloneアプリをassistant-uiで作った例なども公開されています。

なぜこのセットアップが優秀なのか

1. とにかく開発が早い

  • npm create mastra@latest でプロジェクト作成
  • エージェント定義とMCP設定がすぐにできる。
  • プレイグラウンドで即座にテスト可能
  • 要件を聞きながらリアルタイムでAgent調整とかも場合によっては可能。

2. プロトタイプから本格運用までの流れ

  • プレイグラウンドでの動作確認
  • Swagger UIでAPIの仕様確認
  • assistant-uiでフロントエンド構築
  • API連携による外部システム統合

3. 拡張性が高い

  • エージェントは配列等で設定すれば、いくらでも追加できる
  • MCPサーバーもstdio形式でJsonに記述して読み込める。
  • 複数LLMプロバイダーの統一インターフェース

4. 実用的な機能が標準装備

  • ワーキングメモリでユーザー情報保持する機能が標準で備わっている
  • 会話履歴の永続化
  • ベクトル検索による過去会話の活用
  • スレッド管理機能

重要なライセンス注意点

MastraのライセンスはElastic License 2.0 (ELv2)で、これはOSI認定のオープンソースライセンスではありません。

制限事項

ELv2では以下の3つが禁止されています：

  1. マネージドサービスとして提供する行為の禁止
  2. ライセンスキー機能の回避行為の禁止
  3. ライセンス表示の削除・隠蔽行為の禁止

具体的な例

  • Mastraを直接SaaSとして他社に提供
  • Mastraベースのホスティングサービスの運営
  • 「Mastra as a Service」的なビジネス
  • プレイグラウンドをそのまま商用ホスティング

大丈夫なこと

  • 社内利用やクライアント向けの個別開発
  • 自社サービスの機能の一部としてMastraを組み込み
  • SaaSアプリの検索機能にMastraを使用
  • フロントエンドを作ってMastraを隠しつつ、【サービスの機能の一部】として商用利用する。
  • （隠してたらいいわけじゃないと思うし、この辺のとらえ方難しいので要確認だと思う）

つまり 「Mastraそのものを商売にするのはNG」 ということです。

まとめ

Mastraは本当に開発効率が良くて、AIエージェントのプロトタイピングから本格運用まで一貫して対応できる優秀なフレームワークです。

商用利用を検討する場合は、Elastic License 2.0の条項をよく確認して、適切な利用方法を選択することが重要です。（**この辺が結構あいまいで困るけど。。。**もともとは対AWSを意識したlicenseらしい）

※本記事のサンプルコードはあくまで学習・検証目的です。商用利用の際は必ずライセンス条項を確認してください。

Discussion