Agent 類別

Agent 類別已更新，包括重新整理語音方法、更新屬性存取模式，以及簡化串流 API。

已變更

getAgents 改為 listAgents

mastra.getAgents() 方法已重新命名為 mastra.listAgents()。這項變更配合整個 API 的命名慣例：傳回多個項目的 getter 方法使用 list 前綴。

如要遷移，請將所有 mastra.getAgents() 呼叫取代為 mastra.listAgents()。

- const agents = mastra.getAgents();
+ const agents = mastra.listAgents();

Codemod

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

npm

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

pnpm

pnpm dlx @mastra/codemod@latest v1/mastra-plural-apis .

Yarn

yarn dlx @mastra/codemod@latest v1/mastra-plural-apis .

Bun

bun x @mastra/codemod@latest v1/mastra-plural-apis .

RuntimeContext 改為 RequestContext

整個程式碼庫中的 RuntimeContext 類別已重新命名為 RequestContext。新名稱清楚表明此類別包含個別請求的資料，亦符合網頁框架的慣例。

如要遷移，請將所有匯入及參數名稱從 RuntimeContext／runtimeContext 更新為 RequestContext／requestContext。

- import { RuntimeContext } from '@mastra/core/runtime-context';
+ import { RequestContext } from '@mastra/core/request-context';

- const runtimeContext = new RuntimeContext();
- runtimeContext.set('userTier', 'enterprise');
+ const requestContext = new RequestContext();
+ requestContext.set('userTier', 'enterprise');

- await agent.generate(messages, { runtimeContext });
+ await agent.generate(messages, { requestContext });

Codemod

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

npx @mastra/codemod@latest v1/runtime-context .

從直接存取屬性改為使用 getter 方法

直接存取 agent.llm、agent.tools 和 agent.instructions 屬性的方式已棄用。這項變更提供更佳封裝，亦與整體 API 設計保持一致。

如要遷移，請以相應的 getter 方法取代屬性存取。

- const llm = agent.llm;
- const tools = agent.tools;
- const instructions = agent.instructions;
+ const llm = agent.getLLM();
+ const tools = agent.getTools();
+ const instructions = agent.getInstructions();

Codemod

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

npx @mastra/codemod@latest v1/agent-property-access .

語音方法移至 agent.voice 命名空間

語音相關方法已從 Agent 類別移至 agent.voice 命名空間，將語音 API 集中整理。

如要遷移，請更新語音方法呼叫，改用 agent.voice 命名空間。

- await agent.speak('Hello');
- await agent.listen();
- const speakers = agent.getSpeakers();
+ await agent.voice.speak('Hello');
+ await agent.voice.listen();
+ const speakers = agent.voice.getSpeakers();

Codemod

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

npx @mastra/codemod@latest v1/agent-voice .

agent.fetchMemory() 改為 (await agent.getMemory()).recall()

fetchMemory() 方法已由新的 API 取代，以明確表示 Memory 存取是非同步操作。

如要遷移，請以新 API 取代 fetchMemory() 呼叫。

- const messages = await agent.fetchMemory({ threadId: 'thread-123' });
+ const memory = await agent.getMemory();
+ const result = await memory.recall({ threadId: 'thread-123' });
+ const messages = result.messages;

處理器方法名稱從 get* 改為 list*

為與整體 API 保持一致，Agent 處理器方法已從 get* 模式重新命名為 list* 模式。這項變更配合以 list* 方法傳回集合的慣例。

如要遷移，請更新處理器方法名稱。

- const inputProcessors = await agent.getInputProcessors(runtimeContext);
- const outputProcessors = await agent.getOutputProcessors(runtimeContext);
+ const inputProcessors = await agent.listInputProcessors(requestContext);
+ const outputProcessors = await agent.listOutputProcessors(requestContext);

Codemod

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

npx @mastra/codemod@latest v1/agent-processor-methods .

繼續支援 Zod v3 和 v4 結構化輸出結構描述

Mastra v1 的公開 Agent API 如接受結構化輸出結構描述，便會繼續同時接受 Zod v3 及 Zod v4 結構描述，包括 agent.generateLegacy()、agent.streamLegacy() 等方法及相關選項類型。

如果你已向 Agent API 傳入 Zod 結構描述，則無需為 Zod 版本相容性進行遷移。保留現有的結構描述匯入即可：

