Mastraとは｜TypeScript製AIエージェントフレームワークの使い方

MastraとはTypeScriptでAIエージェントを組むフレームワーク

結論として、Mastraは「LLMにどう喋らせるか」ではなく「LLMを含んだ処理の流れをどう設計するか」を担当します。公式ドキュメントでは、AIエージェントとアプリケーションを構築するためのTypeScriptフレームワークと定義されています。

条件としては、プロジェクトがNode.js環境であること。本記事で確認した公式クイックスタートはNode.js 22.18.0以降を前提としており、このバージョン帯ではNode.js側の型注釈の取り扱いによって、別途トランスパイル手順を挟まずにTypeScriptファイルを起動できる構成が取れます。実際にどこまで追加設定なしで動くかは、Node.jsのバージョンと実行方法に依存します。例外として、チームの主力言語がPythonで、既存の推論パイプラインもPython側にある場合は、無理にTypeScript側へ寄せる理由は薄くなります。

「LLMを呼ぶSDK」との役割の違い

AI開発のライブラリは、大きく2つのレイヤーに分かれます。混同したまま選ぶと、あとから重複実装が発生します。

Mastraは後者です。モデルへの実際のリクエスト自体は、下位のSDKやモデルルーター経由で行われます。つまり、Vercel AI SDKとMastraは置き換え関係ではなく、積み重ね関係になりうるということです。

そもそもAIエージェントという概念自体が曖昧なまま進めると設計が揺れます。前提を整理したい場合はAIエージェントとは？仕組み・種類・活用事例をわかりやすく解説を先に読むと、以降の話が入りやすくなります。

公開状況とライセンス

技術選定で確認すべきは、開発が続いているかどうかです。以下は2026年11月15日に確認した値で、対象はGitHubの公式リポジトリ mastra-ai/mastra と、npmパッケージ @mastra/core です。

スター数とフォーク数はGitHubリポジトリ、バージョンの公開日はリリース一覧、ダウンロード数はnpmが公開しているパッケージ別のダウンロード統計で確認しました。ダウンロード数はCI実行やミラーによる取得も含む指標で、実利用者数とは一致しません。いずれも日々変動するため、採用判断の際は公式ページで最新値を見てください。

ライセンスはApache-2.0ですが、リポジトリ内のee配下（エンタープライズ向けの一部機能）には別の条項が適用されます。社内規程でOSSライセンスの確認が必要な場合は、ルート直下のLICENSEファイルを読む前提で進めてください。

ミニFAQ：MastraはPythonでも使えますか

Mastra本体は、本記事の確認時点ではnpmパッケージとして配布されるTypeScript／JavaScript向けのフレームワークで、pipで導入して同じように使う形では提供されていません。Python側の処理と組み合わせたい場合は、Python側をAPIとして切り出してツールから呼ぶ構成が現実的です。チームの主力がPythonであれば、LangGraphとは｜LangChainとの違い・エージェント構築の基本で扱っているような選択肢を検討することになります。

Mastraの構成要素｜エージェント・ツール・ワークフロー・メモリ・RAG

Mastraは、よく使う部品をそれぞれ独立したプリミティブとして提供します。全部を最初から使う必要はありません。エージェントとツールだけで動く最小構成から始め、必要になった順にメモリ・ワークフロー・評価を足すのが現実的です。

エージェントとツール

エージェントは、Agentクラスのインスタンスとして定義します。主な構成要素は次のとおりです。

• id／name：エージェントの識別子と名称

• instructions：システムプロンプトにあたる指示文。役割や制約をここで固定する

• model：プロバイダ名とモデル名を「provider/model」形式の文字列で指定する

• tools：エージェントが呼び出せる関数の集合（任意）

• memory：会話の記憶を保持する設定（任意）

モデル指定では、プロバイダのオブジェクトをインポートせず文字列で書く点が特徴です。Mastra側のモデルルーターが、OPENAI_API_KEYやANTHROPIC_API_KEYといった環境変数を参照します。鍵の置き場所が環境変数に寄るため、設定の散らばりは起きにくくなります。対応プロバイダの顔ぶれはバージョンによって変わるので、使いたいモデルがある場合は公式ドキュメントの対応一覧を確認してください。

実行メソッドは2種類。generateは処理が完了してから結果をまとめて返し、応答テキストのほかツール呼び出し・中間ステップ・トークン使用量を含みます。streamはトークンが届くたびに逐次返します。チャットUIを持つならstream、バッチ処理ならgenerateという使い分けになります。

ツールは、エージェントから呼ばれる関数です。入出力にスキーマを与えるため、LLMが壊れたJSONを返したときに型の段階で弾ける構造になっています。この挙動の前提はLLMの構造化出力とは｜JSON出力とFunction Callingの使い分けで整理しています。

