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

Mastra（マストラ）は、TypeScript／JavaScriptでAIエージェントを組み立てるためのオープンソースフレームワークです。ノーコードのGUIツールでも、Pythonのライブラリでもありません。コードでエージェントを書き、ツール・ワークフロー・メモリ・RAGといった機能を型安全に組み合わせられる点が特徴で、開発元はGatsbyを生んだチームです。本記事は、旧来「ドラッグ＆ドロップのノーコードツール」「pip install mastraで導入」と誤解されがちだったMastraの実像を、公式ドキュメントと一次情報にもとづいて整理し直したものです。導入コマンドから中心となる構成要素、主力キーワードである公式機能「Mastra Skills」、メモリ・RAG・デプロイ、そして他フレームワークとの使い分けまでを一気に解説します。

まとめ：Mastraの要点

• MastraはTypeScript製・コードファーストのAIエージェントフレームワーク（開発はGatsby創業チーム）。ノーコードGUIでもPython製でもない。
• 導入はnpm create mastra@latest（Node.js v22.13.0以上）。pip install mastraという導入方法は存在しない。
• 中心となる構成要素はエージェント・ツール・ワークフロー・メモリ・RAG・評価（スコアラー）・MCP連携。
• 主力の「Mastra Skills」は実在の公式機能で、コーディングエージェント向けのSKILL.md（Claude Agent Skills標準）。npx skills add mastra-ai/skillsで追加でき、Claude Code・Cursor・Codex・OpenCodeなどに対応する。
• Vercel AI SDKの上に構築されており、バージョン1.0は2026年1月20日に正式リリース（GA）された。

以下では、各要素を実際のコードと最新の一次情報に沿って掘り下げます。

Mastraとは：TypeScript製の「コードファースト」AIエージェントフレームワーク

Mastraは、LLMを使ったエージェントやAIアプリケーションをTypeScriptで構築するためのフレームワークです。エージェント（自律的にツールを呼ぶAI）、ツール、ワークフロー、メモリ、RAG、評価といった部品が最初から一体で用意されており、これらを@mastra/coreのAPIで宣言的に組み立てます。モデルは100以上のプロバイダー・数千のモデルをopenai/gpt-5.6のような「プロバイダー／モデル」形式の文字列で切り替えられ、プロバイダーごとの個別パッケージを入れ替える必要がありません。

ノーコードGUIツールでもPython製でもない

Mastraを理解するうえで最初に外せないのは、これが「画面上で部品をドラッグ＆ドロップして作るノーコードツール」ではないという点です。エージェントの挙動はTypeScriptのコードとして書き、Gitで管理し、通常のNode.jsアプリケーションとしてデプロイします。公式に配布されているのはnpmパッケージ（@mastra/coreなど）で、pip install mastraのようなPython版は存在しません。検索で「mastra python」と調べる人が一定数いますが、Pythonから使いたい場合は、Mastraが立ち上げるHTTPサーバー（REST）やMCPエンドポイント経由でエージェントを呼び出す形になります。フレームワーク本体をPythonで書くわけではない、と整理できます。

Vercel AI SDKとの関係と役割分担

Mastraはゼロからモデル呼び出しを実装しているわけではなく、Vercel AI SDKの上に構築されています。AI SDKが担うのはモデル呼び出しとストリーミングといった低レイヤーで、Mastraはその上に「永続的なワークフロー」「一級市民としてのメモリ」「評価（Evals／スコアラー）」「RAG」「オーケストレーション」を足します。単純なチャットUIだけならAI SDK単体で足りますが、会話をまたいだ記憶や多段ワークフロー、品質評価まで必要になったときにMastraの層が効いてきます。AI SDKそのものの詳細は現場で使える新バージョン！Vercel AI SDK v6とは？概要と特徴をエンジニア向けに徹底解説を参照してください。

開発元・資金調達・採用企業

Mastraを開発するのは、静的サイトフレームワークGatsbyを立ち上げたチームです（創業者のSam BhagwatはGatsbyの共同創業者）。資金面では2025年10月に1,300万ドルのシード、2026年4月9日にSpark Capital主導で2,200万ドルのシリーズA（累計3,500万ドル）を調達しています。採用企業としてBrex、Sanity、Replit、PayPalなどが公表されており、「新しいだけの実験的ツール」ではなく本番採用が進んでいる点が、フレームワーク選定時の判断材料になります。

