MastraによるAIエージェント開発・運用［実践入門］

はじめに
本書の想定読者
謝辞
本書のサンプルコードの使い方

■第1章 AIエージェントの基本

1.1　AIエージェントの概要
　AIエージェントとは
　AIエージェントの起源
　AIエージェントの4つの特徴
　エージェントの構成パターン
　COLUMN マルチエージェントは「タスク分解」で考える
1.2　AIエージェントの周辺技術
　メモリ
　RAG（検索拡張生成）
　MCP（Model Context Protocol）
　A2A（Agent-to-Agent Protocol）
　ガードレール
　COLUMN そのガードレール、本当に適切？
1.3　TypeScript中心のAIエージェント開発フレームワーク
　Mastra
　AI SDK
　VoltAgent
　TanStack AI
　COLUMN JavaScriptとTypeScriptの関係
1.4　その他のAIエージェント開発フレームワーク
　LangChain/LangGraph
　OpenAI Agent SDK
　Strands Agents
　Agent Development Kit（ADK）
　COLUMN フレームワークの選び方
1.5　AIエージェントのユースケースやプロダクト
　Claude Code
　Claude Cowork
　COLUMN コーディングエージェントを日常業務にも生かす
　OpenClaw
　キミガタリ
　パワポ作るマン

■第2章 Mastraによるエージェントとワークフローの実装

2.1　Mastraの概要
　Mastraの強み
　Mastra選定の決め手
　Mastra選定時の注意点
　Mastraの主要機能
2.2　Mastraプロジェクトの始め方
　プロジェクトのセットアップ
　プロジェクトの構成例
2.3　エージェントの実装
　エージェントの仕組み
　エージェントの実装コード
　ツールとMCP
2.4　各種モデルの使用方法
　モデルルーターによるモデルの指定
　AI SDKプロバイダーによるモデルの指定
　複数モデルの使い分けとフォールバック
2.5　ワークフローの実装
　ワークフローの仕組み
　ワークフローの実装コード
　コントロールフローの実装コード
　ワークフローの状態管理
　エージェントとツールの利用
2.6　Mastra Studioの概要
　Mastra Studioとは
　Mastra Studioの起動方法
　Mastra Studioで使える機能

■第3章 Mastraによる高度なエージェント機能の実装

3.1　ストリーミングの実装
　ストリーミングとは
　ストリーミングの実装コード
　ストリーミングイベントの種類
3.2　プロセッサの実装
　プロセッサとは
　プロセッサの実装コード
　カスタムプロセッサの実装コード
　ビルトインプロセッサの活用
3.3　メモリの実装
　メモリとは
　メモリの実装コード
　4種類のメモリの役割
　ストレージプロバイダーの選択
3.4　マルチエージェントの実装
　マルチエージェントとスーパーバイザーパターンとは
　スーパーバイザーパターンの実装コード
　A2Aによるフレームワーク間連携
3.5　Request Contextの実装
　Request Contextとは
　動的なマルチモデル選択の実装コード
3.6　ワークスペースとスキル
　ワークスペースとは
　スキルとは

■第4章 AI SDKによるマルチLLM対応とフロントエンド開発

4.1　AI SDKの概要
　AI SDKとは
　AI SDKの主要機能
4.2　AI SDK Coreによるテキスト生成と構造化出力
　AI SDK Coreとは
　テキスト生成の実装コード
　構造化出力の実装コード
4.3　AI SDK UIによるチャットUI構築
　AI SDK UIとは
　AI SDK UI単体によるチャットUIの実装コード
　AI SDK UIとMastraによるチャットUIの実装コード
4.4　AI ElementsによるUIコンポーネントの活用
　AI Elementsとは
　コンポーネントの追加方法
　代表的な4つのサンプル
　COLUMN AI Elementsのスキル対応
4.5　MastraとAI SDKの使い分け
　ToolLoopAgentクラスによるエージェントの実装
　得意分野を活かした選択

■第5章 社内ドキュメント検索アプリを作って学ぶRAG