ワークフローとsuspend／resume

エージェントに全部を任せると、処理の順序が毎回変わります。順序を固定したい業務では、ワークフローを使います。

createStepで1ステップを定義し、createWorkflowで連結し、commitで確定する流れです。各ステップにはinputSchemaとoutputSchemaを付けるため、ステップ間の受け渡しが型でつながります。スキーマライブラリはZodのほかValibotやArkTypeにも対応しており、内部的にはJSON Schemaに揃えられます。

制御フローは、逐次実行に加えて並列実行・条件分岐・ループを組めます。実行はrun.startで完了まで待つか、run.streamで進捗を追うかを選べます。詳細はワークフローの公式ドキュメントに手順があります。

実務で効くのはsuspendとresumeです。途中で処理を止めて人間の承認を待ち、承認後に同じ実行を再開できます。請求データの更新や外部への送信など、自動実行させたくない工程がある業務では、この機能の有無が設計を左右します。承認を挟む設計そのものの考え方はAIエージェントの権限設計｜最小権限とHuman-in-the-loopの実装が詳しいです。

メモリの3層

Mastraのメモリは、役割の違う3つが重なっています。

全部を有効にすると、毎回のリクエストに乗るトークンが増えてコストが膨らみます。クイックスタートではストレージにLibSQLが使われますが、本番ではPostgreSQLなど運用中のデータベースに寄せる判断が一般的です。層の切り分け方はAIエージェントのメモリ設計｜短期記憶と長期記憶の実装パターンと合わせて読むと設計しやすくなります。

RAG・評価・可観測性

社内ドキュメントを参照させる場合は、RAGの機能を使います。文書の取り込み、チャンク分割、埋め込みの保存、クエリ時の検索までを同じフレームワーク内で扱えます。RAG自体の仕組みはRAGとは？仕組み・活用事例・導入メリットをわかりやすく解説を参照してください。

評価機能では、エージェントの出力に対してスコアを付けられます。テストランナーから回せるため、プロンプトを変えたときの劣化をCIで検知する運用が組めます。評価指標の設計はLLM評価（Evals）とは｜LLM-as-a-Judgeと品質保証の実務まで解説が参考になります。

可観測性としては、トレース・ログ・メトリクスを収集できます。外部のトレース基盤に流す構成も取れるため、Langfuse・LangSmithの使い方｜LLMトレース管理と選び方で扱っているツールと併用する選択肢もあります。

Mastraの使い方｜4ステップで最小構成を動かす

公式のクイックスタートは4つの段階に分かれます。エージェント1体とツール数個であれば、追加のインフラを用意せずローカルだけで一通り確認できます。

ステップ1：前提環境とプロジェクト作成

本記事で確認した公式クイックスタートの前提はNode.js 22.18.0以降です。実際に必要なバージョンは利用するMastraのリリースによって変わるため、着手前に公式ドキュメントの要件を確認してください。

プロジェクトの雛形は npm create mastra@latest で生成します。pnpm、Yarn、Bunにも対応しています。対話形式でプロバイダを選ぶと、必要な依存とディレクトリ構成が用意されます。

ステップ2：エージェントを定義する

生成されたプロジェクトのエージェント定義ファイルを開き、instructionsとmodelを書き換えます。ここで決めるのは、そのエージェントが何をする係なのかという役割の線引きです。

instructionsに業務ルールを詰め込みすぎると、応答が不安定になります。判断基準を箇条書きで3〜5項目に絞り、細かい処理はツール側に逃がすほうが、あとで直しやすい構成になります。

ステップ3：ツールとワークフローを組む

外部APIの呼び出しやデータベース参照は、ツールとして切り出します。入出力スキーマを先に書いてから中身を実装すると、エージェント側との接続で迷いません。

処理の順序を固定したい部分が出てきたら、ワークフローに移します。分岐が3つ以上に増えた段階で切り替える、という線引きは公式の仕様ではなく、挙動を追える範囲を保つための実務上の目安です。扱う業務の複雑さに応じて調整してください。複数のエージェントを協調させる構成に進む場合はマルチエージェントとは｜設計パターン5つと単一エージェントの違いが参考になります。

ステップ4：Studioで確認してデプロイする

Mastraには、エージェントやワークフローを画面上で実行し、トレースを確認できるStudioが用意されています。プロンプトを変えながら挙動を見る工程は、ここで回すのが早いです。

デプロイの選択肢は3通りです。mastra buildで成果物を作ってVM・コンテナ・PaaSに置く方法、Vercel・Netlify・Cloudflareなどサーバーレスへ配置する方法、そしてMastra Platformを使う方法です。Mastra Platformは可観測性・Studio・APIサーバーをまとめて提供するホスティングサービスで、自前で運用基盤を組まない場合の選択肢になります。既存のNext.jsやAstroのアプリに統合する場合は、そのフレームワーク側の通常のデプロイ手順に乗ります。

