跳到主要内容

Agent.generateLegacy()（旧版）

注意

已弃用：此方法已弃用，并且仅适用于旧版 model adapter。对于当前的 model adapter，请改用 .generate()。

.generateLegacy() 方法是 Agent 生成 API 的旧版，用于配合旧版 model adapter 生成文本或结构化响应。此方法接受消息和可选的生成选项。

使用示例
使用示例的直接链接

await agent.generateLegacy('message for agent')

Processor 重试支持
Processor 重试支持的直接链接

generateLegacy() 不运行错误 Processor，也不使用 maxProcessorRetries。它改用旧版 AI SDK 生成路径。

使用旧版 model adapter 的 Scorer judge 会调用 generateLegacy()。它们无法获得使用 Mastra 当前生成 API 的 Scorer judge 所具备的协调式 StreamErrorRetryProcessor 重试预算。需要错误 Processor 重试时，请使用当前的 model adapter。旧版 maxRetries 选项仍保持独立，默认值为 2。

参数
参数的直接链接

messages:

string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]
要发送给 Agent 的消息。可以是单个字符串、字符串数组，或包含多模态内容（文本、图像等）的结构化消息对象。

options?:

AgentGenerateOptions
生成过程的可选配置。
AgentGenerateOptions

abortSignal?:

AbortSignal
用于中止 Agent 执行的 signal 对象。中止 signal 后，所有正在进行的操作都会终止。

context?:

CoreMessage[]
提供给 Agent 的其他上下文消息。

structuredOutput?:

StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>
启用结构化输出生成并提供更好的开发者体验。内部会自动创建并使用 StructuredOutputProcessor。
StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>

schema:

z.ZodSchema<S>
用于验证输出的 Zod schema。

model:

MastraLanguageModel
内部结构化 Agent 使用的 Model。

errorStrategy?:

'strict' | 'warn' | 'fallback'
解析或验证失败时采用的策略。默认为 'strict'。

fallbackValue?:

<S extends ZodTypeAny>
当 errorStrategy 为 'fallback' 时使用的回退值。

instructions?:

string
结构化 Agent 的自定义 instructions。

outputProcessors?:

Processor[]
覆盖 Agent 上设置的输出 Processor。输出 Processor 可在 Agent 消息返回给用户之前修改或验证消息。必须实现 processOutputResult 和 processOutputStream 函数中的至少一个。

inputProcessors?:

Processor[]
覆盖 Agent 上设置的输入 Processor。输入 Processor 可在 Agent 处理消息之前修改或验证消息。必须实现 processInput 函数。

experimental_output?:

Zod schema | JsonSchema7
请注意，推荐使用 structuredOutput 属性。该选项可在文本生成和 Tool 调用的同时启用结构化输出生成。Model 将生成符合所提供 schema 的响应。

instructions?:

string
为此次生成覆盖 Agent 默认 instructions 的自定义 instructions。无需创建新的 Agent 实例即可动态修改 Agent 行为。

output?:

Zod schema | JsonSchema7
定义预期的输出结构。可以是 JSON Schema 对象或 Zod schema。

memory?:

object
Memory 配置。这是管理 Memory 的推荐方式。
object

thread:

string | { id: string; metadata?: Record<string, any>, title?: string }
对话 thread，可以是字符串 ID，也可以是包含 id 和可选 metadata 的对象。

resource:

string
与 thread 关联的用户或 resource 标识符。

options?:

MemoryConfig
Memory 行为配置，例如消息历史记录和语义召回。请参阅下方的 MemoryConfig。

maxSteps?:

number
允许的最大执行步骤数。

maxRetries?:

number
最大重试次数。设为 0 可禁用重试。

onStepFinish?:

GenerateTextOnStepFinishCallback<any> | never
每个执行步骤完成后调用的回调函数。以 JSON 字符串接收步骤详情。不适用于结构化输出。

runId?:

string
此次生成运行的唯一 ID，可用于跟踪和调试。

telemetry?:

TelemetrySettings
生成期间的 telemetry 收集设置。
TelemetrySettings

isEnabled?:

boolean
启用或禁用 telemetry。实验阶段默认禁用。

recordInputs?:

boolean
启用或禁用输入记录。默认启用。为避免记录敏感信息，你可能需要禁用输入记录。

recordOutputs?:

boolean
启用或禁用输出记录。默认启用。为避免记录敏感信息，你可能需要禁用输出记录。

functionId?:

string
此函数的标识符。用于按函数对 telemetry 数据分组。

temperature?:

number
控制 Model 输出的随机性。较高的值（例如 0.8）会使输出更随机，较低的值（例如 0.2）会使输出更集中、更具确定性。

toolChoice?:

'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }
控制 Agent 在生成期间如何使用 Tool。
'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }

'auto':

string
让 Model 决定是否使用 Tool（默认）。

'none':

string
不使用任何 Tool。

'required':

string
要求 Model 至少使用一个 Tool。

{ type: 'tool'; toolName: string }:

object
要求 Model 使用指定名称的 Tool。

