mastra-ai/mastra — 優良食堂詳しい解説

01 / 概要

何をするものか一文で言うと

ひとことでTypeScriptベースのAIエージェント・ワークフロー構築フレームワーク。プロトタイプから本番運用まで対応。

Mastraは、TypeScriptでAIエージェントやワークフローを構築するためのフレームワークです。エージェント・ツール・メモリ・RAG・評価・オブザーバビリティ・MCPなどの機能を、pnpmワークスペースの単一モノレポ内に個別パッケージとして提供しています。CLIの `mastra dev` でローカル開発サーバーとStudio UIが立ち上がり、REST API経由でエージェントを呼び出せます。

02 / 構造

どう動くのか中核のしくみ

読み方動きの流れを図と一緒にほどきました。

中核は `@mastra/core` の `Mastra` クラスです。ここにagents・tools・workflows・storage・workspace・observability・editor・server(auth/rbac)をまとめて登録します。エージェントは `Agent` クラスにai-sdk経由のモデル(例: `openai gpt-4o-mini`)と指示文を渡して作り、ツールは `createTool` でzodスキーマ付きの関数として定義します。`mastra dev` を実行すると、この定義がローカルサーバーとして立ち上がり、`/api/agents/<agentKey>/generate` のようなエンドポイントで応答を返します。ストレージは `LibSQLStore` などを差し替え可能で、`.dev/docker-compose.yaml` にはpgvector・Qdrant・Redisなどベクトル検索やキャッシュ用の周辺サービスが用意されています。認証は `MastraAuthWorkos` と `MastraRBACWorkos` のようなプラガブルなプロバイダで、role単位の権限(read/write/execute)を制御します。リリースはchangesetsで管理し、`.changeset/` 配下に多数の変更履歴ファイルがあることから、パッケージ単位のバージョニングが継続的に運用されていることが分かります。

03 / 体験

入れるとこんな体験になりますギット飯が実際にたどった順序

所要ギット飯が実際に導入・実行しながらたどった順序です。

STEP 01
リポジトリをクローンし `pnpm install` を実行すると、Node.js 22.13以上が要求され、モノレポ全体の依存解決に時間がかかります。
STEP 02
`.claude/skills/builder-smoke-test/assets/template` のようなテンプレートで `mastra dev` を起動すると、`http://localhost:4111` にStudioとAPIサーバーが立ち上がります。
STEP 03
`curl -X POST http://localhost:4111/api/agents/weatherAgent/generate` にメッセージを送ると、天気ツールを呼んだ結果を含む応答がJSONで返ってきます。
STEP 04
続けて `memory: { thread, resource }` を指定した2回目の呼び出しを送ると、前回の会話を踏まえた応答が返るかでメモリ機能を確認できます。
STEP 05
`AUTH_PROVIDER=workos` を設定して再起動すると、WorkOSのRBAC設定によりmember権限では特定リソースの書き込みのみ許可されることが確認できます。
STEP 06
`.dev/docker-compose.yaml` で pgvector・Qdrant・Redisを起動し、ストレージやベクトル検索のバックエンドを差し替えて動作させることができます。

04 / 成果物

何が手に入るのか導入後に手元に残るもの

手元にはローカルで動くAIエージェント開発サーバーが残ります。Studio UIからエージェントのチャットを試したり、REST API経由でエージェント・ツール・ワークフローを呼び出したりできます。ストレージ・認証・オブザーバビリティは差し替え可能な設定として得られ、モノレポ内の各パッケージ(`@mastra/core` `@mastra/memory` `@mastra/editor` など)はchangesetsで個別にバージョン管理された状態で確認できます。

05 / 注意

ここは先に知っておいてください先に知っておくとよいこと

正直なところ誰にでも合うとは言いにくいところです。

テンプレートの `package.json` では `@mastra/core` などが `beta` タグやワークツリー内リンクで参照されており、リポジトリ外でそのまま `pnpm install` しても同じ構成は再現しにくいです。

フル機能を試すにはOpenAI・Anthropic・WorkOS・Browserbaseなど複数のAPIキーが必要で、鍵が揃わないとエージェント応答やブラウザ機能でエラーになります。

`.claude/skills/mastra-smoke-test` 配下の資料は手動QA向けのチェックリストで構成されており、動作確認の多くが自動テストではなく人手のスモークテストを前提にしています。

エディタ機能(builder)やRBACのキャッシュTTLを1msにするなど、スモークテスト用の設定が本番向けの推奨設定とは異なる点に注意が必要です。

06 / 結論

ギット飯の結論食べてみる価値のある一膳か

ギット飯の最終判断優良食堂

TypeScriptとai-sdkのエコシステムに慣れたチームが、エージェント・ワークフロー・メモリ・ストレージを一体で管理したい場合に向いています。ローカル開発サーバー、認証・RBAC、ベクトルDB連携までパッケージ単位で揃っている点は、テンプレートコードとdocker-compose構成、changesetsの運用実績から裏付けられます。ただしbetaタグのパッケージやワークツリー内リンクが多く、フル機能検証には複数の外部APIキーと手動QA手順が必要になるため、実際に動かす前に自分の環境で再現できる構成か確認しておくのが安全です。