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。新名称表明该类包含请求特有的数据，并与 Web 框架的约定相符。

迁移时，请将所有导入和参数名从 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() to (await agent.getMemory()).recall()

fetchMemory() 方法已替换为一个明确表示异步 Memory 访问的 API。

迁移时，请将 fetchMemory() 调用替换为新 API。

- 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;

Processor 方法名从 get* 改为 list*

Agent 的 Processor 方法已从 get* 模式重命名为 list* 模式，以与整体 API 保持一致。此变更遵循 list* 方法返回集合的约定。

迁移时，请更新 Processor 方法名。

- 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 结构化输出 Schema

Mastra v1 的公共 Agent API 在接收结构化输出 Schema 时，继续同时支持 Zod v3 和 Zod v4 Schema。这包括 agent.generateLegacy()、agent.streamLegacy() 等方法及相关选项类型。

如果已经向 Agent API 传入 Zod Schema，则无需为 Zod 版本兼容性进行迁移。保留现有的 Schema 导入即可：

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')

Stream API 响应现在会遮盖敏感数据

Mastra Server 现在会自动遮盖 Agent 流式响应中的敏感信息，防止系统提示词、Tool 定义和 API Key 意外暴露在 step-start、step-finish 和 finish 流式数据块中。

遮盖的内容：

• 包含 LLM 请求负载（系统提示词、Tool Schema）的 request.body
• 步骤结果中的 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 泛型参数已移除。Metric/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 与在 Agent 循环每一步运行的新 processInputStep Processor 方法保持一致。

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