ミニFAQ：既存のNext.jsアプリに後から入れられますか

入れられます。別サービスとして立てる必要はなく、同じリポジトリ内にエージェント定義を置いてAPIルートから呼ぶ構成を取れます。この「同じリポジトリ・同じ型定義のまま足せる」点が、Mastraを選ぶ最大の理由になるケースが多いです。TypeScript側の周辺構成はTypeScript開発環境2026｜Hono・Prisma・Zodで組むモダンスタックでまとめています。

Vercel AI SDK・LangGraph・OpenAI Agents SDKとの違い

結論から言うと、比較すべきは機能の多さではなく「どのレイヤーを引き受けるか」と「主力言語が何か」です。

役割レイヤーで整理する比較表

参考までに、同じ期間（2026年11月7〜13日）のnpm週次ダウンロード数は、Vercel AI SDKのaiが約4,532万、@langchain/langgraphが約499万、@mastra/coreが約323万、@openai/agentsが約234万でした。ダウンロード数は用途も粒度も異なるパッケージ間の比較であり、品質や適合度を示す指標ではありません。利用規模の大まかな感覚をつかむ材料として見てください。

各ツールの中身は、AIエージェント開発フレームワーク比較｜LangGraph・CrewAI・AutoGenとOpenAI Agents SDKとは｜使い方とLangGraphとの違いで個別に扱っています。

Mastraを選ぶ条件・選ばない条件

選ぶ条件は3つです。

1. プロダクトの主力言語がTypeScriptで、フロントとバックで型を共有している

2. 単発の生成では終わらず、ツール実行・分岐・承認待ちを含む流れを作る必要がある

3. エージェントの出力品質をテストで担保したい

選ばない条件も明確です。チャット画面を1つ作るだけなら、SDK単体のほうが構成がシンプルに収まります。既存の機械学習パイプラインがPythonで動いていて、その延長でエージェントを組むなら、Python側のフレームワークに寄せたほうが運用の分断が起きません。「TypeScriptで書けるから」だけを理由に選ぶと、推論まわりの資産が二重管理になります。

ケース別の使いどころ

既存のNext.jsプロダクトにAI機能を足す

もっとも素直な使い方です。既存のAPIルートからエージェントを呼び、Zodで定義済みのスキーマをそのままツールの入出力に流用できます。認証やデータベース接続も既存のものを使い回せるため、AI用に別サービスを立てる構成と比べて、運用対象が増えません。

社内業務の多段処理を自動化する

問い合わせの分類、担当への振り分け、下書き生成、人間の承認、送信という流れをワークフローで組む形です。承認工程をsuspendとresumeで表現できるため、全自動にできない業務を部分的に自動化する設計に向きます。社内文書を参照させる場合はRAGの機能を併用します。

Python資産が中心のチーム

この場合は見送りを検討する場面です。前処理や評価のスクリプトがPythonに揃っているなら、エージェント層だけTypeScriptに分けると、デプロイ先もテストの書き方も二系統になります。判断の軸は言語の好みではなく、運用する人数と監視対象の数です。

実務で詰まりやすい4つのポイント

バージョン追従のコスト

これが最初の関門です。@mastra/coreは直近30日で6回（1.78.0から1.83.0）、直近90日では26回の安定版が公開されています。更新頻度が高いこと自体は開発が活発である証拠ですが、本番運用ではバージョンを固定し、アップデート時に差分を確認する前提で計画を立ててください。

古いバージョンに留め置く判断をする場合は、依存する下位SDKやNode.js本体のサポート期限も併せて確認が必要です。サポート対象外のバージョンを使い続けると、脆弱性の修正が降ってこない状態になります。

メモリとトークンコストの膨張

3つのメモリ層をすべて有効にすると、毎回のリクエストに乗る文脈が増えます。セマンティックリコールの取得件数を絞る、ワーキングメモリに入れる項目を決め打ちにする、といった制限を先に入れておくほうが安全です。

評価を省いたまま本番に出す

プロンプトを1行変えただけで、別のケースの出力が崩れることがあります。評価セットを作らずにリリースすると、劣化に気づくのが問い合わせ経由になります。最小でも、代表的な入力パターンに対する期待出力を用意し、テストから回せる状態にしておくことをおすすめします。

権限と人の承認の設計漏れ

エージェントにツールを渡すとき、そのツールが何を書き換えられるかを棚卸ししないまま進めると、想定外の操作が通ります。読み取り専用のツールと書き込みを伴うツールを分け、後者には承認を挟む構成にしてください。

