Mastra：TypeScriptでエージェントとワークフローを同じ枠に収める

Mastraが埋めようとしている穴は何か

TypeScriptでAIアプリを作るとき、LLM呼び出しそのものはSDKで足りる。足りなくなるのは、その呼び出しの周辺だ。会話履歴をどこに保持し、ツールをどう登録し、複数ステップの処理の途中で人間の承認を挟み、失敗した実行をどこから再開するか。Mastraはこの周辺を1つのフレームワークにまとめようとしている。READMEは「TypeScriptと、確立されたAIパターンを前提に設計されている」と述べ、対象をプロトタイプから本番アプリまでと位置づけている。

想定読者は、ReactやNext.js、Node.jsのアプリを持ち、そこにエージェント機能を足したい開発者だ。PythonのMLスタックではなく、既存のTypeScriptコードベースと同じ言語でエージェントを書きたいという動機が前提にある。READMEが挙げる統合先もReact、Next.js、Node.jsで、単体のサーバーとしてもデプロイできるとされている。フロントエンドの隣に置けることを重視した構成だと言える。

エージェントとワークフローという2つの実行モデル

Mastraの中心にあるのは、性質の異なる2つの実行モデルだ。1つはエージェントで、READMEによればLLMとツールを使って目標を推論し、どのツールを使うかを自分で決め、モデルが最終回答を出すか任意の停止条件を満たすまで内部で反復する。制御の主体はモデル側にある。

もう1つはワークフローで、こちらは実行の制御を明示的に握りたいときに使う。READMEはグラフベースのワークフローエンジンと説明し、制御フローの構文として.then()、.branch()、.parallel()を挙げている。分岐と並列実行がメソッド呼び出しとして書けるので、処理の形がコード上で追いやすい。エージェントに任せると経路が読めないが、ワークフローなら読める。この使い分けがMastraの設計の軸になっている。

両者をつなぐのが人間の承認だ。READMEはワークフローの中断と再開のページを参照し、実行状態をstorageに保存することで無期限に停止し、止めた場所から再開できるとしている。承認待ちの間にプロセスが落ちても状態が残る、という前提の設計である。

モデルルーティングとコンテキストの置き場所

モデル接続は40以上のプロバイダを1つの標準インターフェースで扱うとREADMEは説明している。OpenAI、Anthropic、Geminiなどのモデルを同じ書き方で呼べるという意味で、プロバイダを差し替えるたびに呼び出しコードを書き直す必要を減らす。ただしREADMEが挙げるのはプロバイダ数であって、抽象化がどの程度まで各社固有の機能を吸収するかは記述からは読み取れない。プロバイダ固有のパラメータを使いたい場合は、抽象化の外に出る必要があると考えておいたほうがよい。

コンテキスト側は3つの層に分かれている。会話履歴、APIやデータベース、ファイルからの取得（RAG）、そしてObservational Memoryと呼ばれる人間の記憶に近い仕組みだ。READMEはこれらを「適切なタイミングで適切なコンテキストをエージェントに与える」ための要素として並べている。取得元を自分で用意し、それをエージェントに渡す配線をフレームワーク側が持つ、という分担である。

MCPサーバーの作成も範囲に含まれる。エージェントやツールをModel Context Protocol経由で公開し、プロトコルに対応した他のシステムやエージェントから呼び出せるようにする。Mastraを中心に据えるのではなく、Mastra側を部品として外に差し出す方向の機能だ。

立ち上げのコマンドとStudio

READMEが推奨する開始手順はnpm create mastra@latestの1行だ。プロジェクト名とプロバイダを指定する形の例として、npm create mastra@latest <project-name> -- --llm <provider>が示されている。プロバイダはopenai、anthropic、google、xaiの4つが選択肢として挙げられている。

生成されたプロジェクトでは、検出されたコーディングアシスタント向けにMastraのスキルがインストールされ、適切な場合はGitの初期化も行われるとREADMEは説明している。開発サーバーはnpm run devで起動し、READMEの例ではnpx bgproc start -n <project-name> -w -- npm run devという形でバックグラウンド起動している。起動後、Mastra Studioがhttp://localhost:4111で開く。Studioはエージェント、ワークフロー、ツールを構築、テスト、管理するための画面だと説明されている。

手動インストールの手順も用意されている。CLIを使わずに依存関係を自分で管理したい場合や、既存リポジトリの構成に合わせたい場合はそちらを参照することになる。なお、これらのコマンドが生成する具体的なファイル構成や設定キーは、READMEの抜粋からは確認できない。実際に生成物を見て確かめる必要がある。