Mastraの導入方法：create-mastraでの環境構築と起動

Mastraはスキャフォールド用のCLI（create-mastra）で、動くサンプル込みのプロジェクトを一発で生成できます。前提はNode.jsのv22.13.0以上です。

npm create mastra@latest で雛形を生成する

新規プロジェクトは次のコマンドで作成します。パッケージマネージャに応じて選んでください。

# npm
npm create mastra@latest

# pnpm
pnpm create mastra

# yarn
yarn create mastra

# bun
bunx create-mastra

対話式のセットアップでは、利用するLLMプロバイダー（OpenAI・Anthropic・Groq・Googleなど）、含めるサンプル（エージェント／ワークフロー）、可観測性（テレメトリ）の有無、そして後述のMastra SkillsやMCPドキュメントサーバーを入れるかどうかを選べます。既存プロジェクトへ手で入れる場合は次の通りです。

npm install @mastra/core@latest zod@latest mastra@latest

Pythonの仮想環境やpipは一切登場しません。開発サーバーの起動はmastra dev、本番向けビルドはmastra buildです。

生成されるプロジェクト構成

create-mastraはsrc/mastra配下に、天気エージェントを題材にした一式を作ります。エージェント・ツール・ワークフロー・スコアラーがどこに置かれるかが分かる構成です。

src/mastra/
  index.ts                  # Mastra本体のエントリ
  agents/weather-agent.ts   # エージェント定義
  tools/weather-tool.ts     # ツール定義
  workflows/weather-workflow.ts
  scorers/weather-scorer.ts # 評価（スコアラー）

この雛形をそのまま起動して挙動を確認し、必要な部分を差し替えていくのが最短ルートです。

mastra dev と Studio（localhost:4111）で動作確認する

mastra dev（またはnpm run dev）を実行すると、ローカルの開発UIであるMastra Studioがlocalhost:4111で立ち上がります。Studioではエージェントとチャットしたり、ワークフローをステップ単位で実行・可視化したり、ツールを単体でテストしたり、実行トレースやログを確認できます。REST APIとSwaggerのUIも/swagger-uiで提供されるため、フロントを作る前にAPIとして叩いて挙動を詰められます。「mastra studio」で探しているのは、この開発時のプレイグラウンドです。

用途別テンプレートからの構築

ゼロから書かずに、動作する用途別のサンプル（ドキュメントチャットボット、PDFとの対話、GitHubのPRレビュー、フィードバック要約など）を出発点にする方法もあります。テンプレートの一覧は公式のテンプレートギャラリー（mastra.ai/templates）で確認でき、create-mastraからテンプレートを指定して生成できます。指定用のフラグ書式は版によって変わるため、最新の書式は公式のクイックスタートで確認してください。

Mastraのコア構成要素：エージェント・ツール・ワークフロー

Mastraで「AIに仕事をさせる」中心は、エージェント・ツール・ワークフローの3つです。いずれも@mastra/coreから読み込み、コードで宣言します。

エージェント（Agent）を定義する

エージェントは、指示（instructions）とモデル、使えるツールを与えたAIの実行単位です。.generate()で最終結果を、.stream()でトークンを逐次受け取れます。modelはプロバイダー接頭辞つきの文字列で指定します。

import { Agent } from "@mastra/core/agent";

export const weatherAgent = new Agent({
  id: "weather-agent",
  name: "Weather Agent",
  instructions: "あなたは天気アシスタントです。weatherToolで現在の天気を取得してください。",
  model: "openai/gpt-5.6",
  tools: { weatherTool },
});

const res = await weatherAgent.generate("東京の天気は？");
console.log(res.text);

ツール（createTool）とMCP連携

ツールは、エージェントが外部APIや処理を呼ぶための関数です。入出力をZodスキーマで定義するため、引数と戻り値が型で守られます。executeは解析済みの入力を受け取ります。

import { createTool } from "@mastra/core/tools";
import { z } from "zod";