5.1　RAGの概要
　RAGとは
　RAGの仕組み
　RAGの利点と特徴
5.2　RAG実装の全体像
　完成イメージの確認
　実装方法と採用技術
　アーキテクチャ概要
　実装手順
5.3　ハンズオンの準備
　社内ドキュメントの用意
　プロジェクトの作成
　ベクトルデータベースのインストール
　.envファイルの確認
　Mastraインスタンスの初期化
5.4　ドキュメントのチャンク化と保存
　ドキュメントの初期化
　markdown戦略によるチャンク化
　インデックスの作成
　埋め込みの生成
　メタデータの付与
　スクリプトの実行
5.5　検索ツールの組み込みとエージェントの実行
　ベクトル検索ツールとRAGエージェントの作成
　COLUMN リランクによる検索精度の向上
　MastraインスタンスへのRAGエージェントの登録
　Mastra Studioの起動と動作確認
5.6　ドキュメント更新時の再取り込み
　一部チャンクの再構築
　全面的なチャンクの再構築

■第6章 Deep Researchアプリを作って学ぶHITLを組み込んだワークフロー

6.1　HITLとDeep Researchの概要
　HITLとは
　Deep Researchとは
　Human-in-the-Loopを組み込んだワークフローとは
　COLUMN スナップショットの深掘り
6.2　HITLを組み込んだワークフロー実装の全体像
　実装後のイメージ
　実装方針と採用技術
　アーキテクチャ概要
　実装手順
6.3　ハンズオンの準備
　プロジェクトの作成
　.envファイルの確認
6.4　ユーザーからの入力を受け取るワークフローの実装
　検索ワークフロー（クエリ取得ステップ）の作成
　クエリ評価エージェントの作成
　Mastraインスタンスへの検索ワークフローとクエリ評価エージェントの登録
　Mastra Studioの起動と動作確認
6.5　検索ワークフローの実装
　検索ワークフロー（検索ステップ）の作成
　検索エージェントの作成
　.envファイルへのTavily APIキーの追加
　Tavilyクライアントのインストール
　検索ツールの作成
　評価ツールの作成
　評価エージェントの作成
　学習ツールの作成
　学習エージェントの作成
　検索ワークフローの書き換え
　Mastra Studioの動作確認
6.6　ユーザー評価ワークフローの実装
　検索ワークフロー（ユーザーの承認ステップ）の作成
　検索ワークフローの書き換え
　Mastra Studioでの動作確認
　COLUMN 厳密に検索ワークフローを制御したい場合
6.7　レポート生成ワークフローの実装
　ループ制御ワークフローの実装コード
　レポート生成ワークフローの作成
　レポート生成エージェントの作成
　Mastraインスタンスへのレポート生成ワークフローとレポート作成エージェントの登録
　Mastra Studioでの動作確認
　COLUMN HITLポイントの数と粒度の見極め方

■第7章 Deep Researchアプリを作って学ぶAPIサーバーとフロントエンドの構築

7.1　APIサーバーの概要
　APIサーバーとは
　組み込みサーバーとサーバーアダプターの違い
　COLUMN Honoがサーバーミドルウェアとして選ばれる理由
　APIサーバーにおける認証機能とは
7.2　APIサーバー構築の全体像
　実装後のイメージ
　実装方針と採用技術
　アーキテクチャ概要
　実装手順
7.3　APIサーバーからのエージェントの呼び出し
　APIドキュメントの確認
　REST Clientのインストール
　エージェント一覧の確認
　クエリ評価エージェントの呼び出しと動作確認
7.4　APIサーバーにおける認証機能の実装
　シークレットキーとJSON Web Tokenの作成
　.envファイルへのシークレットキーの追加
　Mastra認証ライブラリのインストール
　MastraインスタンスへのMastraJwtAuthの登録
　クエリ評価エージェントの呼び出しと動作確認
7.5　フロントエンドの概要
　Webアプリの土台となる技術
　AI通信ライブラリの選択肢
7.6　フロントエンド構築の全体像
　実装後のイメージ
　実装方針と採用技術
　アーキテクチャ概要
　実装手順
7.7　フロントエンド構築の準備
　Viteの初期化
　Tailwind CSSの初期化
　Tailwindプラグインの追加
　Tailwind CSSの有効化
　パスエイリアスの追加
　AI SDKとAI Elementsのインストール
7.8　フロントエンドとMastraの連携
　Mastraの初期化
　認証とエージェント関連ライブラリのインストールとファイルの移動
　MastraとReactの同時起動を実現するライブラリのインストール
　MastraとReactの同時起動を実現するスクリプトの書き換え
　開発サーバーの起動と動作確認
7.9　フロントエンドの作成とAPIの呼び出し
　ワークフローのAI SDK形式への変換
　チャット画面の作成(1)―ライブラリの読み込み
　チャット画面の作成(2)―型の定義
　チャット画面の作成(3)―ワークフローのUI描画
　.envファイルへのJSON Web Tokenの追加
　チャット画面の作成(4)―API呼び出しの設定とJSON Web Tokenの付与
　チャット画面の作成(5)―UI状態の導出
　チャット画面の作成(6)―ユーザー操作のハンドラー実装
　チャット画面の作成(7)―メッセージ一覧とテキスト入力画面の実装
　メイン画面の作成
　チャット画面での動作確認
　COLUMN エージェントのツール実行におけるHITLの実現
　COLUMN エージェントとエージェンティックワークフローの使い分け
　COLUMN 信頼性の高いワークフロー実行を支えるDurable Execution

