Agent 類別

Agent 類別已更新，包括重新組織 Voice 方法、更新屬性存取模式，以及精簡串流 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 .

Voice 方法移至 agent.voice 命名空間

Voice 相關方法已從 Agent 類別移至 agent.voice 命名空間，將 Voice API 集中於一處。

遷移時，請更新 Voice 方法呼叫，改用 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() 方法已由明確呈現非同步 Memory 存取方式的 API 取代。

遷移時，請使用新 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*

Agent 處理器方法已從 get* 重新命名為 list* 模式，以與更廣泛的 API 保持一致。這項變更符合 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() 等方法與相關選項型別。

如果已將 Zod 結構描述傳給 Agent API，不需為 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 移至 stream 與 generate 選項的頂層。執行控制現在位於模型專屬設定之外。

遷移時，請將 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 Server 現在會自動遮蔽 Agent 串流回應中的敏感資訊，避免在 step-start、step-finish 與 finish 串流區塊中意外洩漏系統提示詞、Tool 定義與 API 金鑰。

遮蔽的內容：

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

這項行為預設為啟用。如果需要存取完整請求資料（例如進行偵錯或用於內部服務），直接使用 Server 轉接器（例如 @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 處理器方法統一，後者會在 Agentic 迴圈的每個步驟執行。

如果需要舊的 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',
  },
})