export const weatherTool = createTool({
  id: "weather-tool",
  description: "指定した地点の天気を取得する",
  inputSchema: z.object({ location: z.string() }),
  outputSchema: z.object({ weather: z.string() }),
  execute: async (inputData) => {
    const { location } = inputData;
    const res = await fetch(`https://wttr.in/${location}?format=3`);
    return { weather: await res.text() };
  },
});

自作ツールに加えて、MastraはMCP（Model Context Protocol）サーバーが公開するツール群をエージェントに読み込ませたり、逆にMastra自身のツールをMCPサーバーとして公開したりできます。MCPそのものの仕組みはMCP（Model Context Protocol）とは？基本概念とその重要性で解説しています。なお1.0ではexecuteのシグネチャに破壊的変更が入っているため、既存コードを移す際は最新のドキュメントで型を確認してください。

ワークフロー（createWorkflow / createStep）で処理を組む

複数の処理を決まった順序・分岐で流したいときはワークフローを使います。createStepで各ステップを定義し、createWorkflowに.then()／.branch()／.parallel()でつなぎ、最後に.commit()で確定します。標準の実行エンジンに加え、リトライや耐久性が必要な場合はInngestを組み合わせられます。エージェントが「その場で考えて動く」のに対し、ワークフローは「決められた手順を確実に流す」役割で、両者を使い分けます。

Mastra Skillsとは：コーディングエージェント向けの公式スキル

「mastra skills」で検索したときにたどり着くべき正解は、Mastraが公式提供するMastra Skillsです。これはAnthropicの提唱するAgent Skills標準（SKILL.md、agentskills.io）に沿った「手順・スクリプト・参考資料をまとめたフォルダ」で、コーディングエージェントがMastraを正しく扱うための知識を与えます。具体的には、セットアップ手順、ベストプラクティス、CLIコマンド、node_modules内のドキュメント参照、リモートの最新ドキュメント取得、トラブルシューティング、バージョン移行の手引きなどを含みます。実行時のエージェントの部品（Agent／Tool／Workflow）ではなく、AIにMastraのコードを正しく書かせるための開発支援機能である点がポイントです。

導入コマンドと対応コーディングエージェント

Mastra Skillsは次のコマンドで追加します。create-mastraの対話式セットアップから入れることもできます。

# npm
npx skills add mastra-ai/skills

# pnpm
pnpm dlx skills add mastra-ai/skills

# yarn
yarn dlx skills add mastra-ai/skills

# bun
bunx skills add mastra-ai/skills

対応するのは、Skills標準に準拠したコーディングエージェント全般で、公式にはClaude Code・Cursor・Codex・OpenCodeなどが挙げられています。SKILL.md標準そのものの書き方や、claude.ai／Claude Code／APIでの使い方はClaude Skillsとは？SKILL.mdの書き方とclaude.ai・Claude Code・APIでの使い方【2026年最新】で詳しく扱っています。

一般語の「スキル」とMastra Skillsの違い

紛らわしいのは、一般語としての「スキル（＝エージェントにできること）」と、固有機能の「Mastra Skills」が別物だという点です。実行時にエージェントへ能力を持たせたいのであれば、それはMastraではツール（createTool）・MCPサーバー・サブエージェントで実現します。一方でMastra Skillsは、開発者（正確にはその隣で動くコーディングエージェント）がMastraのコードを正確に書くための、開発時の知識パックです。「エージェントに機能を足したい」のか「AIにMastraコードを書かせたい」のかで、参照すべき仕組みが変わります。

メモリ機能：会話履歴・意味的想起・ワーキングメモリ

会話をまたいで文脈を保つ仕組みが、@mastra/memoryのMemoryクラスです。エージェントのmemoryに渡して使います。ユーザーやエンティティを表すresourceIdと、個々の会話を表すthreadIdで記憶をスコープします。

import { Agent } from "@mastra/core/agent";
import { Memory } from "@mastra/memory";

export const agent = new Agent({
  id: "support-agent",
  name: "Support Agent",
  instructions: "あなたはサポート担当です。",
  model: "openai/gpt-5.6",
  memory: new Memory({ options: { lastMessages: 20 } }),
});

3種類の記憶を使い分ける

