跳至主要內容

Mastra 類別

Mastra 類別是所有 Mastra 應用程式的中央協調器，負責管理 Agent、Workflow、儲存空間、記錄、可觀測性等。一般而言，你會建立單一 Mastra 實例來協調應用程式。

你可以將 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 thread runtime 發出信號。它並非面向使用者的入口點。派送排程（以及支援它的 Workflow 排程器）會在首次出現延後或摘要通知時才按需啟動，因此從不延後通知的應用程式完全不會執行排程器。

建構函式參數
建構函式參數 的直接連結

有關所有可用設定選項的詳細文件，請參閱設定參考。

agents?:

Record<string, Agent>
= {}
要註冊的 Agent 實例，以名稱作為鍵

tools?:

Record<string, ToolApi>
= {}
要註冊的 Tool 實例。鍵是 `getTool()` 使用的註冊鍵，值則是 Tool 實例。使用 `getToolById()` 按內在 ID 查找，並使用 `listTools()` 讀取註冊表。

storage?:

MastraCompositeStore
用來保存資料的儲存引擎實例

vectors?:

Record<string, MastraVector>
向量儲存實例，用於語意搜尋及向量式 Tool（例如 Pinecone、PgVector 或 Qdrant）

logger?:

Logger
= INFO 層級的控制台記錄器
使用 new PinoLogger() 建立的記錄器實例

idGenerator?:

(context?: IdGeneratorContext) => string
自訂 ID 產生器函式。Agent、Workflow、記憶體及其他元件會用它產生唯一識別碼。它會接收可選的上下文，例如 idType、source、entityId 及 threadId，以支援可感知上下文的 ID 格式。

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 路由、middleware、CORS 設定，以及 Swagger UI、API 請求記錄和 OpenAPI 文件的建置選項。

mcpServers?:

Record<string, MCPServerBase>
此物件的鍵是註冊鍵（供 getMCPServer() 使用），值是 MCPServer 實例或繼承 MCPServerBase 的類別。每個 MCPServer 都必須有 id 屬性。你可使用 getMCPServer() 按註冊鍵擷取伺服器，或使用 getMCPServerById() 按其內在 id 擷取。

bundler?:

BundlerConfig
= { externals: [], sourcemap: false, transpilePackages: [], dynamicPackages: [] }
資產 bundler 的設定，提供 externals、sourcemap、transpilePackages 及 dynamicPackages 選項。

scorers?:

Record<string, Scorer>
= {}
用於評估 Agent 回應及 Workflow 輸出的 Scorer

processors?:

Record<string, Processor>
= {}
用於轉換 Agent 輸入及輸出的輸入／輸出 Processor

gateways?:

Record<string, MastraModelGateway>
= {}
要註冊的自訂模型 gateway，用於透過替代 Provider 或私有部署存取 AI 模型。結構為鍵值組合，鍵是註冊鍵（供 getGateway() 使用），值是 gateway 實例。

memory?:

Record<string, MastraMemory>
= {}
要註冊的記憶體實例。已儲存的 Agent 可以參照這些實例，並在 runtime 解析。結構為鍵值組合，鍵是註冊鍵，值是記憶體實例。

notifications?:

object
通知信號派送的 runtime 設定。
object

dispatch?:

NotificationDispatchConfig
延後通知及通知摘要的排程派送設定。派送預設為啟用。
object

enabled?:

boolean
設定為 false，即可停用自動排程通知派送。

cron?:

string
內部通知派送器 Workflow 使用的 Cron 排程。

batchSize?:

number
每次派送執行最多可處理的到期通知記錄數目。

versions?:

VersionOverrides
子 Agent 委派的全域版本覆寫。當 supervisor Agent 委派工作給子 Agent 時，這些覆寫會決定使用該子 Agent 的哪個已儲存版本，而非程式碼所定義的預設版本。必須設定 editor package。詳情請參閱 Editor 版本控制。
VersionOverrides

agents?:

Record<string, VersionSelector>
Agent ID 至其版本選擇器的對應表。每個選擇器可按 ID 或發佈狀態指定特定版本。
VersionSelector

versionId?:

string
要使用的特定版本 ID。

status?:

'draft' | 'published'
選取具有此發佈狀態的最新版本。

workers?:

MastraWorker[] | false
設定哪些 worker 在此 Mastra 實例中執行。如省略，Mastra 會根據你的 PubSub 及設定自動建立預設 worker。傳入 false 可停用所有事件處理（適合另外執行獨立 worker 時使用）。傳入 MastraWorker[] 可加入自訂 worker——它們會與自動建立的預設 worker 合併，而與預設 worker 具有相同 name 的自訂 worker 會取代該預設 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 觸發程序的排程器 worker。任何 Workflow 宣告 schedule 時便會自動啟用。請參閱排程 Workflow。
object

enabled?:

boolean
明確啟用或停用排程器。

recovery?:

MastraRecoveryConfig
= { durableAgents: 'off' }
啟動時復原孤立 Agent 及 Workflow 執行的行為。請參閱崩潰復原。
object

durableAgents?:

'auto' | 'off'
設定為 'auto'，可在伺服器啟動時自動重新驅動孤立且處於 RUNNING 狀態的 durable Agent 執行。復原會再次發出 LLM 呼叫並重新執行 Tool 呼叫，因此 Tool 必須具備冪等性。請參閱崩潰復原。

方法
方法 的直接連結

recoverAllDurableAgents()
recoveralldurableagents 的直接連結

重新驅動所有已註冊 durable Agent 中每個孤立且處於 running 狀態的 durable Agent 執行。當 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
重新啟動時擲回錯誤的執行數目。
On this page