フリーランス案件から見たMastra

案件票での出方

公開されている案件を見る限り、「Mastra」をフレームワーク名で指名する募集はまだ多くありません。実際には、言語欄にTypeScriptとPythonが併記され、案件詳細の側に「LLM連携」「エージェント開発」「RAG構築」といった記述が置かれる形が中心です。

つまり、Mastraそのものの知名度で案件が取れるという構図ではなく、TypeScriptでの実装力とLLMアプリの設計経験をセットで示せるかどうかが評価軸になります。AIエージェント開発案件の全体像はAIエージェント開発案件の単価相場｜必要スキル・獲得ルートを解説にまとまっています。

掲載案件から見た単価の目安

以下の表は、フリコンに掲載した案件を「AIエンジニアという職種」で集計した値と、「TypeScriptというスキルタグ」で横断集計した値を並べたものです。前者は職種単位、後者は職種をまたいだタグ単位であり、母集団の性質が異なります。後者が前者の内訳ではありません。いずれも2026年11月15日時点の集計で、募集終了分を含む累計、単価は募集時の月額上限を用いた集計値です。成約単価ではありません。

この2行から読み取れるのは、案件数はTypeScript側が圧倒的に多い一方、月100万円以上の比率はAIエンジニア職種のほうが高いという傾向です。ただし両者は案件のレイヤーも職種構成も異なるため、この差がそのままスキルの優劣や「AI領域に移れば単価が上がる」ことを示すわけではありません。

実務経験3年以上のWeb系エンジニアが、TypeScriptでの実装経験に加えてLLM連携やRAG構築の経験を提示できる場合、上の2つの集計の中間からAIエンジニア側のレンジで声がかかるケースが見られます。自分の経歴でどのあたりを狙えるかを確認したい方は、無料のフリーランスエンジニア単価診断で現在の市場単価の目安を把握できます。単価を体系的に上げる考え方は【2026年最新版】フリーランスエンジニアの単価相場と単価の上げ方とは？で整理しています。

AIエンジニアの募集中案件はAIエンジニアのフリーランス案件一覧から確認できます。複数の案件で迷ったときの優先順位の付け方は案件の選び方｜フリーランスエンジニアが単価・稼働・スキルで決める優先順位が使えます。

スキルシートでの書き方

フレームワーク名を並べるより、処理の構造と規模を数字で書くほうが伝わります。「Mastra使用」ではなく、「エージェント3体とツール12個で構成した社内問い合わせ処理を実装。承認待ちを挟む5ステップのワークフローを設計し、評価セット40ケースで回帰テストを自動化」といった粒度です。

TypeScript軸での単価の考え方はTypeScriptフリーランスの単価相場と案件の探し方｜経験別・年収の実態にまとめています。

導入前チェックリスト

採用を決める前に、この7項目を確認してください。1つでも「いいえ」が残るなら、構成を見直す余地があります。

ライセンス条項の確認が必要な組織では、ee配下の扱いについても事前に社内のルールと突き合わせておくと安全です。

まとめ

MastraはTypeScriptのプロダクトにAI機能を同居させたいチーム向けのフレームワークで、単発の生成で終わらない処理を組み立てる段階から価値が出ます。

• 担当するのは呼び出しレイヤーではなく組み立てレイヤー。エージェント・ツール・ワークフロー・メモリ・RAG・評価を型の上で扱う

• 動作要件はNode.js 22.18.0以降。npm create mastra@latest から最小構成を試せる

• suspendとresumeによる承認待ちは、全自動にできない業務を部分的に自動化する設計で効く

• 更新は速く、@mastra/coreは直近30日で安定版が6回公開されている。バージョン固定を前提に計画する

• チャット画面1つならSDK単体、Python資産が中心ならPython側のフレームワークという見送り判断も持っておく

• 案件ではフレームワーク名の指名より、TypeScriptの実装力とLLMアプリの設計経験の組み合わせが評価される

• スキルシートには製品名ではなく、エージェント数・ステップ数・評価ケース数を書く

次のステップとしては、既存プロジェクトのNodeバージョンを確認し、エージェント1体とツール2〜3個の最小構成をローカルで動かすところから始めるのが現実的です。そのうえで、承認待ちが必要な工程があるかを洗い出すと、ワークフローへ進むかどうかの判断がつきます。

参照した一次情報は次のとおりです。

• Mastra公式ドキュメント

• Mastra ワークフロー概要（公式ドキュメント）

• mastra-ai/mastra（GitHubリポジトリ）

• Mastra リリース一覧（GitHub Releases）

• npmが公開するパッケージ別ダウンロード統計（@mastra/core、ai、@langchain/langgraph、@openai/agents／2026年11月7〜13日分）