■第8章 画像生成アプリを作って学ぶチャット応答機能・認証機能・プラン管理機能

8.1　チャット応答機能の概要
　チャット応答機能とは
　AIエージェントにおけるチャット応答機能の役割
8.2　チャット応答機能の全体像
　実装後のイメージ
　実装方針と採用技術
　アーキテクチャ概要
　実装手順
8.3　ハンズオンの準備
　Next.jsプロジェクトの初期化
　Mastraの初期化
　AI SDK関連ライブラリのインストール
　MastraインスタンスへのlibSQLの登録
　.envファイルへのGoogle Gemini APIキーとアプリURLの追加
8.4　チャット応答機能の実装
　チャット応答エージェントの作成
　Mastraインスタンスへのチャット応答エージェントの登録
　チャット応答APIルートの作成
　開発サーバーの起動とロジックの動作確認
8.5　チャットUIの作成とAPIの呼び出し
　shadcn/uiの導入
　必要なshadcn/uiコンポーネントの追加
　チャット画面の作成
　チャット画面での動作確認
8.6　認証機能の概要
　認証機能とは
　AIエージェントにおける認証機能の役割
8.7　認証機能の全体像
　実装後のイメージ
　実装方針と採用技術
　アーキテクチャ概要
　実装手順
8.8　認証システムの実装
　Better AuthとlibSQLアダプターのインストール
　秘密鍵の生成と.envファイルへの追加
　認証インスタンスの初期化
　Next.js設定の更新
　マイグレーションの実行
　認証用APIルートの作成
　認証クライアントの作成
　COLUMN Better Authを採用した理由
　Proxyによるルート保護の作成
　チャット応答用APIルートの書き換え
　APIの動作確認
8.9　認証UIの作成とAPIの呼び出し
　サインアップページの作成
　サインインページの作成
　認証画面での動作確認
　COLUMN AIエージェント時代の認証・認可の課題
8.10　プラン管理機能の概要
　プラン管理機能とは
　AIエージェントにおけるプラン管理機能の役割
8.11　プラン管理機能の全体像
　実装後のイメージ
　実装方針と採用技術
　アーキテクチャ概要
　実装手順
8.12　プラン管理機能の実装
　各プランにおけるデモ仕様の定義
　ユーザースキーマの拡張
　マイグレーションの実行
　トークン追跡テーブルの作成
　COLUMN トークン使用量をauth.dbに持つ理由
　データベース接続クライアントの作成
　トークン管理ユーティリティの作成
　チャット応答用APIルートの書き換え
　トークン情報取得用APIルートの作成
　チャット応答エージェントの書き換え
　APIの動作確認
8.13　プラン管理UIの作成とAPIの呼び出し
　テスト用レコード削除
　各プランにおける本番仕様の定義
　プラン更新用サーバーアクションの作成
　必要なshadcn/uiコンポーネントの追加
　チャット画面の書き換え
　チャット画面での動作確認
　COLUMN 本番環境でのプラン管理と決済サービスの連携
　COLUMN 生成AIサービスの主な課金形態

■第9章 画像生成アプリを作って学ぶガードレールとAgent Skills

