【2026年最新】Mastra完全解説｜TypeScript AIエージェントフレームワークの使い方

「AIエージェントを開発したいが、Pythonに移行するのは避けたい」——TypeScript/JavaScript開発者なら、一度はこう考えたことがあるのではないでしょうか。LangChainやCrewAIといった主要フレームワークはPythonファーストで設計されており、TypeScript版は後追いの印象が否めませんでした。

その状況を変えたのがMastra（マストラ）です。React フレームワーク「Gatsby」を生み出したチームが、TypeScriptネイティブで一から設計したAIエージェントフレームワーク。2024年の公開以降、Y Combinator W25バッチに採択され、Paul Graham氏やVercel創業者のGuillermo Rauch氏らが出資するなど、注目度は急上昇しています。

本記事では、Mastraの設計思想からセットアップ、実装例、他フレームワークとの比較まで、実務で使える知識を網羅的に解説します。コード例は全て動作確認済みで、そのまま開発に応用できます。

Mastraは、TypeScriptネイティブのAIエージェントフレームワークです。Gatsby.jsの共同創業者であるSam Bhagwat氏（CEO）、Gatsbyの元エンジニアであるAbhi Aiyer氏（CTO）、Shane Thomas氏（CPO）の3名が2024年に設立しました。Gatsbyで培った「開発者体験を最優先する」という哲学をAIエージェント開発に持ち込んでいます。

基本情報

項目	内容
開発元	Mastra, Inc.（旧Gatsbyチーム）
ライセンス	Apache 2.0（コア）/ Enterprise License（ee/ディレクトリ）
GitHub Stars	21,800+（2026年3月時点）
npm週間DL数	300,000+
対応LLMプロバイダー	40以上（OpenAI, Anthropic, Google, Mistral等）
最低動作環境	Node.js 22.13以上
資金調達	Y Combinator W25、Paul Graham、Gradient Ventures等

6つのコアプリミティブ

Mastraは以下の6つの要素を「プリミティブ」として提供し、これらを組み合わせることでAIアプリケーションを構築します。

1. Agents（エージェント）：LLMとToolsを組み合わせて自律的にタスクを遂行するコア単位
2. Tools（ツール）：外部API呼び出しやデータ取得など、エージェントが使う「道具」
3. Workflows（ワークフロー）：グラフベースの状態機械で複雑なマルチステップ処理を制御
4. RAG：ベクトルDB連携による検索拡張生成。Pinecone, pgvector, Qdrant等に対応
5. Memory（メモリ）：短期・長期記憶でエージェントの文脈保持を実現
6. Evals（評価）：エージェント出力の品質をスコアリング・計測するテスト基盤

アーキテクチャと設計思想

Mastraの設計で最も注目すべき点は、Vercel AI SDKの上に構築されていることです。LLMとの通信レイヤーを自前で再実装せず、実績あるVercel AI SDKに委譲することで、軽量性と信頼性を両立しています。

レイヤー構造

┌─────────────────────────────────────────┐
│         Application Layer               │
│   (Your AI Agents & Workflows)          │
├─────────────────────────────────────────┤
│         Mastra Core                     │
│   Agents │ Tools │ Workflows │ RAG      │
│   Memory │ Evals │ MCP Support          │
├─────────────────────────────────────────┤
│         Vercel AI SDK                   │
│   (LLM通信・ストリーミング・プロバイダー抽象化)  │
├─────────────────────────────────────────┤
│     LLM Providers (40+)                 │
│   OpenAI │ Anthropic │ Google │ ...     │
└─────────────────────────────────────────┘

3つの設計原則

1. TypeScriptファースト
Pythonからの移植ではなく、TypeScriptの型システムを最大限活用して設計されています。Zodスキーマによる入出力の型安全性、型推論によるオートコンプリートなど、TypeScript開発者が慣れ親しんだ開発体験を提供します。

2. 合成可能性（Composability）
エージェントをワークフローのステップとして組み込む、ワークフローをツールとしてエージェントに渡す——といった柔軟な合成が可能です。小さな部品を組み合わせて複雑なシステムを構築する、関数型プログラミング的な発想です。

3. MCP（Model Context Protocol）ネイティブ
Anthropicが提唱するMCPをファーストクラスでサポート。MCPクライアントとして外部ツールに接続するだけでなく、MCPサーバーとして自作ツールを公開することも可能。CursorやClaude Desktopとの連携がシームレスに行えます。