import { z as z3 } from 'zod/v3'
import { z as z4 } from 'zod/v4'

await agent.generateLegacy({
  prompt: 'Summarize this ticket',
  output: z3.object({ summary: z3.string() }),
})

await agent.streamLegacy({
  prompt: 'Extract contact info',
  output: z4.object({ email: z4.string().email() }),
})

只有當你想在應用程式中統一使用同一個 Zod 版本時，才需要更新匯入。

不同 AI SDK 版本的預設選項方法重新命名

預設選項方法已重新命名，以區分舊版（AI SDK v4）API 與 AI SDK v5+ API。方法名稱現在會指出其目標 AI SDK 版本。

如要遷移，請按你使用的 AI SDK 版本更新方法名稱。

  // For legacy AI SDK v4
- const options = await agent.getDefaultGenerateOptions();
- const streamOptions = await agent.getDefaultStreamOptions();
+ const options = await agent.getDefaultGenerateOptionsLegacy();
+ const streamOptions = await agent.getDefaultStreamOptionsLegacy();

  // For new AI SDK v5+ (default)
  const streamOptions = await agent.getDefaultStreamOptions();

modelSettings.abortSignal 改為頂層 abortSignal

abortSignal 選項已從 modelSettings 移至串流及產生選項的頂層。執行控制現在位於模型特定設定之外。

如要遷移，請將 abortSignal 從 modelSettings 移至頂層。

  agent.stream('Hello', {
-   modelSettings: {
-     abortSignal: abortController.signal,
-   },
+   abortSignal: abortController.signal,
  });

Codemod

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

npx @mastra/codemod@latest v1/agent-abort-signal .

output 改為 structuredOutput.schema

已棄用的 output 和 experimental_output 選項已移除。這項變更將結構化輸出統一為單一穩定 API。

如要遷移，請將 output 或 experimental_output 更新為 structuredOutput.schema。

  agent.stream('Hello', {
-   output: z.object({ result: z.string() }),
+   structuredOutput: {
+     schema: z.object({ result: z.string() }),
+   },
  });

Agent id 欄位現為必填

建立 Agent 時，現在必須提供 id 欄位。以往可以建立沒有明確 ID 的 Agent，但現在已不再支援。

如要遷移，請為所有 Agent 設定加入 id 欄位。

  const agent = new Agent({
+   id: 'my-agent',
    name: 'My Agent',
    instructions: 'You are a helpful assistant',
    model: 'openai/gpt-5.6-sol',
  });

id 可以與 name 相同，亦可使用不同識別碼。呼叫 mastra.getAgentById() 時會使用此 ID，而且在你的 Mastra 實例內必須獨有。

// Register agent with Mastra
const mastra = new Mastra({
  agents: {
    myAgent: agent, // key can differ from id
  },
})

// Retrieve by ID
const agent = mastra.getAgentById('my-agent')

串流 API 回應現在會隱藏敏感資料

Mastra 伺服器現在會自動隱藏 Agent 串流回應中的敏感資料，避免在 step-start、step-finish 和 finish 串流區塊中意外洩露系統提示、Tool 定義及 API 金鑰。

會隱藏的內容：

• 包含 LLM 請求承載資料（系統提示、Tool 結構描述）的 request.body
• 步驟結果中的 metadata.request
• 巢狀步驟資料中的 output.steps[].request

此行為預設啟用。如果你需要存取完整請求資料（例如用於除錯或內部服務），直接使用伺服器配接器（例如 @mastra/hono 或 @mastra/express）時可以停用隱藏功能。

已移除

generateVNext 和 streamVNext 方法

已棄用的 generateVNext() 和 streamVNext() 方法已移除。這些方法過往用於支援 AI SDK v5+，但其實作現在已成為標準。

如要遷移，請使用標準 generate() 和 stream() 方法。

- const result = await agent.generateVNext('Hello');
- const stream = await agent.streamVNext('Hello');
+ const result = await agent.generate('Hello');
+ const stream = await agent.stream('Hello');

Codemod

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

npx @mastra/codemod@latest v1/agent-generate-stream-v-next .

從 stream() 和 generate() 移除 format 參數