9.1　ガードレールの概要
　ガードレールとは
　AIエージェントにおけるガードレールの役割
　COLUMN ガードレールを欠いた商用AIサービスの代償
9.2　ガードレールの全体像
　実装後のイメージ
　実装方針と採用技術
　COLUMN 「プロンプトインジェクション」という言葉の変遷
　アーキテクチャ概要
　実装手順
9.3　ガードレールの実装
　チャット応答エージェントの書き換え
　COLUMN Gemini APIでプロンプトのトークン数を確認する
　開発サーバーの起動とチャット画面での動作確認
9.4　Agent Skillsの概要
　Agent Skillsとは
　AIエージェントにおけるAgent Skillsの役割
9.5　Agent Skillsの全体像
　実装後のイメージ
　実装方針と採用技術
　アーキテクチャ概要
　実装手順
9.6　Agent Skillsの実装
　各プランにおける画像生成モデルの定義
　画像生成ツールの作成
　スキルディレクトリの構造設計
　SKILL.mdファイルの作成
　chalkboard-anime.mdファイルの作成
　extreme-wide-angle.mdファイルの作成
　チャット応答エージェントの書き換え
　チャット応答用APIルートの確認
　チャット画面での動作確認
9.7　生成画像表示UIの作成とAPIの呼び出し
　チャットパネルコンポーネントの作成(1)―ツール描画機能の実装
　チャットパネルコンポーネントの作成(2)―チャット機能の実装
　チャット画面の書き換え
　チャット画面での動作確認
　COLUMN 開発時に使うスキルと実行時に使うスキル

■第10章 画像生成アプリを作って学ぶメモリ機能とスレッド機能

10.1　メモリ機能の概要
　AIエージェントの記憶に関する課題と解決法
　さまざまなメモリ機能
10.2　メモリ機能の全体像
　実装後のイメージ
　COLUMN ストレージプロバイダーの選び方
　実装方針と採用技術
　アーキテクチャ概要
　実装手順
10.3　一般記憶の概要
　一般記憶とは
　AIエージェントにおける一般記憶の役割
10.4　一般記憶の実装
　メモリパッケージのインストール
　メモリ定義ファイルの作成
　チャット応答エージェントの書き換え
　チャット応答用APIルートの書き換え(1)―メッセージ保存機能の実装
　チャット応答用APIルートの書き換え(2)―過去メッセージ取得機能の実装
　スレッド一覧取得・作成用APIルートの作成
　スレッド削除用APIルートの作成
　開発サーバーの起動と動作確認
10.5　スレッド管理UIの作成とAPIの呼び出し
　必要なshadcn/uiコンポーネントの追加
　スレッド一覧サイドバーコンポーネントの作成
　チャット画面の書き換え
　チャットパネルコンポーネントの書き換え
　チャット画面の動作確認
10.6　スレッドタイトル自動生成機能の概要
　スレッドタイトル自動生成とは
　AIエージェントにおけるスレッドタイトル自動生成機能の役割
10.7　スレッドタイトル自動生成機能の実装
　メモリ定義ファイルの書き換え
　スレッド取得APIルートの作成
　APIの動作確認
10.8　タイトル更新UIの作成とAPIの呼び出し
　チャット画面の書き換え
　チャットパネルコンポーネントの書き換え
　チャット画面での動作確認
10.9　ワーキングメモリの概要
　ワーキングメモリとは
　AIエージェントにおけるワーキングメモリの役割
10.10　ワーキングメモリの実装
　メモリ定義ファイルの書き換え
　チャット応答エージェントの書き換え
　チャット画面での動作確認
10.11　セマンティックリコールの概要
　セマンティックリコールとは
　AIエージェントにおけるセマンティックリコールの役割
10.12　セマンティックリコールの実装
　メモリ定義ファイルの書き換え
　チャット画面での動作確認
　COLUMN テンポラルナレッジグラフとAIエージェントの長期記憶
　COLUMN オブザーベショナルメモリ

■第11章 画像生成アプリを作って学ぶオブザーバビリティとAIエージェント評価

