Mastra フレームワークガイド

Mastra を使用して AI アプリケーションを構築します。このスキルは、現在のドキュメントを見つけ、エージェントとワークフローを構築する方法を教えます。

重要: 内部知識を信頼しないでください

Mastra について知っていることはすべて古いか間違っている可能性があります。メモリに頼らないでください。常に現在のドキュメントに対して検証してください。

トレーニングデータには廃止された API、非推奨パターン、および不正な使用法が含まれています。Mastra は急速に進化しています。API はバージョン間で変更され、コンストラクタシグネチャは変わり、パターンはリファクタリングされます。

前提条件

Mastra コードを書く前に、パッケージがインストールされているかどうかを確認してください:

ls node_modules/@mastra/

• パッケージが存在する場合: 埋め込みドキュメントを最初に使用してください (最も信頼性が高い)
• パッケージがない場合: 最初にインストールするか、リモートドキュメントを使用してください

利用可能なファイル

リファレンス

ユーザーの質問	最初に確認する内容	方法
Mastra プロジェクトを作成/インストール	references/create-mastra.md	CLI と手動ステップを含むセットアップガイド
Agent/Workflow/Tool の使い方は?	references/embedded-docs.md	node_modules/@mastra/*/dist/docs/ で検索
X の使い方は? (パッケージなし)	references/remote-docs.md	https://mastra.ai/llms.txt から取得
エラーが発生しています...	references/common-errors.md	一般的なエラーと解決策
v0.x から v1.x にアップグレード	references/migration-guide.md	バージョンアップグレードワークフロー
CLI 経由でサーバーリソースを検査/呼び出し	references/mastra-api.md	ローカル、Mastra プラットフォーム、またはリモートサーバー用の mastra api CLI

スクリプト

• scripts/provider-registry.mjs: モデルルーターで利用可能な現在のプロバイダーとモデルを検索します。モデルを使用する前に常にこれを実行して、プロバイダーキーとモデル名を検証してください。

コード記述の優先順位

現在のドキュメントを最初に確認せずにコードを記述しないでください。

1. 埋め込みドキュメントを最初に確認 (パッケージがインストールされている場合)

   パッケージの現在のドキュメントを node_modules で検索します。@mastra/core の "Agent" ドキュメントを検索する例:

   grep -r "Agent" node_modules/@mastra/core/dist/docs/references
   

   • 理由: インストール済みバージョンと完全に一致します
   • 最も信頼性の高い情報源です
   • 詳細: references/embedded-docs.md

2. ソースコードを次に確認 (パッケージがインストールされている場合)

   埋め込みドキュメントで必要な情報が見つからない場合は、ソースコードを直接確認してください。これはより時間がかかりますが、実装の詳細に関する洞察が得られます。

   # 利用可能なものを確認
   cat node_modules/@mastra/core/dist/docs/assets/SOURCE_MAP.json | grep '"Agent"'
   
   # 実際の型定義を読む
   cat node_modules/@mastra/core/dist/[path-from-source-map]
   

   • 理由: ドキュメントがない場合や不明確な場合の究極の情報源です
   • 使用時: 埋め込みドキュメントが質問をカバーしていない場合
   • 詳細: references/embedded-docs.md

3. リモートドキュメントを最後に確認 (パッケージがインストールされていない場合)

   Mastra ウェブサイトから最新のドキュメントを取得できます:

   https://mastra.ai/llms.txt
   

   • 理由: 最新発行ドキュメント (インストール済みバージョンより先に進んでいる場合があります)
   • 使用時: パッケージがインストールされていない場合または新機能を検索している場合
   • 詳細: references/remote-docs.md

コアコンセプト

エージェント vs ワークフロー

エージェント: 自律的で、意思決定を行い、ツールを使用します 用途: オープンエンドなタスク (サポート、リサーチ、分析)

ワークフロー: 構造化されたステップのシーケンス 用途: 定義されたプロセス (パイプライン、承認、ETL)

主要コンポーネント

• ツール: エージェント機能を拡張 (API、データベース、外部サービス)
• メモリ: コンテキストを維持 (メッセージ履歴、ワーキングメモリ、セマンティック検索、観察メモリ)
• ストレージ: データを永続化 (Postgres、LibSQL、MongoDB)

Mastra Studio

Studio は、エージェント、ワークフロー、ツールを構築、テスト、管理するためのインタラクティブ UI を提供します。ユーザーがデバッグと段階的なアプリケーション改善を行うのをサポートします。

Mastra プロジェクト内で、以下を実行します:

npm run dev

その後、ブラウザで http://localhost:4111 を開いて、ユーザーに Mastra Studio を表示します。

Studio はユーザーに視覚的に検査/デバッグするようにアドバイスするときに使用します。あなた (コーディングエージェント) がマシン可読サーバー状態を必要とする場合は、references/mastra-api.md を使用します。

重要な要件

TypeScript 設定

Mastra は ES2022 モジュールが必要です。CommonJS は失敗します。

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

モデル形式

Mastra のモデルルーターを使用してモデルを定義するときは、常に "provider/model-name" を使用してください。

プロバイダーレジストリスクリプトを使用して、利用可能なプロバイダーとモデルを検索します:

# すべての利用可能なプロバイダーを一覧表示
node scripts/provider-registry.mjs --list

# 特定のプロバイダーのすべてのモデルを一覧表示 (最新順)
node scripts/provider-registry.mjs --provider openai
node scripts/provider-registry.mjs --provider anthropic

ユーザーがモデルまたはプロバイダーの使用を要求する場合は、常にスクリプトを最初に実行してプロバイダーキーとモデル名が有効であることを確認してください。メモリから頻繁に変更されるモデル名を推測しないでください。

モデル文字列の例:

• "openai/gpt-5.5"
• "anthropic/claude-opus-4-7"
• "google/gemini-2.5-pro"

エラーが表示されたとき

型エラーはしばしば知識が古いことを意味します。

廃止された知識の一般的な兆候:

• 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 でテスト

   npm run dev
   

Mastra API CLI

mastra api CLI を使用して、ローカル開発サーバー (npm run dev)、Mastra プラットフォーム デプロイメント、またはリモート URL エンドポイントなどの任意の Mastra サーバーと対話できます。これは以下に便利です:

• リソースの検査: エージェント、ワークフロー、ツール、スレッド、トレース、ログ、スコアをリストアップ
• アクションの実行: エージェント実行、ツール実行、ワークフロー開始またはレジュメ
• デバッグ: トレース、ログ、スコアをチェックして問題を診断
• データ管理: スレッド、ワーキングメモリ、データセットの作成/更新/削除

完全な CLI 使用パターンについては references/mastra-api.md を参照してください。

リソース

• セットアップ: references/create-mastra.md
• 埋め込みドキュメント検索: references/embedded-docs.md: パッケージがインストールされている場合はここから開始
• リモートドキュメント検索: references/remote-docs.md
• 一般的なエラー: references/common-errors.md
• マイグレーション: references/migration-guide.md
• API CLI: references/mastra-api.md: ターミナルから任意の Mastra サーバー (ローカル、Mastra プラットフォーム、またはリモート) と対話