Mastraのメモリは目的の異なる3つの仕組みを持ちます。

• 会話履歴：lastMessagesで、直近の生メッセージを何件モデルに渡すかを制御する。
• 意味的想起：過去の発言を意味の近さで検索して呼び戻す。ベクトルストアと埋め込みが必要。
• ワーキングメモリ：ユーザーの事実や好みを構造化して保持する（既定でリソース単位にスコープ）。

「さっきの件だけど」のような曖昧な参照に応えたり、ユーザーごとの設定を覚えたりできるのは、これらを組み合わせているためです。会話履歴は上記の設定だけで動きますが、意味的想起やセッションをまたぐ永続化を有効にするには、次章のストレージ（意味的想起はベクトルストアと埋め込みも）の設定が別途必要です。

maxStepsとエージェントのループ制御

エージェントは1回のgenerate／streamの中で「モデルが考える→ツールを呼ぶ→結果を見てまた考える」を繰り返します。この内部ループの上限がmaxStepsで、無限にツールを呼び続ける暴走を防ぎます（既定はおおむね5回）。新しめのバージョンでは、上限回数だけでなく任意の条件で止められるstopWhenによる制御も導入されています。ツールを多段で使うエージェントを組むときは、この値が短すぎて途中で打ち切られていないかを最初に疑うと、原因の切り分けが速くなります。

RAGとストレージ：ベクトル検索と保存先の選択

RAG（ドキュメント分割・埋め込み・ベクトルストア・rerank）

Mastraは検索拡張生成（RAG）の部品も同梱します。MDocumentで文書を取り込んで分割し、埋め込みを作ってベクトルストアに格納、問い合わせ時に関連チャンクを取り出してモデルに渡します。

import { MDocument } from "@mastra/rag";

const doc = MDocument.fromText(longText);
const chunks = await doc.chunk({ strategy: "recursive", size: 512, overlap: 50 });

対応するベクトルストアはpgvector（PostgreSQL）・Pinecone・Qdrant・MongoDBなど多岐にわたります。検索結果の並べ替えにはrerank()があり、意味的な関連度・ベクトル類似度・位置を重み付けして関連度の高い順に並べ替えます。グラフ構造を使うGraphRAGも用意されています。RAGの発展形であるエージェンティックRAGの考え方はエージェンティックRAGとは何か？AIエージェント統合で進化したRAGの特徴と仕組みを基礎から詳しく解説が参考になります。

ストレージ（DB）の選択：LibSQL既定・PostgreSQLほか

「mastra db」「mastra database」で問われるのは、メモリ・会話スレッド・トレース・評価結果などをどこに保存するかです。Mastraのストレージは差し替え可能で、既定はローカルではファイル、ホスティングではTursoとして使えるLibSQLです。ほかにPostgreSQL、Upstash（Redis）、Cloudflare D1／KV、MongoDBなどに対応し、Mastra本体の設定でまとめて指定します。1.0では領域ごとに別のバックエンドを割り当てる合成ストレージ（例：トレースとメモリで保存先を分ける）も入りました。

デプロイとMastra Cloud：本番反映の選択肢

本番向けにはmastra buildでアプリをビルドし、VM・コンテナ・PaaSへ載せます。MastraはHonoベースのHTTPサーバー（REST API＋Swagger UI）として動くため、長時間実行やWebSocketを含む用途にも対応できます。ビルド済みのサーバーをコンテナ化すればDockerでの運用も普通のNode.jsアプリと同じ要領です。DeployerとしてVercel・Cloudflare Workers・Netlifyが用意され、AWS Lambda／EC2・Azure・DigitalOcean向けの手引きや、Next.js・Astroに同居させる構成も提供されています。

Mastra Cloud（Studio・Server・Observability・Memory Gateway）

自前で運用せずマネージドで使いたい場合は、2026年4月9日にシリーズA調達と同時にローンチされたMastraのプラットフォームがあります。ホスティングされたStudio、Server、可観測性（Observability）、Memory Gatewayで構成され、クラウドホスト型と自己ホスト型の両方が提供されます。料金体系は変動するため、具体的な金額は公式（mastra.ai）で確認してください。なお「mastra sandbox」という独立した製品機能は公式ドキュメント上には見当たらず、近いのはセキュアなサンドボックス実行を備えたコーディングエージェント用の公式テンプレートです（プラットフォームの一機能ではなくテンプレート）。

