Mastra入門2026｜TypeScriptで作るAIエージェント

週次30万ダウンロード、GitHubスター2万2千、SoftBankとMarsh McLennanが本番採用。2026年1月に1.0を切ったばかりのMastraは、TypeScript界隈に残っていた"AIエージェントの空白地帯"を一気に埋めた。PythonのLangGraphに指をくわえて見ていたフロントエンドエンジニアが、ようやく自分たちの言語でエージェントを組めるようになった格好だ。

Mastraの正体と、LangGraph・Claude Agent SDKとの住み分け。そしてnpm create mastra@latestから本番デプロイまでを、実コードで追う。他の日本語記事がほぼ触れていないMCP公開とCloudflare Workersデプロイの手順も入れた。

1. Mastraとは何か｜TypeScript一本で完結するAIエージェント基盤

Mastra（マストラ）はTypeScript製のオープンソースAIエージェントフレームワークである。開発元はMastra, Inc.。中心メンバーにはGatsby共同創業者のKyle Mathewsが名を連ねる。2024年10月に初版が公開され、2025年10月に$13Mのシードを調達。2026年1月に1.0がリリースされた。

特徴を一言でまとめるなら"Pythonで学び、TypeScriptで出荷する"。公式が掲げるTrain in Python, Ship in TypeScriptというスローガンは、プロトタイプはPythonでも構わないが、Webサービスとして出すならサーバーランタイムもTypeScriptに揃えたほうが運用コストが下がる、という思想を表している。

コアに含まれる機能は次の5つだ。

• Agent｜LLMに人格とツールを与える単位。40以上のLLMプロバイダーを統一APIで切り替え可能
• Tool｜Zodで入出力スキーマを定義する型安全な関数。エージェントが自律的に呼ぶ
• Workflow｜複数ステップの処理を有向グラフで組むための層。分岐や並列もサポート
• Memory｜短期・セマンティック・ワーキングの3層メモリ。会話履歴と長期記憶を分ける
• Evals｜出力を自動採点するスコアラー。CIに組み込んで回帰を防ぐ

Apache 2.0なので商用利用は自由。ただしee/ディレクトリ配下だけEnterprise Licenseという二層構造になっているので、フォークして魔改造するタイプの開発者は読んでおいたほうが無難だ。

2. LangGraph・Claude Agent SDKと何が違うのか

結論、言語と設計思想が違う。使い分けの基準を表で整理する。

判断軸はシンプル。既存コードベースがNext.jsやNestJSならMastra一択。Pythonのデータパイプラインと密結合させたいならLangGraph。Claude専用でよくて手早さが最優先ならClaude Agent SDKだ。

メモリの設計には差がある。他の2つのフレームワークは"セッション内の状態保存"で止まる。MastraはそこにセマンティックRAGとワーキングメモリ（ユーザー属性の自動抽出と永続化）が乗ってくる。1行追加するだけで、エージェントが会話の外側にいるユーザー像を勝手に更新し始める。この差は、触って初めて分かる。

3. インストールと最小構成｜5分で動かす

Node.js 20以上があれば、1コマンドで雛形が立ち上がる。

npm create mastra@latest

対話形式でプロジェクト名、テンプレート、LLMプロバイダーを選ぶ。OpenAI・Anthropic・Groqから選ぶとAPIキー入力を求められる。初回はweatherテンプレートを選んでおくと動く例が最初からついてくる。

出来上がるディレクトリ構造はこうなる。

my-agent/
├── src/
│   └── mastra/
│       ├── agents/
│       │   └── weather-agent.ts
│       ├── tools/
│       │   └── weather-tool.ts
│       ├── workflows/
│       │   └── weather-workflow.ts
│       └── index.ts
├── package.json
└── tsconfig.json

起動はこれだけだ。

cd my-agent
npm run dev

ブラウザでhttp://localhost:4111を開く。Mastra Playgroundが立ち上がる。チャットUIでエージェントに話しかけると、どのツールが呼ばれたか、LLMに渡ったプロンプトは何か、すべて画面右側のトレースで追える。LangGraph Studio相当の機能が最初から同梱されている格好だ。デバッグが試行一回で完結する。

