Mastraとは？Skills・サンドボックス・メモリまで分かるTypeScript製AIエージェントフレームワークの使い方

Mastra（マストラ）は、TypeScriptでAIエージェントを書くためのオープンソースのフレームワークです。Pythonのライブラリではなく、エージェントをコードで書くことを前提にしています。本記事では2026年10月28日公開の @mastra/core 1.80.0 を手元に入れ、導入からエージェント・ツール・ワークフローの書き方、検索の多い「Mastra Skills」、Workspaceのサンドボックス、メモリ、料金までを順に確かめました。Mastra Skillsは2026年に入って意味が2つに分かれたので、どちらを探しているのかを最初に切り分けます。

まとめ：Mastraの要点（2026年10月時点）

• MastraはTypeScript製・コードファーストのAIエージェントフレームワーク。本体はApache-2.0で無料、公式のPython版は無い。
• 導入は npm create mastra@latest。動作環境はNode.js v22.13.0以上で、Bun・Deno・Cloudflareでも動く。
• 「Mastra Skills」は2つある。コーディングエージェントにMastraを教える公式スキル（npx skills add mastra-ai/skills）と、自作エージェントに持たせるスキル（createSkill()・Workspaceの skills）。
• 「mastra sandbox」はWorkspaceのサンドボックス機能を指す。エージェントにシェルコマンドを実行させる仕組みで、LocalSandbox は既定では隔離されない。
• メモリは公式がObservational Memoryを推奨。会話履歴が30,000トークンを超えると要約メモに置き換えていく。
• マネージド版のMastra platformはStarterが月0ドル、Teamsが月250ドル。

Mastraの正体：TypeScript製のコードファーストなAIエージェントフレームワーク

Mastraは、エージェント・ツール・ワークフロー・メモリ・RAG・評価をTypeScriptのコードで組み合わせるフレームワークです。開発元はGatsbyを作ったチームで、ソースは GitHubのmastra-ai/mastra で公開されています。モデルは openai/gpt-6.1-sol のような「プロバイダー/モデル」形式の文字列で指定し、プロバイダーを替えるときは、文字列の書き換えと、そのプロバイダーのAPIキーを環境変数に設定する作業で済みます。ただしツール呼び出しなどの対応状況はモデルごとに違うため、切り替えた後は動作を確かめてください。

画面での作成とPython対応の範囲

日本語の解説記事の一部には「ドラッグ＆ドロップで作れるノーコードツール」「pip install mastra で入る」という説明が残っています。Python製という説明は誤りで、npmで配布されるのはTypeScript/JavaScriptのパッケージだけです。PyPIには mastra というパッケージ自体がありません（2026年10月30日に確認）。画面での操作は、後述のStudioでエージェントを試すほか、Agent Builderというエージェント作成用のUIもあります。ただしAgent BuilderはMastraサーバーの中で動く機能で、本番で使うにはMastra Enterprise Editionのライセンスが必要です。Enterprise契約なしで本番運用する構成はコード中心ですが、Agent Builderもライセンス条件に従って開発・テスト用途で試せます。PythonのアプリからMastraのエージェントを使うなら、mastra build で作ったHTTPサーバーのREST APIを呼ぶ形になります。

ライセンスとリリースの速さ

npmに登録された @mastra/core のライセンスはApache-2.0です。リポジトリの ee/ ディレクトリにあるエンタープライズ向けの機能だけは別の「Mastra Enterprise License」になるため、RBACやSSOのような機能を自前ホストで使うときは条件を確認してください。1.0は2026年1月20日に公開され、10月28日には1.80.0まで進んでいます。10月1日の1.73.0から10月28日の1.80.0まで、4週間で8つのマイナー版が出ています。0.x時代に書かれた解説のコードは、1.0の破壊的変更（後述の createTool の引数など）のためにそのままでは動きません。参考にする記事は、どの版で書かれたかを確かめてから読んでください。

Mastraのインストール：npm create mastraとStudio

npm create mastra@latest による雛形の作成

新規プロジェクトは公式のcreate-mastraで作ります。公式のインストール手順によると、このコマンドはローカルのワークスペース・シェルツール・メモリ・タスク管理・Web検索・定期実行を備えた汎用のエージェント一式を生成し、手元にあるコーディングエージェント向けにMastra Skillsも入れます。