agent.stream() 和 agent.generate() 方法已移除 format 參數。AI SDK 串流轉換現由 @mastra/ai-sdk 套件處理。這項變更將 AI SDK 特定程式碼移至專用套件，改善 tree-shaking。

如要遷移，請使用 @mastra/ai-sdk 的 toAISdkStream() 函式進行 AI SDK 格式轉換。

- const stream = await agent.stream(messages, {
-   format: 'aisdk',
- });

+ import { toAISdkStream } from '@mastra/ai-sdk';
+ 
+ const stream = await agent.stream(messages);
+ const aiSdkStream = toAISdkStream(stream, { from: 'agent' });

agent.toStep() 方法

Agent 類別已移除 toStep() 方法。現在可直接將 Agent 加入 Workflow 步驟，無需明確轉換。

如要遷移，請將 Agent 直接加入 Workflow 步驟。Workflow 會自動處理轉換。

- const step = agent.toStep();
- const workflow = new Workflow({
-   steps: [step],
- });

+ const workflow = new Workflow({
+   steps: [agent],
+ });

Agent 的 TMetrics 泛型參數

AgentConfig 和 Agent 建構函式已移除 TMetrics 泛型參數。指標／scorer 現在使用 scorer API 設定，不再是 Agent 類型系統的一部分。

如要遷移，請移除 TMetrics 泛型參數，並使用新 API 設定 scorer。

- const agent = new Agent<AgentId, Tools, Metrics>({
+ const agent = new Agent<AgentId, Tools>({
    // ...
  });

Tripwire 回應格式變更

tripwire 回應格式已由獨立的 tripwire 及 tripwireReason 欄位，改為單一 tripwire 物件，當中包含所有相關資料。

如要遷移，請更新程式碼，從新的物件結構存取 tripwire 資料。

  const result = await agent.generate('Hello');

- if (result.tripwire) {
-   console.log(result.tripwireReason);
- }
+ if (result.tripwire) {
+   console.log(result.tripwire.reason);
+   // New fields available:
+   // result.tripwire.retry - whether this step should be retried
+   // result.tripwire.metadata - additional metadata from the processor
+   // result.tripwire.processorId - which processor triggered the tripwire
+ }

串流回應的遷移方式：

  for await (const chunk of stream.fullStream) {
    if (chunk.type === 'tripwire') {
-     console.log(chunk.payload.tripwireReason);
+     console.log(chunk.payload.reason);
+     // New fields available:
+     // chunk.payload.retry
+     // chunk.payload.metadata
+     // chunk.payload.processorId
    }
  }

步驟結果現在亦包含 tripwire 資料：

  const result = await agent.generate('Hello');

  for (const step of result.steps) {
-   // No tripwire info on steps
+   if (step.tripwire) {
+     console.log('Step was blocked:', step.tripwire.reason);
+   }
  }

prepareStep 訊息格式

prepareStep 回呼現在收到 MastraDBMessage 格式的訊息，而非 AI SDK v5+ 模型訊息格式。這項變更令 prepareStep 與新的 processInputStep 處理器方法統一；後者會在 Agent 循環的每個步驟執行。

如果你需要舊有 AI SDK v5+ 格式，請使用 messageList.get.all.aiV5.model()：

  agent.generate('Hello', {
    prepareStep: async ({ messages, messageList }) => {
-     // messages was AI SDK v5+ ModelMessage format
-     console.log(messages[0].content);
+     // messages is now MastraDBMessage format
+     // Use messageList to get AI SDK v5+ format if needed:
+     const aiSdkMessages = messageList.get.all.aiV5.model();

      return { toolChoice: 'auto' };
    },
  });

threadId 和 resourceId 改用 memory 選項

agent.stream() 和 agent.generate() 已移除 threadId 及 resourceId 選項。請改用 memory 選項，讓 Memory 設定 API 更簡潔。

如要遷移，請將 threadId 和 resourceId 移至 memory 選項：

  await agent.stream('Hello', {
-   threadId: 'thread-123',
-   resourceId: 'user-456',
+   memory: {
+     thread: 'thread-123',
+     resource: 'user-456',
+   },
  });

建立新對話串時，memory 選項亦支援傳入對話串中繼資料：

await agent.stream('Hello', {
  memory: {
    thread: {
      id: 'thread-123',
      title: 'Support conversation',
      metadata: { category: 'billing' },
    },
    resource: 'user-456',
  },
})