> Discover all available pages from the documentation index: https://mastra.zisheng.pro/llms.txt # Agent 类 Agent 类已更新，重新组织了 Voice 方法，更新了属性访问模式，并简化了流式 API。 ## 已变更 ### `getAgents` 改为 `listAgents` `mastra.getAgents()` 方法已重命名为 `mastra.listAgents()`。此变更与整个 API 的命名约定保持一致：返回集合的 getter 方法使用 `list` 前缀。 迁移时，请将所有 `mastra.getAgents()` 调用替换为 `mastra.listAgents()`。 ```diff - const agents = mastra.getAgents(); + const agents = mastra.listAgents(); ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自动更新代码： > > **npm**: > > ```bash > npx @mastra/codemod@latest v1/mastra-plural-apis . > ``` > > **pnpm**: > > ```bash > pnpm dlx @mastra/codemod@latest v1/mastra-plural-apis . > ``` > > **Yarn**: > > ```bash > yarn dlx @mastra/codemod@latest v1/mastra-plural-apis . > ``` > > **Bun**: > > ```bash > bun x @mastra/codemod@latest v1/mastra-plural-apis . > ``` ### `RuntimeContext` 改为 `RequestContext` 整个代码库中的 `RuntimeContext` 类已重命名为 `RequestContext`。新名称表明该类包含请求特有的数据，并与 Web 框架的约定相符。 迁移时，请将所有导入和参数名从 `RuntimeContext`/`runtimeContext` 更新为 `RequestContext`/`requestContext`。 ```diff - 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 自动更新代码： > > ```bash > npx @mastra/codemod@latest v1/runtime-context . > ``` ### 直接属性访问改为 getter 方法 直接访问 `agent.llm`、`agent.tools` 和 `agent.instructions` 属性的方式已弃用。此变更提供了更好的封装，并与整体 API 设计保持一致。 迁移时，请将属性访问替换为相应的 getter 方法。 ```diff - 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 自动更新代码： > > ```bash > npx @mastra/codemod@latest v1/agent-property-access . > ``` ### Voice 方法迁移到 `agent.voice` 命名空间 Voice 相关方法已从 Agent 类迁移到 `agent.voice` 命名空间，从而将 Voice API 组织在一起。 迁移时，请更新 Voice 方法调用，使其使用 `agent.voice` 命名空间。 ```diff - 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 自动更新代码： > > ```bash > npx @mastra/codemod@latest v1/agent-voice . > ``` ### `agent.fetchMemory()` to `(await agent.getMemory()).recall()` `fetchMemory()` 方法已替换为一个明确表示异步 Memory 访问的 API。 迁移时，请将 `fetchMemory()` 调用替换为新 API。 ```diff - 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 方法名。 ```diff - 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 自动更新代码： > > ```bash > 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 导入即可： ```ts 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 版本更新方法名。 ```diff // 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` 移至顶层。 ```diff agent.stream('Hello', { - modelSettings: { - abortSignal: abortController.signal, - }, + abortSignal: abortController.signal, }); ``` > **Codemod:** 你可以使用 Mastra 的 codemod CLI 自动更新代码： > > ```bash > npx @mastra/codemod@latest v1/agent-abort-signal . > ``` ### `output` 改为 `structuredOutput.schema` 已弃用的 `output` 和 `experimental_output` 选项已移除。此变更将结构化输出统一到一个稳定的 API。 迁移时，请将 `output` 或 `experimental_output` 更新为 `structuredOutput.schema`。 ```diff agent.stream('Hello', { - output: z.object({ result: z.string() }), + structuredOutput: { + schema: z.object({ result: z.string() }), + }, }); ``` ### Agent 现在必须提供 `id` 字段 创建 Agent 时现在必须提供 `id` 字段。此前可以在不显式提供 ID 的情况下创建 Agent，但现在不再支持。 迁移时，请为所有 Agent 配置添加 `id` 字段。 ```diff 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 实例中必须唯一。 ```typescript // 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()` 方法。 ```diff - 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 自动更新代码： > > ```bash > 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 格式。 ```diff - 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 会自动处理转换。 ```diff - 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。 ```diff - const agent = new Agent({ + const agent = new Agent({ // ... }); ``` ### Tripwire 响应格式变更 Tripwire 响应格式已从独立的 `tripwire` 和 `tripwireReason` 字段改为包含所有相关数据的单个 `tripwire` 对象。 迁移时，请更新代码，从新的对象结构访问 tripwire 数据。 ```diff 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 + } ``` 对于流式响应： ```diff 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 信息： ```diff 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()`： ```diff 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` 选项： ```diff await agent.stream('Hello', { - threadId: 'thread-123', - resourceId: 'user-456', + memory: { + thread: 'thread-123', + resource: 'user-456', + }, }); ``` 创建新线程时，`memory` 选项还支持传入线程元数据： ```typescript await agent.stream('Hello', { memory: { thread: { id: 'thread-123', title: 'Support conversation', metadata: { category: 'billing' }, }, resource: 'user-456', }, }) ```