4. 最初のエージェントを作る｜createToolまで一気に

テンプレートが吐くweather-agentを分解して、自作エージェントを組む感覚を掴む。

まずツールから。createToolはZodでスキーマを受け取り、型安全な関数を返す。

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

export const weatherTool = createTool({
  id: "get-weather",
  description: "指定された都市の現在の天気を取得する",
  inputSchema: z.object({
    city: z.string().describe("都市名。例: Tokyo"),
  }),
  outputSchema: z.object({
    temperature: z.number(),
    conditions: z.string(),
  }),
  execute: async ({ context }) => {
    const res = await fetch(
      `https://api.open-meteo.com/v1/forecast?latitude=35.68&longitude=139.76¤t_weather=true`
    );
    const json = await res.json();
    return {
      temperature: json.current_weather.temperature,
      conditions: json.current_weather.weathercode.toString(),
    };
  },
});

ポイントはdescriptionだ。ここに書いた日本語をそのままLLMが読み、ツールを呼ぶか判断する。英語で書くのが無難だが、日本語でも動く。曖昧な説明を入れると関係ない場面でも呼ばれるので、動詞+対象+出力を1文に詰めるのがコツ。

次にエージェント本体。

import { Agent } from "@mastra/core";
import { openai } from "@ai-sdk/openai";
import { weatherTool } from "../tools/weather-tool";

export const weatherAgent = new Agent({
  name: "Weather Assistant",
  instructions: `
あなたは日本の天気を案内するアシスタント。
都市名を受け取ったらget-weatherツールを呼び、
結果を日本語で自然な文章に変換して返すこと。
  `,
  model: openai("gpt-4o-mini"),
  tools: { weatherTool },
});

instructionsがシステムプロンプト、modelはAI SDK経由で40以上のプロバイダーから選べる。Anthropicに切り替えるならanthropic("claude-sonnet-4-5")と書き換えるだけで動く。この乗り換えコストの低さは、LLM価格が半年単位で変動する2026年の現場では効いてくる。

5. メモリとワークフロー｜状態を持つエージェントへ

エージェントが会話を覚えないと、同じ質問を繰り返すことになる。Mastraのメモリは3層構造だ。

利用は1行追加するだけでいい。

import { Memory } from "@mastra/memory";

const memory = new Memory({
  storage: new LibSQLStore({ url: "file:./memory.db" }),
  options: {
    lastMessages: 10,
    semanticRecall: { topK: 3, messageRange: 2 },
    workingMemory: { enabled: true },
  },
});

export const weatherAgent = new Agent({
  name: "Weather Assistant",
  model: openai("gpt-4o-mini"),
  tools: { weatherTool },
  memory,
});

LibSQLなのでSQLiteで手元に保存しても動くし、Tursoに置いてエッジで使ってもいい。ワーキングメモリは一度有効にすると、ユーザーとの2〜3往復の後に「名前: 山田、好きな場所: 京都」といった属性が自動でMarkdownに積み上がっていく。見ていて気持ち悪いくらい能動的に動く。

ワークフローは複数ステップを有向グラフで繋ぐ層だ。天気取得 → 服装提案 → カレンダー登録、のようにエージェント呼び出しを直列で組みたい時に使う。

import { Workflow, Step } from "@mastra/core";

const fetchWeather = new Step({
  id: "fetchWeather",
  execute: async ({ context }) => {
    return { weather: "sunny", temp: 22 };
  },
});

const suggestOutfit = new Step({
  id: "suggestOutfit",
  execute: async ({ context }) => {
    const { weather } = context.getStepResult("fetchWeather");
    return { outfit: weather === "sunny" ? "Tシャツ" : "ジャケット" };
  },
});

export const morningRoutine = new Workflow({ name: "morning" })
  .step(fetchWeather)
  .then(suggestOutfit)
  .commit();