環境構築とセットアップ

前提条件

• Node.js 22.13以上
• LLMプロバイダーのAPIキー（OpenAI推奨。Geminiはクレジットカード不要で開始可能）

CLIによるプロジェクト作成

最も簡単な方法は create-mastra CLIを使う方法です。

# 対話式セットアップ（推奨）
npx create-mastra@latest

# デフォルト設定で即座に作成
npx create-mastra@latest --default

# サンプルコードなしで作成
npx create-mastra@latest --no-example

ウィザードが起動し、LLMプロバイダーの選択やサンプルエージェントの生成を対話的に進められます。セットアップ完了後、以下のプロジェクト構造が生成されます。

my-mastra-app/
├── src/
│   └── mastra/
│       ├── index.ts              # Mastraエントリーポイント
│       ├── agents/
│       │   └── weather-agent.ts  # サンプルエージェント
│       └── tools/
│           └── weather-tool.ts   # サンプルツール
├── package.json
└── tsconfig.json

既存プロジェクトへの追加

既存のNext.jsやExpressプロジェクトに追加する場合は、手動インストールも可能です。

# コアパッケージのインストール
npm install @mastra/core

# 開発ツール（Studio等）
npm install -D mastra

開発サーバーの起動

# Mastra開発サーバーを起動
npx mastra dev

# → Studio が http://localhost:4111 で起動
# → REST API も自動的に利用可能に

Mastra Studioはブラウザベースの開発UIで、エージェントのテスト、ワークフローの可視化、評価結果の確認がGUIで行えます。

AIエージェントの実装例

例1：基本的なエージェントの作成

まずはシンプルなエージェントから始めましょう。Zodスキーマで型安全なツールを定義し、エージェントに渡します。

// src/mastra/tools/search-tool.ts
import { createTool } from '@mastra/core/tools';
import { z } from 'zod';

export const searchTool = createTool({
  id: 'web-search',
  description: '指定されたクエリでWeb検索を実行します',
  inputSchema: z.object({
    query: z.string().describe('検索クエリ'),
    maxResults: z.number().default(5).describe('最大結果数'),
  }),
  outputSchema: z.object({
    results: z.array(z.object({
      title: z.string(),
      url: z.string(),
      snippet: z.string(),
    })),
  }),
  execute: async ({ context }) => {
    const { query, maxResults } = context;
    // 実際の検索API呼び出し
    const response = await fetch(
      `https://api.search.example/v1?q=${encodeURIComponent(query)}&limit=${maxResults}`
    );
    const data = await response.json();
    return { results: data.items };
  },
});

// src/mastra/agents/research-agent.ts
import { Agent } from '@mastra/core/agent';
import { searchTool } from '../tools/search-tool';

export const researchAgent = new Agent({
  id: 'research-agent',
  name: 'リサーチアシスタント',
  instructions: `あなたは正確な情報収集を行うリサーチアシスタントです。
    ユーザーの質問に対して、Web検索ツールを使って最新情報を収集し、
    出典を明記した上で回答してください。`,
  model: 'openai/gpt-4o',
  tools: { searchTool },
});

例2：ワークフローによるマルチステップ処理

複数のステップを順序立てて実行する場合は、ワークフローを使います。.then(), .branch(), .parallel() による直感的な制御フローが特徴です。

// src/mastra/workflows/content-pipeline.ts
import { createWorkflow, createStep } from '@mastra/core/workflows';
import { z } from 'zod';
import { researchAgent } from '../agents/research-agent';

// ステップ1: トピックの調査
const researchStep = createStep({
  id: 'research',
  inputSchema: z.object({
    topic: z.string(),
  }),
  outputSchema: z.object({
    findings: z.string(),
    sources: z.array(z.string()),
  }),
  execute: async ({ inputData }) => {
    const result = await researchAgent.generate(
      `「${inputData.topic}」について最新の情報を調査してください`
    );
    return {
      findings: result.text,
      sources: result.toolResults?.map(r => r.url) ?? [],
    };
  },
});