11.1　オブザーバビリティの概要
　オブザーバビリティとは
　AIエージェントにおけるオブザーバビリティの役割
　トレースデータを外部システムに送信する2つの方法
　COLUMN オブザーバビリティと評価を包含する概念「LLMOps」
11.2　オブザーバビリティの全体像
　実装後のイメージ
　実装方針と採用技術
　アーキテクチャ概要
　実装手順
11.3　Mastra Studioによるオブザーバビリティの確認
　Mastraオブザーバビリティパッケージのインストール
　MastraインスタンスへのMastraStorageExporterの登録
　開発サーバーの起動とMastra Studioでの動作確認
11.4　Langfuseによるオブザーバビリティの実装
　Langfuseパッケージのインストール
　Public KeyとSecret Keyの作成
　.envファイルへのPublic KeyとSecret Keyの追加
　MastraインスタンスへのLangfuseの登録
　画像生成ツールの書き換え
　COLUMN Langfuseのクラウド版とセルフホスティング版の選び方
　開発サーバーの起動とLangfuseでの動作確認
11.5　AIエージェント評価の概要
　AIエージェント評価とは
　AIエージェントにおけるAIエージェント評価の役割
　バッチ評価（データセット評価）とライブ評価とは
11.6　AIエージェント評価の全体像
　実装後のイメージ
　実装方針と採用技術
　アーキテクチャ概要
　実装手順
11.7　Mastraによるバッチ評価の実装
　Evalsパッケージのインストール
　メモリ定義ファイルの書き換え
　評価スクリプトの作成
　評価スクリプトの実行と動作確認
　COLUMN LLMスコアラーとコード/NLPスコアラーの違い
11.8　Mastraによるライブ評価の実装
　チャット応答エージェントの書き換え
　Mastra Studioでの動作確認
11.9　Langfuseによるライブ評価の実装
　画像生成ツールの書き換え
　チャット画面からのテストデータ送信
　LangfuseへのLLMモデルの登録
　カスタムEvaluatorの作成
　Evaluatorの設定と有効化
　Langfuseでの動作確認
11.10　評価フレームワークの使い分け
　他の評価フレームワーク
　得意分野を活かした選択
　COLUMN Langfuseをもっと現場に組み込む4つの仕掛け

■第12章 画像生成アプリを作って学ぶデプロイ

12.1　デプロイの概要
　デプロイとは
　デプロイ環境の使い分け
　デプロイの自動化（CI/CD）
　Mastraサーバーの仕組み
　デプロイ先の選択肢
12.2　デプロイの全体像
　実装後のイメージ
　実装方針と採用技術
　アーキテクチャ概要
　実装手順
12.3　Tursoのセットアップ
　Tursoにおける接続URLとトークンの作成
　認証インスタンスの書き換え
　マイグレーションの実行
　Mastraインスタンスの書き換え
　メモリ定義ファイルの書き換え
12.4　Vercel Blobのセットアップ
　Vercel Blobのインストール
　画像生成ツールの書き換え
12.5　Vercelへのデプロイ実施
　GitHubリポジトリとの連携
　COLUMN VercelプランとAIアプリの相性
　Vercelダッシュボードでの環境変数設定
　デプロイの実行と動作確認

■第13章 さまざまなクラウド環境へのデプロイ

13.1　Mastra Serverへのデプロイ
　Mastra Serverとは
　Mastra Serverの料金プランと制約
　Mastra Serverへのデプロイ方法
　COLUMN GitHub ActionsからのCI/CDデプロイ
13.2　Cloudflareへのデプロイ
　Cloudflare Workersとは
　Cloudflare Workersの料金プランと制約
　Cloudflare Workersへのデプロイ方法
　COLUMN Workers AIでCloudflareのモデルを使う
13.3　AWSへのデプロイ
　Amazon Bedrock AgentCoreとは
　Amazon Bedrock AgentCoreの料金プランと制約
　Amazon Bedrock AgentCoreへのデプロイ方法
　COLUMN AWS Amplify Gen 2とAgentCoreの組み合わせ
13.4　Azureへのデプロイ
　Azure Container Appsとは
　Azure Container Appsの料金プランと制約
　Azure Container Appsへのデプロイ方法
　COLUMN Microsoft Foundry Agent Serviceとの違い
13.5　Google Cloudへのデプロイ
　Cloud Runとは
　Cloud Runの料金プランと制約
　Cloud Runへのデプロイ方法
　COLUMN Agent Runtimeとの違い
　COLUMN デプロイ環境におけるデータ永続化

■付録 各種サービスの使用方法

付録A　GitHub Codespacesの準備
　GitHubアカウントの作成
　GitHubリポジトリの作成
　Codespacesの起動
付録B　Google AI Studio APIキーの取得
　Google AI Studioへのアクセス
　APIキーの生成
　Google AI Studioの課金設定
付録C　Tavily APIキーの取得
　Tavilyアカウントの作成
　APIキーの取得

索引
著者プロフィール