# npm
npm create mastra@latest
# pnpm
pnpm create mastra@latest
# Yarn
yarn create mastra
# Bun
bunx create-mastra

既存のプロジェクトに足す場合は、npx mastra@latest init で初期化します（--default を付けると、src・OpenAI・サンプル付きの既定値で作られます）。手作業で入れるなら、package.json に "type": "module" を設定し、@mastra/core・zod・mastra（CLI）を入れます。2026年10月30日にNode.js v26.5.0で npm i @mastra/[email protected] zod@4 を実行したところ、146パッケージが19秒で入りました。Node.js 22.18.0以降なら、.ts ファイルをビルドせずにそのまま実行できます。

mastra dev と Studio（localhost:4111）での起動と動作確認

開発サーバーは mastra dev（create-mastraで作った場合は npm run dev）で起動します。Studioの公式説明のとおり、既定では http://localhost:4111 にStudioが開き、エージェントとのチャット、ワークフローの実行、ツールの単体実行、トレースの確認ができます。localhost:4111/swagger-ui では同じ機能をREST APIとして試せます。ポートは設定で変えられます。

エージェント・ツール・ワークフローの実装

Agentの定義とモデルの指定

エージェントは Agent クラスに、ID・指示文・モデル・ツールを渡して作ります。次の例を単独実行する場合は、プロジェクト直下の agent.ts に保存し、後掲のツール例を tools/weather.ts に保存してください。作ったエージェントは Mastra インスタンスに登録すると、Studioやサーバーから呼べるようになります。

import { Agent } from '@mastra/core/agent'
import { Mastra } from '@mastra/core'
import { weatherTool } from './tools/weather.ts'

export const weatherAgent = new Agent({
  id: 'weather-agent',
  name: 'Weather Agent',
  instructions: '都市名を受け取り、気温を日本語で答えてください。',
  model: 'openai/gpt-6.1-sol',
  tools: { weatherTool },
})

export const mastra = new Mastra({ agents: { weatherAgent } })

// 呼び出し（OPENAI_API_KEY が必要）
const res = await mastra.getAgent('weatherAgent').generate('東京の気温は？')
console.log(res.text)

createToolによる外部処理の定義

ツールは createTool() で、入力と出力をzodのスキーマで宣言して作ります。モデルを呼ばずにツールだけを実行できるので、APIキーが無くても単体で確かめられます。下の例は東京なら21度、それ以外は15度を返すだけのダミーで、実際の天気APIを呼ぶ処理は execute の中に書きます。下のコードは1.80.0で実行し、{"temp":21} が返ることを確認しました。

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

export const weatherTool = createTool({
  id: 'get-weather',
  description: '都市の気温を返す',
  inputSchema: z.object({ city: z.string() }),
  outputSchema: z.object({ temp: z.number() }),
  execute: async ({ city }) => ({ temp: city === 'Tokyo' ? 21 : 15 }),
})

console.log(await weatherTool.execute({ city: 'Tokyo' }, {}))  // { temp: 21 }

1.0で execute の引数は「入力そのもの」と「実行コンテキスト」の2つに分かれました。0.x時代の記事にある execute: async ({ context }) => ... の書き方は今は使えません。既存のMCPサーバーをツールとして使う場合は @mastra/mcp の MCPClient でつなぎます。MCPそのものの仕組みはMCP（Model Context Protocol）とは？仕組み・APIとの違い・MCPサーバーの作り方で解説しています。

createWorkflowによる処理順序の固定

判断をモデルに任せたくない処理は、createStep() で作った手順を createWorkflow() で .then() につなぎ、最後に .commit() します。次の例は1.80.0で success と {"length":6} を返しました。

import { createWorkflow, createStep } from '@mastra/core/workflows'
import { Mastra } from '@mastra/core'
import { z } from 'zod'

const upper = createStep({
  id: 'upper',
  inputSchema: z.object({ text: z.string() }),
  outputSchema: z.object({ text: z.string() }),
  execute: async ({ inputData }) => ({ text: inputData.text.toUpperCase() }),
})
const count = createStep({
  id: 'count',
  inputSchema: z.object({ text: z.string() }),
  outputSchema: z.object({ length: z.number() }),
  execute: async ({ inputData }) => ({ length: inputData.text.length }),
})

