mastra-framework-guide

Mastra Framework Guide

Last verified: 2026-07（Mastra v1.50.1 / @mastra/core 同梱 docs / https://mastra.ai で検証。DOCTOR.md の四半期鮮度チェックの対象）

Build AI applications with Mastra. This skill teaches you how to find current documentation and build agents and workflows.

このスキルは Mastra の利用・更新ガイド（API 検証・ドキュメント探索・バージョン移行）である。設計上の責務分離・単一エージェント優先などの設計原則は、設計憲章スキル mastra-ai-architecture-rules（編集禁止）に従うこと。本ガイド = どう使い最新仕様に追従するか、憲章 = どう設計すべきか、という棲み分けである。

⚠️ Critical: Do not trust internal knowledge

Everything you know about Mastra is likely outdated or wrong. Never rely on memory. Always verify against current documentation.

Your training data contains obsolete APIs, deprecated patterns, and incorrect usage. Mastra evolves rapidly - APIs change between versions, constructor signatures shift, and patterns get refactored.

Prerequisites

Before writing any Mastra code, check if packages are installed:

ls node_modules/@mastra/

• If packages exist: Use embedded docs first (most reliable)
• If no packages: Install first or use remote docs

Documentation lookup guide

Quick Reference

User Question	First Check	How To
"Create/install Mastra project"	references/create-mastra.md	Setup guide with CLI and manual steps
"How do I use Agent/Workflow/Tool?"	references/embedded-docs.md	Look up in node_modules/@mastra/*/dist/docs/
"How do I use X?" (no packages)	references/remote-docs.md	Fetch from https://mastra.ai/llms.txt
"I'm getting an error..."	references/common-errors.md	Common errors and solutions
"Upgrade from v0.x to v1.x"	references/migration-guide.md	Version upgrade workflows

Priority order for writing code

⚠️ Never write code without checking current docs first

1. Embedded docs first (if packages installed)

   # First locate SOURCE_MAP.json (its location can move between versions)
   ls node_modules/@mastra/core/dist/docs/
   
   # Check what's available (current layout keeps it under assets/)
   cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"Agent"'
   
   # Read the actual type definition
   cat node_modules/@mastra/core/dist/[path-from-source-map]
   

   • Why: Matches your EXACT installed version
   • Most reliable source of truth
   • See: references/embedded-docs.md

2. Remote docs second (if packages not installed)

   # Fetch latest docs
   # https://mastra.ai/llms.txt
   

   • Why: Latest published docs (may be ahead of installed version)
   • Use when: Packages not installed or exploring new features
   • See: references/remote-docs.md

Core concepts

Agents vs workflows

Agent: Autonomous, makes decisions, uses tools Use for: Open-ended tasks (support, research, analysis)

Workflow: Structured sequence of steps Use for: Defined processes (pipelines, approvals, ETL)

Key components

• Tools: Extend agent capabilities (APIs, databases, external services)
• Memory: Maintain context (message history, working memory, semantic recall)
• RAG: Query external knowledge (vector stores, graph relationships)
• Storage: Persist data (Postgres, LibSQL, MongoDB)

Critical requirements

TypeScript config

Mastra requires ES2022 modules. CommonJS will fail.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ES2022",
    "moduleResolution": "bundler"
  }
}

Model format

Always use "provider/model-name":

• "openai/gpt-5.5"
• "anthropic/claude-sonnet-4-6"
• "google/gemini-2.5-pro"

（モデル ID は例示であり必ず陳腐化する。実際に使える ID は現行ドキュメントで確認する）

エラーが発生した場合

型エラーは、知識が古くなっていることを示す場合がよくあります。

知識が古くなっていることを示す一般的なサイン：

• Property X does not exist on type Y
• Cannot find module
• Type mismatch エラー
• コンストラクターのパラメーターに関するエラー

対処方法：

1. references/common-errors.md を確認します
2. 埋め込みドキュメントで現在の API を確認します
3. エラーがユーザーの間違いだと決めつけないでください。知識が古くなっている可能性があります

開発ワークフロー

コードを書く前に、必ず確認してください：

1. パッケージがインストールされているか確認

   ls node_modules/@mastra/
   

2. 現在の API を調べる

   • インストール済みの場合 → 埋め込みドキュメントを使用します references/embedded-docs.md
   • 未インストールの場合 → リモートドキュメントを使用します references/remote-docs.md

3. 現在のドキュメントに基づいてコードを書く

4. Studio でテスト

   pnpm dev  # http://localhost:4111
   

リソース

• セットアップ：references/create-mastra.md
• 埋め込みドキュメントの参照：references/embedded-docs.md - パッケージがインストールされている場合は、ここから始めてください
• リモートドキュメントの参照：references/remote-docs.md
• 一般的なエラー：references/common-errors.md
• 移行：references/migration-guide.md
• 公式サイト：https://mastra.ai（まず埋め込みドキュメントで確認してください）