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

# Mastra 類別

`Mastra` 類別是所有 Mastra 應用中的中央協調器，用於管理 Agent、Workflow、Storage、記錄、可觀測性等。通常，你會建立單一 `Mastra` 執行個體來協調應用。

可以將 `Mastra` 視為頂層 registry，用於註冊需要在整個應用中存取的 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 scheduler 自動交付延遲通知記錄和通知摘要，請啟用定時通知分發：

```typescript
export const mastra = new Mastra({
  agents: { supportAgent },
  storage,
  notifications: {
    dispatch: {
      enabled: true,
      cron: '*/1 * * * *',
      batchSize: 100,
    },
  },
})
```

`notifications.dispatch.enabled` 允許內部 dispatcher Workflow 使用預設 cron `*/1 * * * *` 執行。dispatcher 從 Storage 讀取到期通知記錄，依 `agentId`、`resourceId` 和 `threadId` 對摘要分組，並透過 Agent thread runtime 發出 signal。它不是面向使用者的入口。分發計劃（及其底層 Workflow scheduler）會在出現第一個延遲通知或摘要通知時延遲激活，因此從不延遲通知的應用不會執行 scheduler。

## 建構函式參數

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

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

**tools** (`Record<string, ToolApi>`): 要註冊的 Tool 執行個體。鍵是 \`getTool()\` 使用的註冊鍵，值是 Tool 執行個體。使用 \`getToolById()\` 依本身的 ID 尋找，使用 \`listTools()\` 讀取 registry。 (Default: `{}`)

**storage** (`MastraCompositeStore`): 用於持久儲存資料的 Storage engine 執行個體

**vectors** (`Record<string, MastraVector>`): 用於語義搜尋和基於 vector 的 Tool 的 vector store 執行個體（例如 Pinecone、PgVector 或 Qdrant）

**logger** (`Logger`): 使用 new PinoLogger() 建立的 Logger 執行個體 (Default: `Console logger with INFO level`)

**idGenerator** (`(context?: IdGeneratorContext) => string`): 自訂 ID 產生器函式。供 Agent、Workflow、Memory 和其他元件產生唯一識別碼。接收 idType、source、entityId 和 threadId 等選用情境，以支援情境感知的 ID 格式。

**workflows** (`Record<string, Workflow>`): 要註冊的 Workflow。採用鍵值對結構，鍵為 Workflow 名稱，值為 Workflow 執行個體。 (Default: `{}`)

**tts** (`Record<string, MastraVoice>`): 用於語音合成的 text-to-speech Provider

**observability** (`ObservabilityEntrypoint`): 用於 tracing 和監控的可觀測性設定

**environment** (`string`): 部署環境名稱（例如 production、staging、development）。設定後，會自動附加到所有可觀測性 signal，以便依環境篩選，而不必在每次呼叫時傳遞 tracingOptions.metadata.environment。未設定時改用 process.env.NODE\_ENV；兩者均未設定時保持 undefined。每次呼叫傳入的 tracingOptions.metadata.environment 始終優先。

**deployer** (`MastraDeployer`): 用於管理部署的 MastraDeployer 執行個體。

**server** (`ServerConfig`): Server 設定，包括 port、host、timeout、API route、middleware、CORS 設定，以及 Swagger UI、API 請求記錄和 OpenAPI 文件的建置選項。

**mcpServers** (`Record<string, MCPServerBase>`): 一個物件，其中鍵為註冊鍵（供 getMCPServer() 使用），值為 MCPServer 執行個體或擴展 MCPServerBase 的類。每個 MCPServer 都必須具有 id 屬性。可使用 getMCPServer() 依註冊鍵取得 server，或使用 getMCPServerById() 依本身的 id 取得。

**bundler** (`BundlerConfig`): asset 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>`): 要註冊的 Memory 執行個體。已儲存的 Agent 可以參照這些執行個體，並在執行階段解析。採用鍵值對結構，鍵為註冊鍵，值為 Memory 執行個體。 (Default: `{}`)

**notifications** (`object`): 通知 signal 分發的執行階段設定。

**notifications.dispatch** (`NotificationDispatchConfig`): 延遲通知和通知摘要的定時分發設定。預設啟用分發。

**notifications.dispatch.enabled** (`boolean`): 設為 false 可停用自動定時通知分發。

**notifications.dispatch.cron** (`string`): 內部通知 dispatcher Workflow 使用的 cron 計劃。

**notifications.dispatch.batchSize** (`number`): 每次分發 run 最多處理的到期通知記錄數。

**versions** (`VersionOverrides`): sub-agent 委派的全域版本覆寫。當 supervisor Agent 委派給 sub-agent 時，這些覆寫決定使用該 sub-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`): 設定在此 Mastra 執行個體中執行哪些 Worker。省略時，Mastra 會根據 PubSub 和設定自動建立預設 Worker。傳入 false 可停用所有事件處理（適用於單獨執行獨立 Worker 的情況）。傳入 MastraWorker\[] 可新增自訂 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 觸發器的 scheduler Worker。當任一 Workflow 宣告 schedule 時自動啟用。請參閱定時 Workflow。

**scheduler.enabled** (`boolean`): 顯式啟用或停用 scheduler。

**recovery** (`MastraRecoveryConfig`): 孤立 Agent 和 Workflow run 的啟動時復原行為。請參閱當機復原。 (Default: `{ durableAgents: 'off' }`)

**recovery.durableAgents** (`'auto' | 'off'`): 設為 'auto' 後，會在 server 啟動時自動重新驅動孤立的 RUNNING durable Agent run。復原會重新發出 LLM 呼叫並重新執行 Tool 呼叫，因此 Tool 必須具有冪等性。請參閱當機復原。

## 方法

### `recoverAllDurableAgents()`

重新驅動所有已註冊 durable Agent 中的每個孤立 `running` durable-Agent run。當 `recovery.durableAgents` 為 `'auto'` 時，會在啟動時自動呼叫。也可以直接呼叫以手動復原，或從排程任務中呼叫。

需要持久儲存 Storage。使用記憶體 store 時，處理程序重新啟動後沒有可復原的內容。

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

傳回值：

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

**recovered** (`number`): 重新驅動的 run 總數。

**succeeded** (`number`): 成功重新啟動的 run 數量。

**failed** (`number`): 重新啟動時擲回錯誤的 run 數量。