他フレームワークとの比較：LangChain・LangGraph・Vercel AI SDK

Mastraの立ち位置は、同じTypeScript圏の選択肢と並べると明確になります。旧記事にあった「ドラッグ＆ドロップでLangChainより簡単」という説明は誤りで、実際はいずれもコードで書くフレームワークです。差は「どのレイヤーまで面倒を見るか」にあります。

MastraはVercel AI SDKを土台にしつつ、メモリ・ワークフロー・評価・RAGといった「アプリを本番運用するための層」を足したものと捉えると位置づけが掴めます。LangChainとLangGraphの関係整理はLangChainとLangGraphの違い｜v1.0で逆転した関係と使い分けにまとめています。

Mastraを選ぶ場面と選ばない場面

結論として、TypeScriptで、会話をまたぐ記憶・多段ワークフロー・評価・RAGまで一体で欲しいならMastraが有力です。逆に、単発のチャットUIを最短で作りたいだけならVercel AI SDK単体で十分で、Mastraはむしろ過剰になります。スタックがPython中心で他をTypeScriptに寄せられないなら、Mastraは選ばずPython系のフレームワークを使うべきです。「TypeScriptで書けるか」と「基盤機能をどこまで自前で持ちたいか」の2軸で判断すると外しません。

よくある質問

MastraはPythonで使えますか？

フレームワーク本体はTypeScript／JavaScript専用で、公式のPython版はありません。pip install mastraという導入もできません。PythonのコードからMastraのエージェントを使いたい場合は、Mastraが公開するHTTP（REST）やMCPのエンドポイント越しに呼び出す形になります。

Mastra Skillsとは何ですか？

コーディングエージェント向けの公式スキルで、Agent Skills標準のSKILL.mdに沿ってMastraの使い方（セットアップ・CLI・ドキュメント参照・移行手引きなど）をまとめたものです。npx skills add mastra-ai/skillsで追加でき、Claude Code・Cursor・Codex・OpenCodeなどに対応します。実行時のエージェント機能ではなく開発支援機能です。

Mastraは無料ですか？

フレームワーク本体はオープンソースとして公開されており、自分でホストして使う分にフレームワーク自体の利用料はかかりません。マネージド版のMastra Cloud（プラットフォーム）は別料金のサービスです。金額は変動するため公式で確認してください。

mastra init コマンドはありますか？

現在の推奨はnpm create mastra@latest（create-mastra）でプロジェクトを生成する方法です。開発サーバー起動はmastra dev、本番ビルドはmastra buildを使います。旧記事にあった、Pythonのmastra initでセットアップするという手順は誤りです。

Mastra 1.0はいつリリースされましたか？

2026年1月20日に正式版（GA）となりました。AI SDKの新バージョン対応や各種サーバーアダプタ、合成ストレージなどが入る一方、createToolのシグネチャ変更などの破壊的変更も含まれるため、旧版から移行する際は付属のコード変換ツール（codemod）と最新ドキュメントを併用してください。

Mastraのライセンスは何ですか？

Mastra本体はApache-2.0ライセンスのオープンソースで、商用利用を含めて無料で使えます。ただしリポジトリ内のee/ディレクトリに含まれるエンタープライズ向けコードは、ソースは公開されているものの「Mastra Enterprise License」の対象で利用条件が異なります。通常のエージェント開発で使う範囲はApache-2.0のため、ライセンス上の懸念は小さいといえます。

関連記事

• Claude Skillsとは？SKILL.mdの書き方とclaude.ai・Claude Code・APIでの使い方【2026年最新】
• 現場で使える新バージョン！Vercel AI SDK v6とは？概要と特徴をエンジニア向けに徹底解説
• LangChainとLangGraphの違い｜v1.0で逆転した関係と使い分け
• MCP（Model Context Protocol）とは？基本概念とその重要性
• エージェンティックRAGとは何か？AIエージェント統合で進化したRAGの特徴と仕組みを基礎から詳しく解説