Mastra クラス
Mastra クラスは、あらゆる Mastra アプリケーションの中心的なオーケストレーターであり、Agent、Workflow、ストレージ、ロギング、可観測性などを管理します。通常は、アプリケーション全体を連携させるために Mastra のインスタンスを 1 つ作成します。
Mastra は、アプリケーション全体からアクセスする必要がある Agent、Workflow、Tool、その他のコンポーネントを登録する最上位のレジストリと考えることができます。
使用例使用例への直接リンク
src/mastra/index.ts
import { Mastra } from '@mastra/core'
import { PinoLogger } from '@mastra/loggers'
import { LibSQLStore } from '@mastra/libsql'
import { weatherWorkflow } from './workflows/weather-workflow'
import { weatherAgent } from './agents/weather-agent'
export const mastra = new Mastra({
workflows: { weatherWorkflow },
agents: { weatherAgent },
storage: new LibSQLStore({
id: 'mastra-storage',
url: ':memory:',
}),
logger: new PinoLogger({
name: 'Mastra',
level: 'info',
}),
})
遅延通知レコードと通知サマリーを Workflow スケジューラー経由で自動配信する場合は、通知のスケジュール配信を有効にします。
src/mastra/index.ts
export const mastra = new Mastra({
agents: { supportAgent },
storage,
notifications: {
dispatch: {
enabled: true,
cron: '*/1 * * * *',
batchSize: 100,
},
},
})
notifications.dispatch.enabled を指定すると、内部ディスパッチャー Workflow がデフォルトの cron */1 * * * * で実行できるようになります。ディスパッチャーは、配信期限を迎えた通知レコードをストレージから読み取り、agentId、resourceId、threadId ごとにサマリーをグループ化し、Agent のスレッドランタイムを通じてシグナルを送出します。これはユーザー向けのエントリーポイントではありません。配信スケジュールと、それを支える Workflow スケジューラーは、最初の遅延通知またはサマリー通知が発生した時点で遅延起動されます。そのため、通知を遅延させないアプリではスケジューラー自体が実行されません。
コンストラクターパラメーターコンストラクターパラメーターへの直接リンク
利用可能なすべての設定オプションの詳細については、設定リファレンスを参照してください。
agents?:
Record<string, Agent>
= {}
名前をキーとして登録する Agent インスタンス
tools?:
Record<string, ToolApi>
= {}
登録する Tool インスタンス。キーは `getTool()` で使用する登録キーで、値は Tool インスタンスです。固有 ID で検索するには `getToolById()`、レジストリを読み取るには `listTools()` を使用します。
storage?:
MastraCompositeStore
データを永続化するためのストレージエンジンインスタンス
vectors?:
Record<string, MastraVector>
セマンティック検索やベクトルベースの Tool に使用するベクトルストアインスタンス（例: Pinecone、PgVector、Qdrant）
logger?:
Logger
= Console logger with INFO level
new PinoLogger() で作成した Logger インスタンス
idGenerator?:
(context?: IdGeneratorContext) => string
カスタム ID 生成関数。Agent、Workflow、Memory、その他のコンポーネントが一意の識別子を生成する際に使用します。コンテキストに応じた ID 形式をサポートするため、idType、source、entityId、threadId などの任意のコンテキストを受け取ります。
workflows?:
Record<string, Workflow>
= {}
登録する Workflow。キーと値のペアで構成され、キーは Workflow 名、値は Workflow インスタンスです。
tts?:
Record<string, MastraVoice>
音声合成に使用するテキスト読み上げ Provider
observability?:
ObservabilityEntrypoint
トレースと監視のための可観測性設定
environment?:
string
デプロイ環境名（例:
production、staging、development）。設定すると、各呼び出しで tracingOptions.metadata.environment を渡さなくても環境で絞り込めるよう、すべての可観測性シグナルに自動的に付加されます。未設定の場合は process.env.NODE_ENV にフォールバックし、どちらも設定されていなければ undefined のままです。呼び出しごとの tracingOptions.metadata.environment が常に優先されます。deployer?:
MastraDeployer
デプロイを管理する MastraDeployer のインスタンス。
server?:
ServerConfig
ポート、ホスト、タイムアウト、API ルート、ミドルウェア、CORS 設定、および Swagger UI、API リクエストロギング、OpenAPI ドキュメントのビルドオプションを含むサーバー設定。
mcpServers?:
Record<string, MCPServerBase>
キーがレジストリキー（getMCPServer() で使用）、値が MCPServer のインスタンスまたは MCPServerBase を拡張したクラスであるオブジェクト。各 MCPServer には id プロパティが必要です。サーバーは getMCPServer() を使ってレジストリキーで取得するか、getMCPServerById() を使って固有 id で取得できます。
bundler?:
BundlerConfig
= { externals: [], sourcemap: false, transpilePackages: [], dynamicPackages: [] }
externals、sourcemap、transpilePackages、dynamicPackages のオプションを含むアセットバンドラーの設定。
scorers?:
Record<string, Scorer>
= {}
Agent の応答と Workflow の出力を評価する Scorer
processors?:
Record<string, Processor>
= {}
Agent の入力と出力を変換する入出力 Processor
gateways?:
Record<string, MastraModelGateway>
= {}
代替 Provider やプライベートデプロイを通じて AI モデルへアクセスするために登録するカスタムモデル Gateway。キーと値のペアで構成され、キーはレジストリキー（getGateway() で使用）、値は Gateway インスタンスです。
memory?:
Record<string, MastraMemory>
= {}
登録する Memory インスタンス。保存済みの Agent から参照し、実行時に解決できます。キーと値のペアで構成され、キーはレジストリキー、値は Memory インスタンスです。
notifications?:
object
通知シグナル配信のランタイム設定。
object
dispatch?:
NotificationDispatchConfig
遅延通知と通知サマリーのスケジュール配信設定。配信はデフォルトで有効です。
object
enabled?:
boolean
自動スケジュール通知配信を無効にするには
false に設定します。cron?:
string
内部通知ディスパッチャー Workflow が使用する cron スケジュール。
batchSize?:
number
1 回の配信実行で処理する、配信期限を迎えた通知レコードの最大数。
versions?:
VersionOverrides
サブ Agent への委譲に使用するグローバルなバージョンオーバーライド。Supervisor Agent がサブ Agent に委譲するとき、コードで定義されたデフォルトの代わりに使用する、そのサブ Agent の保存済みバージョンをこのオーバーライドで決定します。Editor パッケージの設定が必要です。詳細は Editor のバージョン管理を参照してください。
VersionOverrides
agents?:
Record<string, VersionSelector>
Agent ID からバージョンセレクターへのマップ。各セレクターは、ID または公開ステータスによって特定のバージョンを指定できます。
VersionSelector
versionId?:
string
使用する特定バージョンの ID。
status?:
'draft' | 'published'
この公開ステータスを持つ最新バージョンを選択します。
workers?:
MastraWorker[] | false
この Mastra インスタンスで実行する Worker を設定します。省略すると、Mastra が PubSub と設定に基づいてデフォルトの Worker を自動作成します。すべてのイベント処理を無効にするには
false を渡します（スタンドアロン Worker を別に実行する場合に便利です）。カスタム Worker を追加するには MastraWorker[] を渡します。これらは自動作成されたデフォルトとマージされ、デフォルトと同じ name を持つカスタム Worker はデフォルトを置き換えます。backgroundTasks?:
BackgroundTaskManagerConfig
Agent の バックグラウンドタスク実行を設定します。すべてのオプションについては、バックグラウンドタスク設定リファレンスを参照してください。
BackgroundTaskManagerConfig
enabled?:
boolean
バックグラウンドタスクの配信を有効にします。
globalConcurrency?:
number
すべての Agent を通じた同時実行タスクの最大数。
perAgentConcurrency?:
number
Agent ごとの同時実行タスクの最大数。
backpressure?:
'queue' | 'reject' | 'fallback-sync'
同時実行数の上限に達したときの動作。
defaultTimeoutMs?:
number
デフォルトのタスクタイムアウト（ミリ秒）。
defaultRetries?:
RetryConfig
デフォルトのリトライ設定。
scheduler?:
object
cron による Workflow トリガーのための Scheduler Worker を設定します。いずれかの Workflow が
schedule を宣言すると自動的に有効になります。スケジュールされた Workflow を参照してください。object
enabled?:
boolean
Scheduler を明示的に有効または無効にします。
メソッドメソッドへの直接リンク
recoverAllDurableAgents()recoveralldurableagentsへの直接リンク
登録済みのすべての Durable Agent を対象に、孤立した running 状態の実行をすべて再駆動します。recovery.durableAgents が 'auto' の場合は起動時に自動的に呼び出されます。手動復旧やスケジュールタスクから直接呼び出すこともできます。
永続ストレージが必要です。インメモリストアでは、プロセスの再起動後に復旧できるものはありません。
const result = await mastra.recoverAllDurableAgents()
// { agents: 2, recovered: 3, succeeded: 3, failed: 0 }
戻り値:
agents:
number
スキャンした Durable Agent の数。
recovered:
number
再駆動した実行の合計数。
succeeded:
number
正常に再起動した実行の数。
failed:
number
再起動時にエラーがスローされた実行の数。