const textFlow = createWorkflow({
  id: 'text-flow',
  inputSchema: z.object({ text: z.string() }),
  outputSchema: z.object({ length: z.number() }),
}).then(upper).then(count).commit()

const mastra = new Mastra({ workflows: { textFlow } })
const run = await mastra.getWorkflow('textFlow').createRun()
const result = await run.start({ inputData: { text: 'mastra' } })
console.log(result.status, result.result)  // success { length: 6 }

このとき Mastra にストレージを設定していないと、「メモリ上の保存先にフォールバックした。再起動で全データが消え、本番では安全でない」という警告が出ます。ワークフローの途中停止・再開や会話履歴を本番で使うなら、ストレージは必ず明示してください。

Mastra Skillsの2つの意味：コーディングエージェント向けと自作エージェント向け

「mastra skills」で調べる人の目的は2つに分かれます。どちらも Agent Skills仕様に沿ったスキル（SKILL.md を置いたフォルダ、またはコード内での定義）ですが、使う場面がまったく違います。

本記事の2026年7月版では「Mastra Skillsは実行時の機能ではなく開発支援」と説明していましたが、現在の公式ドキュメントには実行時のスキル機能があります。Mastraのコードを書かせたいなら前者、作ったエージェントに業務手順を覚えさせたいなら後者です。

コーディングエージェントにMastraを教える：npx skills add mastra-ai/skills

公式のMastra Skillsは、2026年2月5日の公式ブログで公開されました。Claude CodeやCursorのようなコーディングエージェントが、Mastraの古いAPIを推測で書くのを防ぐための知識パックです。

npx skills add mastra-ai/skills
# .well-known による自動検出でも入る
npx skills add https://mastra.ai/

mastra-ai/skillsのREADMEによると、2026年10月時点で入っているのは2つです。mastra は1つの総合スキルで、セットアップ、node_modules 内の同梱ドキュメントの引き方、mastra.ai/llms.txt からの最新ドキュメント取得、よくあるエラー、版の移行手順などを参照ファイルに分けて持ちます。mastra-factory は mastra api factory を使う監督役向けで、--skill mastra-factory を付けると単独で入れられます。

スキルを入れなくても、各パッケージには同梱ドキュメントがあります。1.80.0の node_modules/@mastra/core/dist/docs/ には name: mastra-core・version: "1.80.0" を持つ SKILL.md と、471本の参照ファイルが入っていました。インストールした版と同じ版の説明として配布されるため、版の上がりやすいMastraでは、書かれた時期の分からないWeb上の記事より先に当たるべき情報源です。Claude Code側のスキルの仕組みはClaude Skillsとは？SKILL.mdの書き方とclaude.ai・Claude Code・APIでの使い方【2026年10月】、カスタムコマンドがスキルに統合された経緯はClaude Codeカスタムコマンドの作り方｜Skills統合後の書き方と引数【2026年最新】にまとめています。

自作エージェントにスキルを持たせる：createSkillとWorkspaceのskills

Mastraで作ったエージェントに手順書を持たせるには、エージェントのスキルとしてコードで定義するか、Workspaceのスキルとしてフォルダから読み込みます。両方を同時に使うこともできます。Workspaceから読み込む場合は、先に ./workspace/skills/code-review/SKILL.md を次の内容で作っておきます。

---
name: code-review
description: Reviews code for bugs and readability issues
---

# Code review

Check the code for bugs, missing error handling, and unclear naming.

そのうえで、エージェントにコード内のスキルとWorkspaceを渡します。

import { Agent } from '@mastra/core/agent'
import { createSkill } from '@mastra/core/skills'
import { Workspace, LocalFilesystem } from '@mastra/core/workspace'

const release = createSkill({
  name: 'release-checklist',
  description: 'リリース準備のときに使う',
  instructions: '1. テストを全件流す\n2. CHANGELOG.md を更新\n3. タグを打つ',
})

// ./workspace/skills/code-review/SKILL.md を自動で見つける
const workspace = new Workspace({
  filesystem: new LocalFilesystem({ basePath: './workspace' }),
  skills: ['skills'],
})

export const reviewer = new Agent({
  id: 'reviewer',
  name: 'reviewer',
  instructions: 'コードレビューを担当します。',
  model: 'openai/gpt-6.1-sol',
  workspace,
  skills: [release],
})

