mastra

Mastra フレームワークガイド

Mastra で AI アプリケーションを構築します。このスキルでは、最新のドキュメントを探し、エージェントとワークフローを構築する方法を学びます。

重要：内部知識を信用しないでください

Mastra について知っていることは、古くなっているか、間違っている可能性が高いです。記憶に頼らないでください。必ず最新のドキュメントで確認してください。

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

前提条件

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

ls node_modules/@mastra/

• パッケージがある場合：まず埋め込みドキュメントを使用します（最も信頼できます）
• パッケージがない場合：先にインストールするか、リモートドキュメントを使用します

リソース

リファレンス

ユーザーの質問	最初に確認する項目	方法
Mastra プロジェクトを作成／インストールする	references/create-mastra.md	CLI と手動の手順を含むセットアップガイド
Agent／Workflow／Tool／Memory／Storage を選ぶ	references/core-concepts.md	基本概念と各プリミティブを使う場面
Agent／Workflow／Tool の使い方を知りたい	references/embedded-docs.md	node_modules/@mastra/*/dist/docs/ を検索
X の使い方を知りたい（パッケージなし）	references/remote-docs.md	https://mastra.ai/llms.txt から取得
モデルを選択または検証する	references/model-selection.md	モデル形式とプロバイダーレジストリの検索
エラーが発生した場合	references/common-errors.md	よくあるエラーと解決方法
v0.x から v1.x にアップグレードする	references/migration-guide.md	バージョンアップグレードのワークフロー
CLI でサーバーのリソースを調査／呼び出す	references/mastra-api.md	ローカル、Mastra プラットフォーム、またはリモートサーバー向けの mastra api CLI
複雑な条件で正確なトレースを探す	references/trace-query.md	トレースフィールドまたは関連するスパン、スコア、フィードバックで完了済みトレースをクエリする
トレース数を数える、またはグループ化した指標（エラー率、レイテンシー、トークン、コスト）を計算する	references/trace-query.md	同じ選択条件で mastra api trace aggregate を使って完了済みトレースを集計する
個々のスパン（失敗したツール呼び出し、ネストされたエージェント実行）を一覧表示する	references/trace-query.md	mastra api span query とスパンフィールドの条件を使って完了済みスパンをクエリする
スパンごとの指標（ツールのエラー率、ネストされたエージェント実行、モデルのトークン数）を計算する	references/trace-query.md	mastra api span aggregate を使い、スパンフィールドでグループ化してスパンを集計する
Mastra にバグ／ドキュメントの不備を報告する	references/feedback.md	条件を満たす問題を自律的に Mastra チームに報告する

スクリプト

• scripts/provider-registry.mjs：モデルルーターで利用できる最新のプロバイダーとモデルを検索します。モデルを使用する前に必ず実行し、プロバイダーキーとモデル名を確認してください。

コードを書く際の優先順位

現在のドキュメントを確認せずにコードを書いてはいけません。

1. まず埋め込みドキュメントを確認する（パッケージがインストールされている場合）

   パッケージの最新ドキュメントを node_modules で確認してください。インストール済みの正確なバージョンに対応しており、最も信頼できる情報源です。詳しくは references/embedded-docs.md を参照してください。

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

   埋め込みドキュメントに質問への回答がない場合は、インストール済みのソースコードと型定義を確認してください。ドキュメントがない場合や不明確な場合は、これが信頼できる情報源です。詳しくは references/embedded-docs.md を参照してください。

3. その次にリモートドキュメントを確認する（パッケージがインストールされていない場合）

   パッケージがインストールされていない場合や、新機能を調査する場合は、公開されている最新のドキュメントを使用してください。リモートドキュメントは、ユーザーがインストールしているバージョンより先行している場合があります。詳しくは references/remote-docs.md を参照してください。

基本概念

エージェント、ワークフロー、ツール、メモリ、ストレージの選択には、references/core-concepts.md を使用してください。

• エージェント：判断を行い、ツールを使用する自由度の高いタスクに使用します。
• ワークフロー：手順が定義された複数ステップのプロセスに使用します。

Mastra Studio

Studio は、エージェント、ワークフロー、ツールを構築、テスト、管理するためのインタラクティブな UI です。人間のユーザーに視覚的な確認やデバッグを案内する場合は、Studio を使用してください。

Mastra プロジェクト内で、次を実行します。

npm run dev

次に、ブラウザーで http://localhost:4111 を開き、人間のユーザーに Mastra Studio を表示します。

Mastra API CLI

mastra api を使用すると、ローカル開発サーバー、Mastra プラットフォームへのデプロイ、またはリモート Mastra エンドポイント上のリソースを調査したり、呼び出したりできます。エージェントが読み取れる状態、実行、トレース、ログ、スコア、スレッド、ワークフロー操作に役立ちます。使用パターンについては、references/mastra-api.md を参照してください。

関連するスパン、スコア、フィードバックに対する再帰的な述語や条件を使ってトレースを正確に選択する必要がある場合は、references/trace-query.md を参照してください。mastra api trace query を使用する前に、インストール済みの CLI でそのコマンドが利用できることを確認してください。対象のリクエスト／レスポンスの形式と構造上の制約には --schema を使用し、サポートされているフィールド、演算子、セマンティクスについては、references/remote-docs.md から参照できる正式なドキュメントを使用してください。不透明なページネーションカーソルはそのまま保持し、候補を選択した後にのみトレースやスパンの詳細を取得してください。

Mastra Factory

Factory プロジェクト、作業項目、キューの健全性、意思決定、セッション履歴、メモリの確認、または許可された操作を扱う場合は、mastra-factory スキルを有効にしてください。Factory は運用管理プレーンであり、新しい Mastra アプリをひな形から作成したりデプロイしたりする理由にはなりません。

スキルが見つからない場合は、このリポジトリからインストールするよう提案してください。

npx skills add mastra-ai/skills --skill mastra-factory

ユーザーが意図するエージェントと範囲を、対話しながら選択してください。グローバルにインストールする場合は、--agent <agent> -g を指定して、サポート対象のエージェントを明示してください。PromptScript はグローバルインストールに対応していません。別のエージェントへのインストールに失敗した場合でも、対象のエージェントについて、インストールと参照先ファイルを確認してください。

Factory スキルでは、CLI の確認、mastra auth whoami／許可された mastra auth login、および任意のディレクトリからユーザーの実際のインスタンス URL を使用した接続を扱います。--url を使用する場合、デプロイ済みのリポジトリや .mastra-project.json は必要ありません。共有 Factory ホストやプロジェクト ID を推測してはいけません。接続とセッション確認に関するリファレンスでは、デプロイ固有の認証、プロジェクトの検出、スレッド、および観察に基づくメモリの制限について説明しています。

フィードバックの報告

references/feedback.md に記載された条件を満たす場合は、確認済みの Mastra のバグや、具体的なドキュメントの不備を、報告ごとに許可を求めずに自律的に報告してください。機能リクエストは人に任せてください。提出したり、不備として分類したりしないでください。現在のタスクまたは会話中に、同じ問題を再度報告しないでください。タスクを進める際は、フィードバック用に匿名化した事実のみを記録してください。確認できていない場合や、関連性が不明確な場合は、自動報告を見送ってください。分類のためだけにユーザーの作業を中断しないでください。何かを報告しないようユーザーから指示された場合は、それに従ってください。

重要な要件

TypeScript の設定

Mastra では ES2022 モジュールが必要です。CommonJS では動作しません。セットアップについては references/create-mastra.md、トラブルシューティングについては references/common-errors.md を参照してください。

モデルの形式

Mastra のモデルルーターでモデルを定義する際は、必ず "provider/model-name" を使用してください。

ユーザーからモデルまたはプロバイダーの使用を求められた場合は、プロバイダーキーとモデル名が有効か確認するため、必ず最初に scripts/provider-registry.mjs を実行してください。モデル名は頻繁に変わるため、記憶を頼りに推測しないでください。references/model-selection.md を参照してください。

エラーが発生した場合

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

知識が古くなっている兆候の例：

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

次の対応を行ってください。

1. references/common-errors.md を確認する
2. 埋め込みドキュメントで現在の API を確認する
3. エラーがユーザーの誤りだと決めつけない。知識が古くなっているのは自分かもしれない

開発ワークフロー

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

1. Mastra パッケージがインストールされているか確認する
2. 現在の API を調べる
   • インストールされている場合：埋め込みドキュメント references/embedded-docs.md を使用する
   • インストールされていない場合：リモートドキュメント references/remote-docs.md を使用する
3. 現在のドキュメントに基づいてコードを書く
4. 利用可能な場合は、プロジェクトのスクリプトまたは Studio でテストする