Mastra 類別

Mastra 類別已重組，以限制頂層匯入，並以 getter 方法取代直接存取屬性。

已變更

從頂層匯入改為從子路徑匯入

主要的 @mastra/core 索引文件現在只匯出 Mastra 和 Config。所有其他匯出項目已移至子路徑匯入。這項變更讓打包器可移除未使用的程式碼，改善 tree-shaking 並縮減套件大小。

如要遷移，請更新所有從 @mastra/core 進行的匯入，改用適當的子路徑。

- import { Mastra, Agent, Workflow, createTool } from '@mastra/core';
+ import { Mastra, type Config } from '@mastra/core';
+ import { Agent } from '@mastra/core/agent';
+ import { Workflow } from '@mastra/core/workflows';
+ import { createTool } from '@mastra/core/tools';

Codemod

你可以使用 Mastra 的 codemod CLI 自動更新程式碼：

npx @mastra/codemod@latest v1/mastra-core-imports .

experimental_auth 改為 auth

實驗性驗證設定現已成為穩定功能。這項變更表示驗證 API 已經穩定，並可用於生產環境。

如要遷移，請在 Mastra 設定中將 experimental_auth 鍵重新命名為 auth。

  const mastra = new Mastra({
-   experimental_auth: {
+   auth: {
      provider: workos,
    },
  });

Codemod

你可以使用 Mastra 的 codemod CLI 自動更新程式碼：

npx @mastra/codemod@latest v1/experimental-auth .

所有 Mastra 基本元件都必須提供 id 參數

所有儲存空間、向量儲存區、Agent、Workflow、mcpServers、處理器、scorer 和 Tool 現在都必須在初始化時提供 id 參數。這可支援標準化的 Mastra API，並避免 ID 衝突。

所有這些基本元件現在亦提供 get、list 和 add 函式。

如要遷移，請為所有儲存空間及向量儲存區實例加入 id 參數。同一儲存空間／向量類別使用多次時，請確保每個實例都有獨有 ID。

- const storage = new LibSQLStore({
-   url: ':memory:',
- });
+ const storage = new LibSQLStore({
+   id: 'my-app-storage',
+   url: ':memory:',
+ });

- const vector = new PgVector({
-   connectionString: process.env.DATABASE_URL,
- });
+ const vector = new PgVector({
+   id: 'my-app-vector',
+   connectionString: process.env.DATABASE_URL,
+ });

為不同用途使用個別實例時，請使用描述清晰且獨有的 ID：

  const agentMemory = new Memory({
    storage: new LibSQLStore({
-     url: 'file:./agent.db',
+     id: 'weather-agent-memory-storage',
+     url: 'file:./agent.db',
    }),
  });

  const mastra = new Mastra({
    storage: new LibSQLStore({
+     id: 'mastra-storage',
      url: ':memory:',
    }),
  });

基本元件的複數 API 從 get<primitives> 改為 list<primitive>

傳回某個基本元件所有實例的 get* 函式已重新命名為 list*，以更準確反映其用途。

- const agents = mastra.getAgents();
+ const agents = mastra.listAgents();
- const vectors = mastra.getVectors();
+ const vectors = mastra.listVectors();
- const workflows = mastra.getWorkflows();
+ const workflows = mastra.listWorkflows();
- const scorers = mastra.getScorers();
+ const scorers = mastra.listScorers();
- const mcpServers = mastra.getMCPServers();
+ const mcpServers = mastra.listMCPServers();
- const logsByRunId = await mastra.getLogsByRunId({ runId: 'id', transportId: 'id' });
+ const logsByRunId = await mastra.listLogsByRunId({ runId: 'id', transportId: 'id' });
- const logs = await mastra.getLogs('transportId');
+ const logs = await mastra.listLogs('transportId');

Codemod

你可以使用 Mastra 的 codemod CLI 自動更新程式碼：

npx @mastra/codemod@latest v1/mastra-plural-apis .

每個基本元件都有 getById 和 get 函式

mastra.getMCPServer('myServer') // Works (registry key)
mastra.getMCPServerById('my-mcp-server') // Works (intrinsic ID)

Tool 註冊現改用內在 ID

當 Tool 從 Agent 或 MCP 伺服器自動註冊至 Mastra 實例時，現在會使用 Tool 的內在 id，而非設定物件的鍵。當多個 Agent／MCP 伺服器具有相同設定鍵的 Tool 時，這可避免衝突。

如要遷移，請更新所有透過設定鍵參照 Tool 的程式碼，改用 Tool 的內在 ID。

  const agent = new Agent({
    id: 'agent1',
    tools: {
      searchTool: weatherSearchTool,
    },
  });

- mastra.getTool('searchTool');
+ mastra.getTool(weatherSearchTool.id);