console.log(await reviewer.listSkills())

1.80.0で実行すると、listSkills() はコードで定義した release-checklist と、フォルダから見つけた code-review の2件を返しました。getSkill('code-review') で SKILL.md の本文も取り出せます。会話の中では、エージェントに skill（本文を読み込む）・skill_read（参照ファイルを読む）・skill_search（スキル内を検索する）の3つのツールが自動で付き、必要になったスキルだけを読み込みます。全スキルの本文を最初からプロンプトに入れないので、スキルを増やしてもコンテキストを圧迫しにくい作りです。同じ名前のスキルがある場合は、Workspace側よりエージェントに直接渡した方が優先されます。

SKILL.mdの命名ルールと読み込み失敗時の挙動

フロントマターの name と description は必須で、name はフォルダ名と一致させ、64文字以内の小文字英数字とハイフンにします。先頭・末尾のハイフンと、ハイフンの連続も使えません。ここで注意したいのは、規則に外れたスキルがあってもエラーで止まらない点です。Bad_Name というフォルダを置いて試すと、警告を1行出してそのスキルだけを読み飛ばし、残りのスキルは普通に読み込まれました。気づかないまま「スキルが効かない」状態になりやすいので、アプリからSKILL.mdを書き込むなら保存前に validateSkillContent() で確かめてください。

import { validateSkillContent } from '@mastra/core/skills'

const r = validateSkillContent({
  content: '---\nname: Bad_Name\ndescription: x\n---\nbody',
  directoryName: 'Bad_Name',
})
console.log(r.valid, r.errors)
// false [ 'name: Skill name must contain only lowercase letters, numbers, and hyphens' ]

スキル・ツール・MCPの使い分け

スキルは「手順と知識」を渡す仕組みで、それ自体は何も実行しません。外部APIを呼ぶ、DBを書き換えるといった動作はツール（createTool）かMCPサーバーで持たせます。判断の目安は、文章で書ける手順ならスキル、入力と出力の型が決まった処理ならツール、他のアプリとも共有したい機能ならMCPです。スキルの中でスクリプトを動かしたい場合は、次章のサンドボックスと組み合わせます。

Workspaceのサンドボックスによるコマンド実行

「mastra sandbox」で検索される機能の実体は、Workspaceの sandbox です。公式のSandboxes解説では、リポジトリをクローンしてテストを流す、PDFを専用ライブラリで処理する、長時間の作業を別環境で並行させる、といった用途が挙がっています。利用できるツールはバックエンドの対応機能で変わります。バックグラウンドプロセスに対応する静的サンドボックス、またはリクエストごとに解決するサンドボックスを付けたエージェントには、execute_command・get_process_output・kill_process のツールが自動で付きます。

import { Agent } from '@mastra/core/agent'
import { LocalSandbox, Workspace } from '@mastra/core/workspace'

const workspace = new Workspace({
  sandbox: new LocalSandbox({ workingDirectory: './workspace' }),
  tools: { requireApproval: true },  // エージェントがツールを呼ぶ前に人の承認を挟む
})

export const codingAgent = new Agent({
  id: 'coding-agent',
  name: 'Coding agent',
  instructions: 'サンドボックスでコーディング作業をしてください。',
  model: 'openai/gpt-6.1-sol',
  workspace,
})

// アプリのコードから直接実行することもできる（この場合は承認を挟まない）
const r = await workspace.sandbox.executeCommand('echo', ['hello-from-sandbox'])
console.log(r.exitCode, r.stdout)  // 0 'hello-from-sandbox\n'

requireApproval はエージェントがツールとして呼ぶときに効く設定で、workspace.sandbox.executeCommand() を直接呼ぶと承認は挟まらず、すぐに結果が返りました。ここで最も注意すべきなのは、LocalSandbox が既定ではアプリと同じマシンでコマンドを実行し、隔離されていないことです。公式も「隔離されておらず安全ではない」と警告しています。ユーザーの入力からコマンドが組み立てられるエージェントでは、LocalSandboxをそのまま本番に出してはいけません。ネイティブ隔離を有効にするか、Docker・E2B・Daytona・Modal・Cloudflare Sandboxなどの外部サンドボックスに替えてください。もう1点、サンドボックスを1つだけ定義すると全ユーザー・全スレッドで共有されます。ユーザーごとに環境を分けるなら、sandbox にリクエストごとに別のサンドボックスを返す関数を渡します。