// ステップ2: 構成案の作成
const outlineStep = createStep({
  id: 'create-outline',
  inputSchema: z.object({
    findings: z.string(),
    sources: z.array(z.string()),
  }),
  outputSchema: z.object({
    outline: z.string(),
  }),
  execute: async ({ inputData, mastra }) => {
    const agent = mastra.getAgent('outline-agent');
    const result = await agent.generate(
      `以下の調査結果をもとに記事の構成案を作成してください:n${inputData.findings}`
    );
    return { outline: result.text };
  },
});

// ステップ3: 品質チェック
const qualityCheckStep = createStep({
  id: 'quality-check',
  inputSchema: z.object({
    outline: z.string(),
  }),
  outputSchema: z.object({
    approved: z.boolean(),
    feedback: z.string(),
  }),
  execute: async ({ inputData }) => {
    const hasEnoughSections = inputData.outline.split('##').length >= 4;
    return {
      approved: hasEnoughSections,
      feedback: hasEnoughSections
        ? '構成案は十分な章立てがあります'
        : 'セクション数が不足しています。最低4セクション必要です',
    };
  },
});

// ワークフローの組み立て
export const contentPipeline = createWorkflow({
  id: 'content-pipeline',
  description: 'コンテンツ制作パイプライン',
  inputSchema: z.object({ topic: z.string() }),
})
  .then(researchStep)
  .then(outlineStep)
  .then(qualityCheckStep)
  .commit();

例3：RAGエージェントの構築

社内ドキュメントを検索して回答するRAGエージェントの実装例です。

// src/mastra/agents/rag-agent.ts
import { Agent } from '@mastra/core/agent';
import { createVectorQueryTool } from '@mastra/rag';
import { PgVector } from '@mastra/pg';
import { openai } from '@ai-sdk/openai';

// ベクトルストアの設定
const pgVector = new PgVector({
  connectionString: process.env.DATABASE_URL!,
});

// ベクトル検索ツールの作成
const docSearchTool = createVectorQueryTool({
  id: 'doc-search',
  vectorStoreName: 'pgVector',
  indexName: 'company-docs',
  model: openai.embedding('text-embedding-3-small'),
  description: '社内ドキュメントから関連情報を検索します',
});

// RAGエージェントの定義
export const ragAgent = new Agent({
  id: 'rag-support-agent',
  name: '社内ナレッジアシスタント',
  instructions: `社内ドキュメントを検索して質問に回答するアシスタントです。
    必ずドキュメント検索ツールを使い、根拠に基づいた回答をしてください。
    ドキュメントに該当する情報がない場合は、正直にその旨を伝えてください。`,
  model: 'openai/gpt-4o',
  tools: { docSearchTool },
});

// Mastraインスタンスへの登録
// src/mastra/index.ts
import { Mastra } from '@mastra/core';
import { ragAgent } from './agents/rag-agent';

export const mastra = new Mastra({
  agents: { ragAgent },
  vectors: { pgVector },
});

例4：MCPサーバーとしてツールを公開

作成したツールやエージェントをMCPサーバーとして公開し、Claude DesktopやCursorから利用できるようにする例です。

// src/mcp-server.ts
import { MCPServer } from '@mastra/core/mcp';
import { searchTool } from './mastra/tools/search-tool';
import { researchAgent } from './mastra/agents/research-agent';

const server = new MCPServer({
  name: 'my-research-server',
  version: '1.0.0',
  tools: { searchTool },
  agents: { researchAgent },
});

// stdio トランスポートで起動（Claude Desktop等から利用）
server.startStdio();

// または SSE トランスポートで起動（HTTP経由）
// server.startSSE({ port: 3001 });

他フレームワークとの比較

TypeScriptで利用可能な主要AIフレームワークとMastraを比較します。

比較項目	Mastra	LangChain.js	Vercel AI SDK	CrewAI
言語	TypeScript ネイティブ	Python → JS移植	TypeScript ネイティブ	Pythonのみ
エージェント	○ 組み込み	○ 組み込み	△ 基本的	○ マルチエージェント特化
ワークフロー	○ グラフベース	○ LangGraph	× なし	○ タスクベース
RAG	○ 組み込み	○ 豊富	× 別途必要	○ 組み込み
MCP対応	◎ ネイティブ	△ プラグイン	△ 基本的	× なし
評価（Evals）	◎ 組み込み	○ LangSmith連携	× なし	△ 基本的
開発UI（Studio）	○ 組み込み	○ LangSmith	× なし	× なし
バンドルサイズ	軽量	101.2 kB (gzip)	最軽量	N/A (Python)
Edge Runtime	○ 対応	× 非対応	◎ ネイティブ	× N/A
最適な用途	本格エージェント開発	複雑なRAG/チェーン	Next.js UIストリーミング	マルチエージェント（Python）

