mastra dev

mastra dev コマンドは、エージェント、ツール、ワークフロー用の REST エンドポイントを公開する開発サーバーを起動します。

使い方

mastra dev [options]

オプション

ルート

mastra dev でサーバーを起動すると、既定で一連の REST ルートが公開されます。

システムルート

• GET /api: API のステータスを取得します。

エージェントのルート

エージェントは src/mastra/agents からエクスポートすることが想定されています。

• GET /api/agents: Mastra フォルダーで見つかった登録済みエージェントを一覧表示します。
• GET /api/agents/:agentId: ID を指定してエージェントを取得します。
• GET /api/agents/:agentId/evals/ci: エージェント ID ごとの CI 評価を取得します。
• GET /api/agents/:agentId/evals/live: エージェント ID ごとのライブ評価を取得します。
• POST /api/agents/:agentId/generate: 指定したエージェントにテキストプロンプトを送信し、応答を返します。
• POST /api/agents/:agentId/stream: エージェントの応答をストリーミングします。
• POST /api/agents/:agentId/instructions: エージェントの指示を更新します。
• POST /api/agents/:agentId/instructions/enhance: 指示から改良版のシステムプロンプトを生成します。
• GET /api/agents/:agentId/speakers: エージェントで利用可能な話者を取得します。
• POST /api/agents/:agentId/speak: エージェントの音声プロバイダーを使用してテキストを音声に変換します。
• POST /api/agents/:agentId/listen: エージェントの音声プロバイダーを使用して音声をテキストに変換します。
• POST /api/agents/:agentId/tools/:toolId/execute: エージェント経由でツールを実行します。

ツールのルート

ツールは src/mastra/tools（または設定済みのツールディレクトリ）からエクスポートされることが想定されています。

• GET /api/tools: すべてのツールを取得します。
• GET /api/tools/:toolId: ID でツールを取得します。
• POST /api/tools/:toolId/execute: リクエストボディで入力データを渡して、指定した名前のツールを実行します。

ワークフローのルート

ワークフローは src/mastra/workflows（または設定されたワークフロー用ディレクトリ）からエクスポートする想定です。

• GET /api/workflows: すべてのワークフローを取得します。
• GET /api/workflows/:workflowId: IDでワークフローを取得します。
• POST /api/workflows/:workflowName/start: 指定したワークフローを開始します。
• POST /api/workflows/:workflowName/:instanceId/event: 既存のワークフローインスタンスにイベントまたはトリガーシグナルを送信します。
• GET /api/workflows/:workflowName/:instanceId/status: 実行中のワークフローインスタンスのステータス情報を返します。
• POST /api/workflows/:workflowId/resume: 一時停止中のワークフローステップを再開します。
• POST /api/workflows/:workflowId/resume-async: 一時停止中のワークフローステップを非同期で再開します。
• POST /api/workflows/:workflowId/createRun: 新しいワークフロー実行を作成します。
• POST /api/workflows/:workflowId/start-async: ワークフローを非同期で開始・実行します。
• GET /api/workflows/:workflowId/watch: ワークフローの遷移をリアルタイムで監視します。

メモリ関連ルート

• GET /api/memory/status: メモリのステータスを取得します。
• GET /api/memory/threads: すべてのスレッドを取得します。
• GET /api/memory/threads/:threadId: 指定したIDのスレッドを取得します。
• GET /api/memory/threads/:threadId/messages: 指定したスレッドのメッセージを取得します。
• GET /api/memory/threads/:threadId/messages/paginated: 指定したスレッドのメッセージをページネーション対応で取得します。
• POST /api/memory/threads: 新規スレッドを作成します。
• PATCH /api/memory/threads/:threadId: スレッドを更新します。
• DELETE /api/memory/threads/:threadId: スレッドを削除します。
• POST /api/memory/save-messages: メッセージを保存します。

テレメトリーのルート

• GET /api/telemetry: すべてのトレースを取得します。

ログルート

• GET /api/logs: すべてのログを取得します。
• GET /api/logs/transports: すべてのログトランスポートの一覧を取得します。
• GET /api/logs/:runId: 実行IDでログを取得します。

ベクター関連ルート

• POST /api/vector/:vectorName/upsert: ベクターをインデックスにアップサートします。
• POST /api/vector/:vectorName/create-index: 新しいベクターインデックスを作成します。
• POST /api/vector/:vectorName/query: インデックスからベクターをクエリします。
• GET /api/vector/:vectorName/indexes: ベクターストア内のすべてのインデックスを一覧表示します。
• GET /api/vector/:vectorName/indexes/:indexName: 特定のインデックスの詳細を取得します。
• DELETE /api/vector/:vectorName/indexes/:indexName: 特定のインデックスを削除します。

OpenAPI仕様

• GET /openapi.json: プロジェクトのルートに対するOpenAPI仕様を自動生成して返します。
• GET /swagger-ui: APIドキュメントを閲覧できるSwagger UIにアクセスします。

追加の注意事項

ポートはデフォルトで 4111 です。ポート、ホスト名、HTTPS 設定は Mastra サーバーの設定で変更できます。詳細は Launch Development Server を参照してください。

使用するプロバイダー向けに、.env.development または .env ファイルで環境変数を設定していることを確認してください（例：OPENAI_API_KEY、ANTHROPIC_API_KEY など）。

Mastra フォルダ内の index.ts ファイルが、開発サーバーで読み取れるように Mastra インスタンスをエクスポートしていることを確認してください。

リクエスト例

mastra dev を実行後にエージェントをテストするには:

curl -X POST http://localhost:4111/api/agents/myAgent/generate \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Hello, how can you assist me today?" }
    ]
  }'

高度な使い方

mastra dev サーバーは、開発中に便利な追加の環境変数をいくつか 解釈して動作します。

ビルドキャッシュを無効化する

MASTRA_DEV_NO_CACHE=1 を設定すると、.mastra/ 配下のキャッシュ済みアセットを使わずに フルリビルドを強制できます：

MASTRA_DEV_NO_CACHE=1 mastra dev

これは、バンドラープラグインのデバッグ時や、古い出力が疑われる場合に役立ちます。

並列実行の制限

MASTRA_CONCURRENCY は、高コストな処理（主にビルドや評価のステップ）の並列実行数に上限を設けます。例:

MASTRA_CONCURRENCY=4 mastra dev

未設定のままにすると、CLI がマシンに応じた適切なデフォルト値を選択します。

カスタムプロバイダーのエンドポイント

Vercel AI SDK がサポートするプロバイダーを使用する場合、ベース URL を設定することで、プロキシや内部ゲートウェイ経由でリクエストをリダイレクトできます。OpenAI の場合:

OPENAI_API_KEY=<your-api-key> \
OPENAI_BASE_URL=https://openrouter.example/v1 \
mastra dev

Anthropic の場合:

OPENAI_API_KEY=<your-api-key> \
ANTHROPIC_BASE_URL=https://anthropic.internal \
mastra dev

これらの設定は AI SDK によって引き継がれ、openai() や anthropic() の呼び出しで機能します。

テレメトリーを無効化する

匿名の CLI 分析をオプトアウトするには、 MASTRA_TELEMETRY_DISABLED=1 を設定します。これにより、ローカルの Playground 内でのトラッキングも無効化されます。

MASTRA_TELEMETRY_DISABLED=1 mastra dev