メモリ：Observational Memoryとストレージの選び方

Observational Memoryの有効化

会話をまたいだ記憶は @mastra/memory の Memory で持たせます。次の例を実行する前に、npm install @mastra/memory @mastra/libsql で追加パッケージを導入してください。メモリの公式解説では、会話履歴（message history）を土台に、ユーザーの名前や好みを構造化して保つワーキングメモリ、意味の近い過去発言を引く意味的想起（semantic recall）を足す構成で、さらにObservational Memoryを「推奨」としています。

import { Agent } from '@mastra/core/agent'
import { Memory } from '@mastra/memory'
import { LibSQLStore } from '@mastra/libsql'

export const agent = new Agent({
  id: 'support-agent',
  name: 'support-agent',
  instructions: 'あなたはサポート担当です。',
  model: 'openai/gpt-6.1-sol',
  memory: new Memory({
    storage: new LibSQLStore({ id: 'memory', url: 'file:./memory.db' }),
    options: { observationalMemory: true },
  }),
})

Observational Memoryの公式説明によると、既定の非同期処理では、Observerが約6,000トークンごとに観察メモを先行作成し、会話履歴が30,000トークンに達すると準備済みのメモを有効化して、観察済みの履歴をコンテキストから置き換えます。メモが増えるとReflectorがさらにまとめ直します。長い会話でもコンテキストが膨らみにくい一方、要約のたびにモデルを呼ぶので、その分のトークン費用がかかります。使えるストレージは @mastra/pg・@mastra/libsql・@mastra/mysql・@mastra/mongodb・@mastra/convex・@mastra/oracledb に限られます。

ストレージ（DB）の選び方

開発中はローカルファイルに保存できるLibSQL（@mastra/libsql）が手軽です。本番で複数台のサーバーから同じ記憶を読むならPostgreSQL（@mastra/pg）が無難で、pgvectorを使えばRAGのベクトル保存先も1つにまとめられます。前章で見たとおり、ストレージを設定しないとメモリ上に保存され、再起動で消えます。Observational Memoryを使うなら、上の6種から選んでください。

RAGによる自社ドキュメントの検索と参照

RAGは @mastra/rag の MDocument で文書を分割し、埋め込みを作ってベクトルストアに保存し、質問時に近い断片を取り出す流れです。RAGの公式解説の例では strategy: 'recursive'・size: 512・overlap: 50 で分割しています。対応するベクトルストアにはpgvector・OracleDB・Pinecone・Qdrant・MongoDBなどがあります。検索をエージェントの判断に任せる構成の考え方はエージェンティックRAGとは？RAGとAIエージェントの違いと組み合わせる仕組みで扱っています。

デプロイとMastra platformの料金

デプロイの公式解説によると、Mastraは mastra build でHonoベースのHTTPサーバーとしてビルドし、VM・コンテナ・PaaSに載せられます。ビルド結果は普通のNode.jsアプリなので、Dockerでの運用も他のNode.jsアプリと同じです。Vercel・Netlify・Cloudflare向けのデプロイヤーがあり、AWS Lambda・EC2・Amazon Bedrock AgentCore・Azure App Servicesなどの手引きもあります。Next.js・Astro・Express・Honoなどの既存アプリの中に組み込む構成も取れます。

自前で運用しない場合は、マネージドのMastra platform（Studio・Server・Observability）を使います。公式の料金ページの内容は次のとおりです（2026年10月30日確認）。

表は主な項目の抜粋です。ほかにデータ転送量（Starterは10GBまで、超過は1GBあたり0.10ドル）、常時稼働サーバー（1プロジェクトあたり100ドル）、Gateway経由のモデル利用（市場価格＋5.5%）などが加わります。Starterでもユーザー数・デプロイ数・プロジェクト数は無制限で、SSOとSOC 2の資料はTeamsから、RBAC・監査ログ・稼働率のSLAはEnterpriseで提供されます。Apache-2.0の範囲の機能を自前のサーバーで動かす限り、Mastraへの支払いは発生しません。Agent BuilderやRBAC・SSOのような ee/ 配下の機能を本番で自前ホストする場合は、年額固定のEnterpriseライセンスの契約が必要です。

