Playground
Mastra は、開発中にエージェント、ワークフロー、ツールをテストできるローカル開発環境を提供します。
ローカル開発サーバーは次のコマンドで起動します:
npm run devローカル開発サーバーでは、以下のインターフェースにアクセスできます:
- Playground: http://localhost:4111/
- Mastra API: http://localhost:4111/api
- OpenAPI 仕様: http://localhost:4111/openapi.json
- Swagger UI（API エクスプローラー）: http://localhost:4111/swagger-ui
ローカル開発用プレイグラウンド
Playgroundでは、エージェント、ワークフロー、ツールと対話できます。開発中の Mastra アプリケーションの各コンポーネントをテストするための専用インターフェースを提供しており、以下のアドレスで利用できます：http://localhost:4111/ 。
エージェント
Agent Playground のインタラクティブなチャットインターフェースを使って、開発中のエージェントをすばやくテストし、デバッグできます。
主な機能:
- チャットインターフェース: エージェントと会話し、リアルタイムの応答を確認できます。
- モデル設定: temperature や top-p などの設定を調整して、出力への影響を確かめられます。
- エージェントエンドポイント: エージェントが公開する利用可能な REST API ルートと、その使い方を確認できます。
- エージェントトレース: エージェントの裏側での処理、ツール呼び出し、判断などをステップごとに追跡できます。
- エージェント評価: エージェントに対してテストを実行し、パフォーマンスを評価できます。
Workflows
定義済みの入力を与え、Workflow Playground 上で各ステップを可視化しながらワークフローを検証します。
主な機能:
- Workflow Visualization: ワークフローをグラフで可視化し、ステップや分岐をひと目で追えます。
- Step Inputs & Outputs: 各ステップに入出力されるデータを確認し、全体の流れを把握できます。
- Run Workflows: 実際の入力でテストしてロジックを検証し、不具合をデバッグできます。
- Execution JSON: 実行の全体像を生の JSON で取得（入力、出力、エラー、結果を含む）。
- Workflow Traces: 各ステップの詳細な内訳を確認。データフロー、ツール呼び出し、発生したエラーまで掘り下げられます。
ツール
Tools Playground を使えば、エージェントやワークフロー全体を動かさずに、カスタムツールを単体で素早くテスト・デバッグできます。
主な機能:
- ツールを単体でテスト: エージェントやワークフロー全体を実行せず、個々のツールだけを試せます。
- 入力と応答: サンプル入力を送って、ツールの応答を確認できます。
- ツールの利用状況: どのエージェントがこのツールを使用し、どのように活用しているかを把握できます。
MCP サーバー
ローカルでの MCP サーバー開発における接続情報、ツール利用状況、IDE 設定を確認できます。
主な機能:
- 接続情報: MCP 環境を構成するために必要なエンドポイントや設定にアクセスできます。
- 利用可能なツール: 現在公開されているツールを一覧で確認でき、名称・バージョン・利用中のエージェントがわかります。
- IDE 設定: テストやツールの公開にすぐ使える設定を、ローカル環境にそのまま適用できます。
REST API エンドポイント
ローカル開発サーバーは Mastra Server を介して一連の REST API ルートを公開しており、デプロイ前にエージェントやワークフローをテスト・操作できます。
エージェント、ツール、ワークフローを含む利用可能な API ルートの詳細な一覧は、Routes reference を参照してください。
OpenAPI 仕様
ローカル開発サーバーには、次の場所で利用できる OpenAPI 仕様が用意されています: http://localhost:4111/openapi.json 。
本番サーバーに OpenAPI ドキュメントを含めるには、Mastra インスタンスで有効化してください:
import { Mastra } from "@mastra/core/mastra";
export const mastra = new Mastra({
server: {
build: {
openAPIDocs: true
}
},
});Swagger UI
ローカル開発サーバーにはインタラクティブな Swagger UI（API エクスプローラー）が用意されており、次の URL で利用できます: http://localhost:4111/swagger-ui 。
本番サーバーで Swagger UI を使用するには、Mastra インスタンスで有効にします:
import { Mastra } from "@mastra/core/mastra";
export const mastra = new Mastra({
server: {
build: {
swaggerUI: true
},
},
});アーキテクチャ
ローカル開発サーバーは、外部依存やコンテナに頼らず、完全に自己完結して動作します。以下を活用しています:
- コアの Mastra Server に対して Hono を用いた Dev Server。
- エージェントのメモリ、トレース、評価、ワークフローのスナップショット向けに LibSQL アダプタを利用する インメモリ ストレージ。
- 埋め込み、ベクター検索、セマンティックリトリーバル向けに FastEmbed を用いる ベクター ストレージ。
この構成により、データベースやベクターストアの準備は不要で、本番に近い挙動のまま、すぐに開発を始められます。
設定
既定ではサーバーはポート 4111 で動作します。Mastra サーバーの設定で host と port を変更できます。
import { Mastra } from "@mastra/core/mastra";
export const mastra = new Mastra({
server: {
port: 8080,
host: "0.0.0.0",
},
});ローカル HTTPS
Mastra は mastra dev でローカルの HTTPS サーバーを利用する方法を提供します（expo/devcert 経由）。--https フラグを使用すると、秘密鍵と証明書が作成され、プロジェクトで使用されます。デフォルトでは、別の host 値を指定しない限り、証明書は localhost 向けに発行されます。
mastra dev --httpsMastra サーバーの設定で server.https オプションを指定すると、独自の鍵と証明書ファイルを使用できます。
import { Mastra } from "@mastra/core/mastra";
import fs from 'node:fs'
export const mastra = new Mastra({
server: {
https: {
key: fs.readFileSync('path/to/key.pem'),
cert: fs.readFileSync('path/to/cert.pem')
}
},
});--https と server.https の両方を指定した場合は、後者が優先されます。
バンドラーのオプション
TypeScript のパッケージやライブラリをコンパイルするには transpilePackages を使用します。実行時に解決される依存関係を除外するには externals を、可読性の高いスタックトレースを出力するには sourcemap を使用します。
import { Mastra } from "@mastra/core/mastra";
export const mastra = new Mastra({
bundler: {
transpilePackages: ["utils"],
externals: ["ui"],
sourcemap: true
}
});そのほかの設定オプションは Mastra Class を参照してください。