LangGraphと違い、Mastraのワークフローは"エージェントの外側の制御層"と位置付けられている。エージェント単体で自律的に動かすか、決定論的なワークフローで縛るか、用途で選べる設計だ。

6. MCPサーバーとして公開する｜他ツールから呼ぶ

ここがMastraの隠れた目玉機能だ。既存の日本語記事はほぼ触れていない。作ったエージェントやツールを、そのままMCPサーバーとして外部公開できる。つまりClaude DesktopやCursor、Claude Codeから呼び出せる形に変身させられる。

import { MCPServer } from "@mastra/mcp";
import { weatherAgent } from "./agents/weather-agent";
import { weatherTool } from "./tools/weather-tool";

const server = new MCPServer({
  name: "weather-mcp",
  version: "1.0.0",
  agents: { weatherAgent },
  tools: { weatherTool },
});

await server.startStdio();

Claude Desktopの設定ファイルにこう書き足せば、Mastra側で定義したツールがそのまま使える。

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/path/to/my-agent/dist/mcp-server.js"]
    }
  }
}

この機能の何が嬉しいか。社内向けのAPIラッパーを一度Mastraで作っておけば、エンジニアはCursorから、非エンジニアはClaude Desktopから、同じロジックを叩けるようになる。MCPはClaude Codeが閉じ込められたターミナルの壁にドアを開ける仕組みだが、Mastraはそのドアを作る側に回れる、という位置付けだ。

7. Cloudflare Workersへデプロイする

本番に載せる話。Mastraは公式でCloudflare Workers・Vercel・AWS Lambda・自前のNode.jsサーバー向けのデプロイヤーを提供している。今回はエッジ最速のCloudflare Workersで動かす。

npm install @mastra/deployer-cloudflare

src/mastra/index.tsでデプロイヤーを噛ませる。

import { Mastra } from "@mastra/core";
import { CloudflareDeployer } from "@mastra/deployer-cloudflare";
import { weatherAgent } from "./agents/weather-agent";

export const mastra = new Mastra({
  agents: { weatherAgent },
  deployer: new CloudflareDeployer({
    scope: "your-account-id",
    projectName: "weather-agent",
    auth: { apiToken: process.env.CLOUDFLARE_API_TOKEN! },
  }),
});

あとはビルドとデプロイをワンコマンドで。

npm run build
wrangler deploy

8. 料金・ライセンス・対応LLM

Mastra本体はオープンソースで無料。かかるコストはLLMのAPI料金とインフラ代のみ。

商用利用で気をつけるのはEnterprise Licenseの範囲だけ。packages/coreやpackages/memoryを使う通常の開発では発生しない。

9. SoftBankやMarsh McLennanの導入事例

規模で最大なのはMarsh McLennanだ。75,000人向けの社内ナレッジ検索をMastraで動かしている。保険・コンサル大手、世界有数の実装規模。個人開発者のおもちゃではない。

日本ではSoftBank。同社のSatto Workspaceという生成AI業務支援プラットフォームのエージェント層にMastraが入っている。約45,000人の社員がエージェント経由で業務アプリと対話する、年末ローンチの巨大プロジェクトだ。

採用時期を逆算すると、各社はベータ版で本番投入を始めていた計算になる。1.0は後から追いついた。フレームワーク選定の現場で、このタイムラインは珍しい。

10. よくある質問

11. まとめ｜今日から始める一手

MastraはTypeScriptエンジニアが"LangGraphがうらやましい"と言わなくて済むようにしてくれた最初のフレームワークだ。Pythonにずっと置き去りにされていたNext.js勢が、ようやく自分たちのスタックだけでAIエージェントを本番投入できるようになった。

今日の一手は1コマンドだけでいい。

npm create mastra@latest

Weatherテンプレートを選び、npm run devで起動。30分後にはPlaygroundで自作エージェントと会話できている。筆者なら次の一手はMCPサーバー化を試す。作ったツールをClaude Desktopから呼び出して、エージェントが"外の世界"と繋がる瞬間を体感する。それが一番腹に落ちる。

関連記事

この記事を書くにあたり参考にした書籍