toolsets?:

ToolsetsInput
生成期间向 Agent 提供的其他 Toolset。

clientTools?:

ToolsInput
在请求的 'client' 端执行的 Tool。这些 Tool 的定义中没有 execute 函数。

hooks?:

ToolHooks
每次执行时在 Tool 调用前后运行的 hook。覆盖此次执行中匹配的 Agent 级 hook。beforeToolCall 可返回 { proceed: false, output } 以跳过 Tool 调用。

savePerStep?:

boolean
每个生成步骤完成后增量保存消息（默认：false）。启用 observational memory 时会在内部禁用。

providerOptions?:

Record<string, Record<string, JSONValue>>
传递给底层 LLM Provider 的其他 Provider 专属选项。结构为 { providerName: { optionKey: value } }。由于 Mastra 扩展了 AI SDK，有关完整的 Provider 选项，请参阅 AI SDK 文档。
Record<string, Record<string, JSONValue>>

openai?:

Record<string, JSONValue>
OpenAI 专属选项。示例：{ reasoningEffort: 'high' }

anthropic?:

Record<string, JSONValue>
Anthropic 专属选项。示例：{ maxTokens: 1000 }

google?:

Record<string, JSONValue>
Google 专属选项。示例：{ safetySettings: [...] }

[providerName]?:

Record<string, JSONValue>
其他 Provider 专属选项。键为 Provider 名称，值为 Provider 专属选项的记录。

requestContext?:

RequestContext
用于依赖注入和上下文信息的 RequestContext。

maxTokens?:

number
要生成的最大 token 数。

topP?:

number
核采样。取值范围为 0 到 1。建议只设置 temperature 或 topP，不要同时设置。

topK?:

number
生成后续每个 token 时，只从概率最高的 K 个选项中采样。用于移除低概率的“长尾”响应。

presencePenalty?:

number
存在惩罚设置。它会影响 Model 重复 prompt 中已有信息的可能性。取值范围为 -1（增加重复）到 1（最大惩罚，减少重复）。

frequencyPenalty?:

number
频率惩罚设置。它会影响 Model 重复使用相同单词或短语的可能性。取值范围为 -1（增加重复）到 1（最大惩罚，减少重复）。

stopSequences?:

string[]
停止序列。设置后，当生成任一停止序列时，Model 将停止生成文本。

seed?:

number
随机采样使用的 seed（整数）。如果设置且 Model 支持，调用将生成确定性结果。

headers?:

Record<string, string | undefined>
随请求发送的其他 HTTP header。仅适用于基于 HTTP 的 Provider。

返回值
返回值的直接链接

text?:

string
生成的文本响应。当输出为 'text'（未提供 schema）时存在。

object?:

object
生成的结构化响应。通过 output、structuredOutput 或 experimental_output 提供 schema 时存在。

toolCalls?:

Array<ToolCall>
生成过程中进行的 Tool 调用。在文本和对象模式下均存在。
Array<ToolCall>

toolName:

string
被调用 Tool 的名称。

args:

any
传递给 Tool 的参数。

迁移到新 API
迁移到新 API的直接链接

信息

新的 .generate() 方法提供了更强的能力，包括兼容 AI SDK v5+、更完善的结构化输出处理以及改进的 streaming 支持。有关详细迁移说明，请参阅迁移指南。

快速迁移示例
快速迁移示例的直接链接

迁移前（旧版）
迁移前（旧版）的直接链接

const result = await agent.generateLegacy('message', {
  temperature: 0.7,
  maxSteps: 3,
})

迁移后（新 API）
迁移后（新 API）的直接链接

const result = await agent.generate('message', {
  modelSettings: {
    temperature: 0.7,
  },
  maxSteps: 3,
})

扩展使用示例
扩展使用示例的直接链接

import { z } from 'zod'
import { ModerationProcessor, TokenLimiterProcessor } from '@mastra/core/processors'

await agent.generateLegacy(
  [
    { role: 'user', content: 'message for agent' },
    {
      role: 'user',
      content: [
        {
          type: 'text',
          text: 'message for agent',
        },
        {
          type: 'image',
          imageUrl: 'https://example.com/image.jpg',
          mimeType: 'image/jpeg',
        },
      ],
    },
  ],
  {
    temperature: 0.7,
    maxSteps: 3,
    memory: {
      thread: 'user-123',
      resource: 'test-app',
    },
    toolChoice: 'auto',
    providerOptions: {
      openai: {
        reasoningEffort: 'high',
      },
    },
    // Structured output with better DX
    structuredOutput: {
      schema: z.object({
        sentiment: z.enum(['positive', 'negative', 'neutral']),
        confidence: z.number(),
      }),
      model: 'openai/gpt-5.6-sol',
      errorStrategy: 'warn',
    },
    // Output processors for response validation
    outputProcessors: [
      new ModerationProcessor({ model: 'openai/gpt-5-mini' }),
      new TokenLimiterProcessor({ maxTokens: 1000 }),
    ],
  },
)
On this page