Mastra Code：Mastraで作られたコーディングエージェント

「mastra code」で探しているのが別製品のMastra Codeであることもあります。これは2026年2月24日に公式ブログで発表されたターミナル型のコーディングエージェントで、npm install -g mastracode で入ります（npmの最新は0.48.1で、要件はNode.js 22.19.0以上）。Observational Memoryで会話を圧縮し続けるため、長いセッションでも文脈を失いにくいのが売りです。Mastraの部品で作られたアプリの1つであり、フレームワークとしてのMastraを使うのに必須ではありません。

LangChain・Vercel AI SDKとの比較と選ぶ条件

同じTypeScriptの選択肢と比べると、違いは「どこまでを1つのパッケージで面倒を見るか」です。

MastraはモデルとのやりとりにVercel AI SDKを使い、その上にメモリ・ワークフロー・スキル・評価を足した構成です。AI SDK単体の機能はVercel AI SDK v6とは？新機能（ToolLoopAgent・needsApproval）とv7との違い・移行【2026】、LangChain.jsはLangChain.jsとは？npm導入からcreateAgent・構造化出力・会話メモリまで【v1.5対応】、Python側も含めた8種の比較はAIエージェントフレームワークとは？主要8種の比較・動作コード・選定基準【2026年9月版】で確認できます。

Mastraを選ばない方がよい場面

選ぶべきなのは、TypeScriptで、会話をまたぐ記憶・多段のワークフロー・スキル・サンドボックスまで1つにまとめたい場合です。逆に、チャット画面を1つ作るだけならVercel AI SDK単体で足ります。Mastraを入れると依存が増え、版を上げるたびにリリースノートで破壊的変更を確かめる保守作業も増えます。チームの主力言語がPythonで、TypeScriptのサーバーを別に運用する体制が無いなら、Mastraは選ばずPythonのフレームワークを使うべきです。社内の業務フローにエージェントを組み込む設計から相談したい場合は、AIエージェント開発の支援も行っています。

よくある質問

MastraはPythonで使えますか？

使えません。公式のPython版は無く、pip install mastra もできません。PythonのアプリからMastraのエージェントを使うなら、mastra build で作ったサーバーのREST APIを呼びます。

Mastra SkillsとClaudeのAgent Skillsは同じものですか？

形式は同じです。どちらもAgent Skills仕様の SKILL.md を使います。公式のMastra SkillsはClaude Codeなどに入れるスキル集で、Mastraの createSkill() やWorkspaceの skills は、同じ形式のスキルを自作のエージェントに読ませる機能です。

Mastraは無料ですか？

フレームワーク本体はApache-2.0で無料です。マネージドのMastra platformはStarterが月0ドル、Teamsが月250ドルで、観測イベント・CPU時間・データ転送量などの超過分や常時稼働サーバーの料金が加わります。

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

あります。Node.js版のCLIの npx mastra@latest init が、既存のプロジェクトにMastraを追加するコマンドです。新規作成は npm create mastra@latest、開発サーバーは mastra dev、本番ビルドは mastra build を使います。Pythonのコマンドではありません。

MastraはBunで動きますか？

動きます。公式のデプロイ解説は、Node.js v22.13.0以上・Bun・Deno・Cloudflareを実行環境に挙げています。プロジェクト作成は bunx create-mastra です。

Mastraの最新バージョンはいくつですか？

2026年10月28日公開の @mastra/core 1.80.0です（CLIの mastra は1.36.0）。マイナー版の公開が速いため、最新は npm view @mastra/core version で確かめてください。

関連記事

• Claude Skillsとは？SKILL.mdの書き方とclaude.ai・Claude Code・APIでの使い方【2026年10月】
• AIエージェントフレームワークとは？主要8種の比較・動作コード・選定基準【2026年9月版】
• Vercel AI SDK v6とは？新機能（ToolLoopAgent・needsApproval）とv7との違い・移行【2026】
• LangChainとLangGraphの違いと使い分け｜v1.0以降の関係をコードで確認【2026年10月】
• MCP（Model Context Protocol）とは？仕組み・APIとの違い・MCPサーバーの作り方