開発

Mastra プロジェクトを作成したら、Agent の開発、実行、テストを始められます。

Mastra をローカルで実行する

Agent の動作を最も手軽に確認できるのは Mastra Studio です。プロジェクトのルートから mastra dev を実行し、Studio とローカル開発サーバーを起動します。

npm

npx mastra dev

pnpm

pnpm dlx mastra dev

Yarn

yarn dlx mastra dev

Bun

bun x mastra dev

http://localhost:4111 で Studio を開き、Agent をテストして実行結果を確認します。

開発サーバーは、Agent、Tool、Workflow 用の API も公開します。http://localhost:4111/api を開いて利用可能な API を確認し、Mastra Client を使用してフロントエンドを接続します。

src/mastra/ ディレクトリを変更すると開発サーバーが自動的に再起動するため、開発中に手動で再起動する必要はありません。

AI を活用して構築する

Mastra は、コーディング Agent が高品質な Mastra コードを作成できるようにする Skill と CLI を提供します。

Mastra Skill

AI モデルが Mastra API に関する最新情報を持っているとは限りません。Mastra Skill を使用すると、実装ガイダンス、ベストプラクティス、最新の Mastra ドキュメントを取得する手順をコーディング Agent に提供できます。

Skill を手動でインストールするには、次を実行します。

npm

npx skills add mastra-ai/skills

pnpm

pnpm dlx skills add mastra-ai/skills

Yarn

yarn dlx skills add mastra-ai/skills

Bun

bun x skills add mastra-ai/skills

最新のガイダンスを利用できるよう、Skill を定期的に更新してください。

npm

npx skills update mastra

pnpm

pnpm dlx skills update mastra

Yarn

yarn dlx skills update mastra

Bun

bun x skills update mastra

注記

create mastra でプロジェクトを作成すると、コーディング Agent が検出して使用できるように Mastra Skill が自動的にインストールされます。

Mastra CLI

mastra CLI を使用すると、コーディング Agent は変更をテストして結果を確認するフィードバックループを構築できます。CLI から Agent、Workflow、Tool、メモリ、Evals、Trace、ログにアクセスできます。

たとえば、コーディング Agent は Agent を実行した後、Trace を取得して結果を確認できます。

npx mastra api --url http://localhost:4111 agent run agent '{"messages":"Hello"}'
npx mastra api --url http://localhost:4111 trace list

コーディング Agent が CLI の使い方を理解できるよう、Mastra Skillをインストールしてください。

プロジェクト構成

フレームワークを導入する際に最初に決めることの 1 つが、プロジェクトの構成です。フレームワークのコードは src/mastra/ 以下に配置し、関連するプリミティブを個別のファイルやフォルダーにまとめることを推奨します。設定と登録の中心には src/mastra/index.ts を使用します。

最小限のプロジェクト構成は次のようになります。

src/
  mastra/
    agents/
      agent.ts
    tools/
      tool.ts
    workflows/
      workflow.ts
    scorers/
      scorer.ts
    skills.ts
    index.ts

デフォルトのレイアウトと推奨規約については、プロジェクト構成リファレンスを参照してください。

ファイルベースの Agent

beta

ファイルベースの Agent はベータ版であり、安定版になるまでに変更される可能性があります。

ファイルベースの検出は、mastra dev または mastra build を介した場合にのみ実行されます。Web フレームワークやサーバーアダプター経由の場合を含め、アプリが mastra を直接インポートすると、ファイルベースの Agent は検出されません。そのような Agent はコードで登録するか、Mastra を別のサーバーとして実行してください。

📹 動画

最初のファイルベース Agent を作成する方法

ファイルベースの Agent では、Mastra が src/mastra/ 以下の対応ファイルから Agent と関連プリミティブを自動的に検出します。各プリミティブを Mastra インスタンスにインポートして登録する代わりに、規約に従ってファイルを整理します。

ファイルシステムがプロジェクト構成を直接表すため、コード内の接続関係をたどらなくても、開発者とコーディング Agent の双方がプロジェクト全体の構成を把握できます。

プロジェクト全体でファイルベースの Agent を使用することも、コードで定義したプリミティブと併用しながら段階的に導入することもできます。現時点では、Mastra のすべての機能やユースケースに対応しているわけではありません。

最初の Agent を作成する

ファイルベースの Agent は、src/mastra/agents/ 以下の専用ディレクトリに配置します。動作する Agent を作成するには、モデルとランタイムオプションを定義する config.ts ファイルと、常時適用されるプロンプトを記述する instructions.md ファイルを追加します。

src/mastra/agents/
  writing-assistant/
    config.ts
    instructions.md

ディレクトリ名が Agent のデフォルトの id と name になります。この例では、Mastra は Agent を writing-assistant として登録します。

src/mastra/agents/writing-assistant/config.ts

import { agentConfig } from '@mastra/core/agent'

export default agentConfig({
  model: 'openai/gpt-5.6-sol',
})

src/mastra/agents/writing-assistant/instructions.md

Rewrite text clearly and concisely.

npx mastra dev を実行して Studio を開き、writing-assistant を選択してテストします。

検出の仕組み

Mastra はパスを使用してファイルベースの機能を検出し、名前を付けます。Agent ディレクトリから、Agent のデフォルトの id と name が決まります。たとえば、tools/search_docs.ts は Tool を search_docs として登録し、skills/style-guide.md は Skill を style-guide として登録します。拡張用のパスを次に示します。

Agent を拡張する

Agent に機能が必要になったら、ファイルまたはディレクトリを追加します。

パス	追加される機能
tools/<tool-name>.ts	モデルが呼び出せる関数
skills/<skill-name>.md	関連する場合に Agent が読み込む詳細なガイダンス
memory.ts	会話履歴と作業コンテキスト
workspace.ts and workspace/	ファイルシステムとシェルへのアクセス
subagents/<agent-id>/	親 Agent が委任できる専門 Agent

各機能は、それを使用する Agent の近くに配置します。Mastra は開発サーバーの起動時または再起動時に、これらのファイルを検出して登録します。

対応しているすべてのファイル規約と設定オプションについては、ファイルベース Agent のリファレンスを参照してください。