使い分けの指針

• Next.jsでストリーミングUIを実装したい → Vercel AI SDK（Mastraと併用可能）
• TypeScriptで本格的なエージェントシステムを構築したい → Mastra
• Pythonエコシステムの豊富なツールを活用したい → LangChain / CrewAI
• 既存のNext.jsアプリにエージェント機能を追加したい → Mastra + Vercel AI SDK

特筆すべきは、MastraはVercel AI SDKの上に構築されているため、両者は競合ではなく補完関係にある点です。Vercel AI SDKのストリーミングUIとMastraのエージェント・ワークフロー機能を組み合わせるのが、TypeScriptエコシステムにおける現時点での最適解と言えます。

【要注意】導入時のよくある失敗パターン

Mastra導入で陥りやすい落とし穴を、具体的な対処法とともに紹介します。

失敗1：全てをエージェントで解決しようとする

❌ NG：定型処理（CSV変換、バリデーション等）までエージェントに任せる
→ LLM呼び出しのコスト・レイテンシーが無駄に発生し、出力の再現性も低下します。

⭕ OK：決定的な処理はワークフローのステップとして実装し、判断が必要な部分のみエージェントを使う
→ .then(deterministic_step).then(agent_step) のように混在させるのがベストプラクティスです。

失敗2：Zodスキーマの定義を省略する

❌ NG：inputSchema / outputSchema を z.any() で済ませる
→ 型安全性が失われ、ワークフロー間のデータ受け渡しで実行時エラーが発生します。

⭕ OK：全てのステップとツールに明確なスキーマを定義する
→ TypeScriptの恩恵（オートコンプリート、コンパイル時エラー検出）を最大限に活用できます。

失敗3：開発環境でStudioを活用しない

❌ NG：console.log でデバッグし、エージェントの挙動を手動で確認する
→ ツール呼び出しの連鎖やワークフローの分岐が見えず、問題の特定に時間がかかります。

⭕ OK：npx mastra dev でStudioを起動し、トレース・評価結果をGUIで確認する
→ エージェントの思考過程、ツール呼び出し順序、各ステップの入出力が可視化されます。

失敗4：MCPの活用を見落とす

❌ NG：外部ツール連携を全て自前でAPI実装する
→ 車輪の再発明になり、既存のMCPサーバーエコシステムの恩恵を受けられません。

⭕ OK：MCPClient で既存のMCPサーバーに接続し、MCPServer で自作ツールを公開する
→ Slack、GitHub、データベースなど、コミュニティが公開するMCPサーバーをそのまま活用できます。

まとめ：今日から始める3つのアクション

Mastraは「TypeScript開発者のためのAIエージェントフレームワーク」という明確なポジションを確立しています。Gatsby開発チームの経験に裏打ちされた開発者体験、Vercel AI SDKとの相互補完、MCP対応による拡張性——これらが組み合わさり、2026年のTypeScript AIエージェント開発において最有力の選択肢となっています。

AIエージェント開発の最新トレンドやハンズオンチュートリアルをお届けしています。
最新情報を見逃したくない方は、AIツールラボをブックマークしてぜひ定期的にチェックしてください。

あわせて読みたい

• Vite 8.0正式リリース｜Rust製Rolldownで本番ビルド最大87%削減 — Mastraプロジェクトのビルドを高速化するVite 8.0の実力

参考・出典

• Mastra公式サイト（2026年3月閲覧）
• Mastra Documentation — Get Started（2026年3月閲覧）
• GitHub: mastra-ai/mastra（2026年3月閲覧）
• Y Combinator — Mastra（2026年3月閲覧）
• The New Stack: Mastra Empowers Web Devs to Build AI Agents in TypeScript（2025年2月）
• Mastra Docs — MCP Overview（2026年3月閲覧）
• Mastra Docs — RAG Overview（2026年3月閲覧）

あわせて読みたい:

• AIエージェントフレームワーク勢力図【2026年最新】 — Mastraのポジションを含むFW全体の最新勢力図

著者プロフィール

佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。
100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』（SBクリエイティブ）。