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 Specification

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

追加の注意事項

ポートはデフォルトで4111に設定されています。ポートとホスト名の両方は、mastraサーバー設定で構成できます。設定の詳細については、開発サーバーの起動を参照してください。

使用するプロバイダーの環境変数が.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を設定します。これにより、ローカルプレイグラウンド内でのトラッキングも防止されます。

MASTRA_TELEMETRY_DISABLED=1 mastra dev