> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/llms.txt

# Mastra 類別

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

你可以將 `Mastra` 視為頂層註冊表，用來註冊需要在整個應用程式中存取的 Agent、Workflow、Tool 及其他元件。

## 使用範例

```typescript
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 排程器自動傳送延後的通知記錄及通知摘要，請啟用排程通知派送：

```typescript
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 排程器）會在首次出現延後或摘要通知時才按需啟動，因此從不延後通知的應用程式完全不會執行排程器。

## 建構函式參數

有關所有可用設定選項的詳細文件，請參閱[設定參考](https://mastra.zisheng.pro/zh-HK/reference/configuration)。

**agents** (`Record<string, Agent>`): 要註冊的 Agent 實例，以名稱作為鍵 (Default: `{}`)

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

**storage** (`MastraCompositeStore`): 用來保存資料的儲存引擎實例

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

**logger** (`Logger`): 使用 new PinoLogger() 建立的記錄器實例 (Default: `INFO 層級的控制台記錄器`)

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

**workflows** (`Record<string, Workflow>`): 要註冊的 Workflow。結構為鍵值組合，鍵是 Workflow 名稱，值是 Workflow 實例。 (Default: `{}`)

**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`): 資產 bundler 的設定，提供 externals、sourcemap、transpilePackages 及 dynamicPackages 選項。 (Default: `{ externals: [], sourcemap: false, transpilePackages: [], dynamicPackages: [] }`)

**scorers** (`Record<string, Scorer>`): 用於評估 Agent 回應及 Workflow 輸出的 Scorer (Default: `{}`)

**processors** (`Record<string, Processor>`): 用於轉換 Agent 輸入及輸出的輸入／輸出 Processor (Default: `{}`)

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

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

**notifications** (`object`): 通知信號派送的 runtime 設定。

**notifications.dispatch** (`NotificationDispatchConfig`): 延後通知及通知摘要的排程派送設定。派送預設為啟用。

**notifications.dispatch.enabled** (`boolean`): 設定為 false，即可停用自動排程通知派送。

**notifications.dispatch.cron** (`string`): 內部通知派送器 Workflow 使用的 Cron 排程。

**notifications.dispatch.batchSize** (`number`): 每次派送執行最多可處理的到期通知記錄數目。

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

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

**versions.agents.versionId** (`string`): 要使用的特定版本 ID。

**versions.agents.status** (`'draft' | 'published'`): 選取具有此發佈狀態的最新版本。

**workers** (`MastraWorker[] | false`): 設定哪些 worker 在此 Mastra 實例中執行。如省略，Mastra 會根據你的 PubSub 及設定自動建立預設 worker。傳入 false 可停用所有事件處理（適合另外執行獨立 worker 時使用）。傳入 MastraWorker\[] 可加入自訂 worker——它們會與自動建立的預設 worker 合併，而與預設 worker 具有相同 name 的自訂 worker 會取代該預設 worker。

**backgroundTasks** (`BackgroundTaskManagerConfig`): 設定 Agent 的背景工作執行方式。所有選項請參閱背景工作設定參考。

**backgroundTasks.enabled** (`boolean`): 啟用背景工作派送。

**backgroundTasks.globalConcurrency** (`number`): 所有 Agent 合計可同時執行的工作數目上限。

**backgroundTasks.perAgentConcurrency** (`number`): 每個 Agent 可同時執行的工作數目上限。

**backgroundTasks.backpressure** (`'queue' | 'reject' | 'fallback-sync'`): 達到並行處理上限時的行為。

**backgroundTasks.defaultTimeoutMs** (`number`): 預設工作逾時（毫秒）。

**backgroundTasks.defaultRetries** (`RetryConfig`): 預設重試設定。

**scheduler** (`object`): 設定用於 cron 驅動 Workflow 觸發程序的排程器 worker。任何 Workflow 宣告 schedule 時便會自動啟用。請參閱排程 Workflow。

**scheduler.enabled** (`boolean`): 明確啟用或停用排程器。

**recovery** (`MastraRecoveryConfig`): 啟動時復原孤立 Agent 及 Workflow 執行的行為。請參閱崩潰復原。 (Default: `{ durableAgents: 'off' }`)

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

## 方法

### `recoverAllDurableAgents()`

重新驅動所有已註冊 durable Agent 中每個孤立且處於 `running` 狀態的 durable Agent 執行。當 `recovery.durableAgents` 為 `'auto'` 時，系統會在啟動時自動呼叫此方法。你亦可直接呼叫它，以手動復原或從排程工作執行復原。

此方法需要持久儲存空間。如使用記憶體內儲存空間，程序重新啟動後便沒有內容可供復原。

```typescript
const result = await mastra.recoverAllDurableAgents()
// { agents: 2, recovered: 3, succeeded: 3, failed: 0 }
```

傳回：

**agents** (`number`): 已掃描的 durable Agent 數目。

**recovered** (`number`): 已重新驅動的執行總數。

**succeeded** (`number`): 成功重新啟動的執行數目。

**failed** (`number`): 重新啟動時擲回錯誤的執行數目。