向かない場面：単発の呼び出しとPython資産

Mastraが過剰になる場面ははっきりしている。アプリの数か所でLLMを呼び、結果を表示するだけなら、プロバイダのSDKを直接使うほうが構成は小さい。storageの設定、エージェントの定義、ワークフローのグラフといった概念を先に覚える必要があり、その分の学習と保守が発生する。エージェントが内部で反復する挙動も、単発の呼び出ししかしない用途では使いどころがない。

もう1つの境界は言語だ。MastraはTypeScriptのフレームワークであり、既存の資産がPython側にある場合、モデルの学習や評価のパイプラインをそのまま持ち込むことはできない。READMEが挙げる統合先はReact、Next.js、Node.jsに限られている。TypeScriptのアプリを持たないチームが、MastraのためにTypeScriptを選ぶ理由は、この資料からは見えてこない。

3つ目は抽象化の漏れだ。40以上のプロバイダを1つのインターフェースで扱う以上、各プロバイダ固有の新しい機能は抽象化を経由しないと使えない期間が生じる。最先端のモデル機能をすぐ試したい用途では、SDKを直接叩く経路を併用することになる。

Vercel AI SDKとの違いは制御の持ち主

比較対象としてREADME自身が名前を挙げているのがVercelのAI SDK UIだ。MastraはこれをUI側の統合先として扱っており、対立するものではなく組み合わせるものという位置づけになっている。CopilotKitも同様に挙げられている。

両者の違いは制御の持ち主にある。AI SDKはストリーミングやツール呼び出しをUIに届けるためのプリミティブを提供する。Mastraはその上に、エージェントの反復、ワークフローの分岐と並列、storageに支えられた中断と再開、evalとobservabilityを載せようとしている。UIに近い層を薄く保ちたいならAI SDKのプリミティブだけで足りる。多段の処理とその状態管理をフレームワークに預けたいならMastra側の機能が必要になる。

判断の目安は、実行の途中で止めて人間の承認を待つ必要があるかどうかだ。この要件がないなら、Mastraのワークフローとstorageを持ち込む理由は薄い。

二重ライセンスと保守コストの読み方

ライセンスはApache License 2.0とMastra Enterprise Licenseの二重構造だとREADMEは説明している。コアフレームワークとコードベースの大部分はApache-2.0で、ee/という名前のディレクトリに入っているコード（例としてpackages/core/src/auth/ee/が挙げられている）はMastra Enterprise Licenseの下でsource-availableとなり、本番利用には有効なエンタープライズライセンスが必要だが、開発とテストでは自由に使えるとされている。ライセンスの対応関係の全体はLICENSE.mdに、ee/側の条件はee/LICENSEに記載されている。

ここで注意すべきは、リポジトリのライセンス表示がNOASSERTIONになっている点だ。単一のSPDX識別子では表現できない二重構造であることの現れで、ライセンススキャナやSBOMの生成時に、どのファイルがどちらに属するかを機械的に判定できない可能性がある。ee/配下に依存する機能を設計に組み込むと、後からApache-2.0だけの構成に戻すコストが生じる。法務判断はここでは扱わないが、採用前にLICENSE.mdのマッピングを読んでおく価値はある。

保守の面では、リリースの刻みが判断材料になる。@mastra/coreは1.63.0、1.64.0、1.65.0がそれぞれ2026年8月26日、9月3日、9月9日付で並んでおり、週次に近い間隔で更新されている。活発である一方、追従する側はバージョン間の差分を確認し続ける前提で臨むことになる。1.0を超えたメジャー系列であるとはいえ、この速度は安定を優先するチームには負担になりうる。

編集部の結論

導入を検討すべきなのは、TypeScriptのモノレポにエージェント機能を組み込み、会話履歴やRAGの取得元を自分で管理しつつ、人間の承認を挟む多段処理まで同じ枠で扱いたいチームだ。逆に、単発のLLM呼び出しを数か所に足すだけの用途や、Python側のML資産をそのまま使いたい案件では、フレームワークを挟む分だけ構成が重くなる。最初に確認すべきは、packages/core/src/auth/ee/のようなee/配下のコードを本番で使う予定があるかどうかで、ここに依存する設計にするとApache-2.0だけでは完結しない。次に、npm create mastra@latestで生成される既定プロジェクトが自分のリポジトリ構成と衝突しないかを、実際の生成物で確かめてから採用を決めればよい。

公式情報源

1. Issues
2. mastra-ai/mastra on GitHub
3. Project website
4. README
5. Releases