Agent.generate()

.generate() 方法支持 Agent 以增强功能进行非流式响应生成。它接受消息和可选的生成选项。

用法示例
用法示例的直接链接

向 Agent 传入消息以生成响应：

const result = await agent.generate('message for agent')

参数
参数的直接链接

messages:

string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]

要发送给 Agent 的消息。可以是单个字符串、字符串数组或结构化消息对象。

options?:

AgentExecutionOptions<Output, Format>

生成过程的可选配置。

AgentExecutionOptions<Output, Format>

maxSteps?:

number

执行期间运行的最大步骤数。

stopWhen?:

LoopOptions['stopWhen']

停止执行的条件（例如步骤数、token 限制）。

onIterationComplete?:

(context: IterationCompleteContext) => { continue?: boolean; feedback?: string } | void | Promise<{ continue?: boolean; feedback?: string } | void>

每次迭代完成后调用的回调函数。可用于监控进度、提供反馈以引导 Agent，或提前停止执行。该回调接收迭代的上下文，其中包括当前文本、Tool 调用和完成原因。

IterationCompleteContext

context.iteration:

number

当前迭代编号（从 1 开始）。

context.maxIterations:

number | undefined

允许的最大迭代次数（如果已设置）。

context.text:

string

本次迭代的文本响应。

context.isFinal:

boolean

本次是否为最终迭代。

context.finishReason:

string

本次迭代完成的原因（例如 'stop'、'length'、'tool-calls'）。

context.toolCalls:

ToolCall[]

本次迭代中发出的 Tool 调用。

context.messages:

MastraDBMessage[]

截至目前累积的所有消息。

return.continue?:

boolean

设为 false 可提前停止执行。

return.feedback?:

string

用于引导 Agent 下一次迭代的反馈消息。

isTaskComplete?:

IsTaskCompleteConfig

用于验证任务是否完成的任务完成度评分配置。使用 Mastra 的评估 scorer 自动检查 Agent 的响应是否满足完成条件。

IsTaskCompleteConfig

scorers:

MastraScorer[]

用于评估任务完成情况的 scorer 数组。每个 scorer 返回 0（失败）或 1（通过）。

strategy?:

'all' | 'any'

组合 scorer 结果的策略。'all' 要求所有 scorer 均通过，'any' 要求至少一个通过。

onComplete?:

(result: IsTaskCompleteRunResult) => void | Promise<void>

任务完成检查结束时调用的回调。接收包含各个 scorer 分数的结果。

parallel?:

boolean

是否并行运行 scorer。

timeout?:

number

等待所有 scorer 完成的最长时间（毫秒）。

delegation?:

DelegationConfig

子 Agent 委派的配置。可用于控制和监控 Agent 何时将任务委派给其他 Agent，包括修改或拒绝委派，以及提供反馈来引导 supervisor。

DelegationConfig

onDelegationStart?:

(context: DelegationStartContext) => DelegationStartResult | void | Promise<DelegationStartResult | void>

委派给子 Agent 前调用。可用于修改委派参数、完全拒绝委派，或更改 context.requestContext，向子 Agent 运行的 request context 添加条目。

onDelegationComplete?:

(context: DelegationCompleteContext) => { feedback?: string } | void | Promise<{ feedback?: string } | void>

子 Agent 委派完成后调用。上下文包含用于停止后续执行的 bail() 方法，你还可以返回 { feedback } 来引导 supervisor 的下一步操作。反馈会作为 assistant 消息保存到 supervisor memory。

messageFilter?:

(context: MessageFilterContext) => MastraDBMessage[] | Promise<MastraDBMessage[]>

委派给子 Agent 前调用的回调函数。可用于筛选传递给子 Agent 的消息。

scorers?:

MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>

针对执行结果运行的评估 scorer。

MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>

scorer:

string

要使用的 scorer 名称。

sampling?:

ScoringSamplingConfig

scorer 的采样配置。

ScoringSamplingConfig

type:

'none' | 'ratio'

采样策略的类型。使用 'none' 禁用采样，或使用 'ratio' 按百分比采样。

rate?:

number

采样率（0-1）。type 为 'ratio' 时必填。

returnScorerData?:

boolean

是否在响应中返回详细评分数据。

onChunk?:

(chunk: ChunkType) => Promise<void> | void

生成期间每个 chunk 都会调用的回调函数。

onError?:

({ error }: { error: Error | string }) => Promise<void> | void

生成期间发生错误时调用的回调函数。

onAbort?:

(event: any) => Promise<void> | void

生成中止时调用的回调函数。

activeTools?:

Array<keyof ToolSet> | undefined

执行期间应处于活动状态的 Tool 名称数组。如果为 undefined，则所有可用 Tool 均处于活动状态。

abortSignal?:

AbortSignal

用于中止 Agent 执行的 signal 对象。signal 中止后，所有正在进行的操作都会终止，包括 Agent 委派且仍在运行的所有子 Agent。

prepareStep?:

PrepareStepFunction

多步骤执行中每一步之前调用的回调函数。

requireToolApproval?:

boolean

为 true 时，所有 Tool 调用都必须在执行前获得明确批准。generate() 方法将返回 finishReason: 'suspended'，并包含带有 Tool 调用详细信息（toolCallId、toolName、args）的 suspendPayload。使用 approveToolCallGenerate() 或 declineToolCallGenerate() 继续。有关详细信息，请参阅 Agent 审批。

autoResumeSuspendedTools?:

boolean

为 true 时，当用户在同一 thread 中发送新消息，会自动恢复已暂停的 Tool。Agent 根据 Tool 的 resumeSchema 从用户消息中提取 resumeData。需要配置 memory。

toolCallConcurrency?:

number

可并发执行的 Tool 调用最大数量。可能需要审批时默认为 1，否则为 10。

context?:

ModelMessage[]

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

structuredOutput?:

StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>

用于微调结构化输出生成的选项。

StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>

schema:

StandardJSONSchemaV1

定义预期输出结构的标准 JSON Schema。

model?:

MastraLanguageModel

用于生成结构化输出的语言模型。提供后，Agent 可以通过多个步骤使用 Tool 调用、文本和结构化输出来响应

errorStrategy?:

'strict' | 'warn' | 'fallback'

处理 schema 验证错误的策略。'strict' 抛出错误，'warn' 记录警告，'fallback' 使用回退值。

fallbackValue?:

schema 验证失败且 errorStrategy 为 'fallback' 时使用的回退值。

instructions?:

string

结构化输出模型的其他指令。

jsonPromptInjection?:

boolean | 'system' | 'inline' | 'auto'

控制 JSON schema 如何传递到模型。设为 'auto' 后，在支持时使用原生结构化输出，否则使用内联 prompt 注入。

logger?:

IMastraLogger

输出生成期间用于结构化日志记录的可选 logger 实例。

providerOptions?:

ProviderOptions

传递给内部结构化 Agent 的 Provider 专属选项。可用于控制模型行为，例如 thinking 模型的推理强度（如 { openai: { reasoningEffort: 'low' } }）。

outputProcessors?:

OutputProcessorOrWorkflow[]

本次执行使用的输出 processor（覆盖 Agent 的默认值）。

maxProcessorRetries?:

number

本次生成中 processor 可触发重试的最大次数。覆盖 Agent 的默认 maxProcessorRetries。

inputProcessors?:

InputProcessorOrWorkflow[]

本次执行使用的输入 processor（覆盖 Agent 的默认值）。

instructions?:

本次执行中覆盖 Agent 默认指令的自定义指令。可以是单个字符串、消息对象，或二者任一类型的数组。

system?:

要包含在 prompt 中的自定义 system 消息。可以是单个字符串、消息对象，或二者任一类型的数组。system 消息提供额外的上下文或行为指令，以补充 Agent 的主要指令。

output?:

Zod schema | JsonSchema7

**已弃用。** 使用不带 model 的 structuredOutput 可实现相同效果。定义预期输出结构。可以是 JSON Schema 对象或 Zod schema。

memory?:

object

用于对话持久化和检索的 memory 配置。

object

thread:

string | { id: string; metadata?: Record<string, any>, title?: string }

用于保持对话连续性的 thread 标识符。可以是字符串 ID，也可以是包含 ID 以及可选 metadata/title 的对象。

resource:

string

用于按用户、session 或上下文组织对话的 resource 标识符。

options?:

MemoryConfig

其他 memory 配置选项，包括 lastMessages、readOnly、semanticRecall、workingMemory 和 filterIncompleteToolCalls。

onTitleGenerated?:

(title: string) => void | Promise<void>

生成 thread 标题并将其持久化到存储后异步触发的回调。标题生成在后台运行，可能在 generate() 返回后才完成。仅当 memory 选项中启用了 generateTitle 且 thread 没有现有标题时触发。

onFinish?:

LoopConfig['onFinish']

生成完成时触发的回调。

onStepFinish?:

LoopConfig['onStepFinish']

每个生成步骤完成后触发的回调。

telemetry?:

TelemetrySettings

生成期间的 OTLP telemetry 收集设置（非 Tracing）。

TelemetrySettings

isEnabled?:

boolean

是否启用 telemetry 收集。

recordInputs?:

boolean

是否在 telemetry 中记录输入数据。

recordOutputs?:

boolean

是否在 telemetry 中记录输出数据。

functionId?:

string

正在执行的函数标识符。

modelSettings?:

CallSettings

Model-specific settings like temperature, maxOutputTokens, topP, etc. These settings control how the language model generates responses.

temperature?:

number

Controls randomness in generation (0-2). Higher values make output more random.

maxOutputTokens?:

number

Maximum number of tokens to generate in the response. Note: Use maxOutputTokens (not maxTokens) as per AI SDK v5 convention.

maxRetries?:

number

Maximum number of retry attempts for failed requests.

topP?:

number

Nucleus sampling parameter (0-1). Controls diversity of generated text.

topK?:

number

Top-k sampling parameter. Limits vocabulary to k most likely tokens.

presencePenalty?:

number

Penalty for token presence (-2 to 2). Reduces repetition.

frequencyPenalty?:

number

Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.

stopSequences?:

string[]

Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.

toolChoice?:

'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }

控制生成期间如何选择 Tool。

'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }

'auto':

string

让模型决定何时使用 Tool（默认）。

'none':

string

完全禁用 Tool。

'required':

string

强制模型使用至少一个 Tool。

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

object

强制模型使用指定 Tool。

toolsets?:

ToolsetsInput

本次执行可使用的其他 Tool 集。

clientTools?:

ToolsInput

执行期间可用的客户端 Tool。

hooks?:

ToolHooks

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

savePerStep?:

boolean

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

providerOptions?:

Record<string, Record<string, JSONValue>>

传递给语言模型的 Provider 专属选项。

Record<string, Record<string, JSONValue>>

openai?:

Record<string, JSONValue>

OpenAI 专属选项，例如 reasoningEffort、responseFormat 等。

anthropic?:

Record<string, JSONValue>

Anthropic 专属选项，例如 maxTokens 等。

google?:

Record<string, JSONValue>

Google 专属选项。

[providerName]?:

Record<string, JSONValue>

任意 Provider 专属选项。

runId?:

string

本次执行运行的唯一标识符。

requestContext?:

RequestContext

包含动态配置和状态的 Request Context。

tracingContext?:

TracingContext

用于创建子 span 和添加 metadata 的 Tracing 上下文。使用 Mastra 的 tracing 系统时会自动注入。

TracingContext

currentSpan?:

Span

用于创建子 span 和添加 metadata 的当前 span。可用于在执行期间创建自定义子 span 或更新 span 属性。

tracingOptions?:

TracingOptions

Tracing 配置选项。

TracingOptions

metadata?:

Record<string, any>

要添加到根 trace span 的 metadata。适合添加用户 ID、session ID 或 feature flag 等自定义属性。

requestContextKeys?:

string[]

要提取为此 trace 的 metadata 的其他 RequestContext key。嵌套值支持点表示法（例如 'user.id'）。

traceId?:

string

本次执行使用的 trace ID（1-32 个十六进制字符）。如果提供，此 trace 将成为指定 trace 的一部分。

parentSpanId?:

string

本次执行使用的父 span ID（1-16 个十六进制字符）。如果提供，根 span 将创建为该 span 的子 span。

tags?:

string[]

要应用于此 trace 的 tag。用于对 trace 进行分类和筛选的字符串标签。

versions?:

VersionOverrides

子 Agent 委派的每次调用版本覆盖。与 Mastra 实例级版本合并，并通过 requestContext 在子 Agent 调用中自动传播。需要 editor package。请参阅 Editor 版本控制。

VersionOverrides

agents?:

Record<string, VersionSelector>

Agent ID 到其版本选择器的映射。

VersionSelector

versionId?:

string

通过 ID 指定特定版本。

status?:

'draft' | 'published'

指定具有此发布状态的最新版本。

includeRawChunks?:

boolean

是否在 stream 输出中包含原始 chunk。并非所有模型 Provider 都支持。

响应结构
响应结构的直接链接

Agent.generate() 返回执行期间收集的最终数据。steps 是步骤对象数组。结果中的 Tool 数组（包括顶层 toolCalls 和 toolResults，以及嵌套的 step.toolCalls 和 step.toolResults 数组）使用 Mastra 的 chunk 格式。

这意味着 Tool 数据封装在 payload 中：

const response = await agent.generate('Check the weather in Lagos')

for (const toolCall of response.toolCalls) {
  console.log(toolCall.type) // 'tool-call'
  console.log(toolCall.runId)
  console.log(toolCall.from)
  console.log(toolCall.payload.toolName)
  console.log(toolCall.payload.args)
}

for (const step of response.steps) {
  for (const toolResult of step.toolResults) {
    console.log(toolResult.type) // 'tool-result'
    console.log(toolResult.payload.toolName)
    console.log(toolResult.payload.result)
  }
}

有关相同 chunk 结构的流式版本，请参阅 ChunkType 参考。

返回值
返回值的直接链接

result:

Awaited<ReturnType<MastraModelOutput<Output>['getFullOutput']>>

返回生成过程的完整输出，包括文本、对象（如果使用结构化输出）、Tool 调用、Tool 结果、用量统计和步骤信息。

text:

string

Agent 生成的文本响应。

object?:

Output | undefined

如果提供了 structuredOutput，则为通过 schema 验证的结构化输出对象。

toolCalls:

ToolCallChunk[]

生成期间发出的 Tool 调用 chunk 数组。

ToolCallChunk

type:

'tool-call'

chunk 类型标识符。

runId:

string

执行运行标识符。

from:

ChunkFrom

chunk 的来源，例如 AGENT 或 WORKFLOW。

payload:

ToolCallPayload

Tool 调用数据。

ToolCallPayload

toolCallId:

string

Tool 调用的唯一标识符。

toolName:

string

被调用 Tool 的名称。

args?:

Record<string, unknown>

传递给 Tool 的参数。

providerExecuted?:

boolean

模型 Provider 是否直接执行了 Tool。

toolResults:

ToolResultChunk[]

Tool 执行产生的 Tool 结果 chunk 数组。

ToolResultChunk

type:

'tool-result'

chunk 类型标识符。

runId:

string

执行运行标识符。

from:

ChunkFrom

chunk 的来源，例如 AGENT 或 WORKFLOW。

payload:

ToolResultPayload

Tool 结果数据。

ToolResultPayload

toolCallId:

string

Tool 调用的唯一标识符。

toolName:

string

产生结果的 Tool 名称。

result:

unknown

Tool 返回的值。

isError?:

boolean

Tool 执行是否失败。

usage:

TokenUsage

生成的 token 用量统计。

steps:

object[]

执行步骤数组，适用于调试多步骤生成。

object

text:

string

此步骤中生成的文本。

toolCalls:

ToolCallChunk[]

此步骤中发出的 Tool 调用。

toolResults:

ToolResultChunk[]

此步骤中发出的 Tool 结果。

finishReason?:

string

此步骤完成的原因。

usage:

LanguageModelUsage

此步骤的 token 用量。

request:

{ body?: unknown }

此步骤的请求 metadata。

response:

object

此步骤的响应 metadata。

finishReason:

string

生成完成的原因。值包括 'stop'（正常完成）、'tool-calls'（以 Tool 调用结束）、'suspended'（等待 Tool 审批）或 'error'（发生错误）。

response:

object

模型 Provider 返回的响应 metadata。适合用于访问速率限制 header 和请求 ID。

object

id?:

string

模型 Provider 返回的响应 ID。

timestamp?:

Date

生成响应时的时间戳。

modelId?:

string

此响应使用的模型标识符。

headers?:

Record<string, string>

模型 Provider 返回的 HTTP 响应 header。包含速率限制信息（例如 anthropic-ratelimit-requests-remaining、x-ratelimit-remaining-tokens）和其他 Provider 专属 metadata。

messages?:

ResponseMessage[]

模型格式的响应消息。

uiMessages?:

UIMessage[]

UI 格式的响应消息，包括输出 processor 添加的所有 metadata。

request?:

object

发送给模型的请求。

object

body?:

unknown

发送给模型 Provider 的请求正文。

warnings?:

LanguageModelWarning[]

生成期间模型 Provider 返回的所有警告。

providerMetadata?:

Record<string, unknown>

随响应返回的 Provider 专属 metadata。

reasoning?:

ReasoningChunk[]

支持推理的模型所返回的推理详细信息（例如 OpenAI o1 系列）。

reasoningText?:

string

推理模型返回的合并推理文本。

sources?:

SourceChunk[]

模型在生成期间引用的来源。

files?:

FileChunk[]

模型生成的文件。

suspendPayload?:

object

当 finishReason 为 'suspended' 时存在。包含批准或拒绝待处理 Tool 调用所需的 Tool 调用详细信息。

object

toolCallId:

string

待处理 Tool 调用的唯一标识符。

toolName:

string

需要审批的 Tool 名称。

args:

Record<string, any>

将传递给 Tool 的参数。

runId?:

string

本次执行运行的唯一标识符。调用 approveToolCallGenerate() 或 declineToolCallGenerate() 恢复暂停的执行时必需。

traceId?:

string

启用 Tracing 后与本次执行关联的 trace ID。可用于关联日志和调试执行流程。

spanId?:

string

启用 Tracing 后与本次执行关联的根 span ID。可用于 span 级查找和关联。

messages:

MastraDBMessage[]

本次执行的所有消息，包括输入、memory 历史记录和响应。

rememberedMessages:

MastraDBMessage[]

仅从 memory 加载的消息（对话历史记录）。

error?:

Error

生成失败时的 Error 对象。

tripwire?:

StepTripwireData

内容被 processor 阻止时的 Tripwire 数据。

scoringData?:

object

启用 returnScorerData 时用于 Evals 的评分数据。

更多示例
更多示例的直接链接

使用模型设置
使用模型设置的直接链接

限制输出 token 数并设置 temperature 的示例：

const limitedResult = await agent.generate('Write a short poem about coding', {
  modelSettings: {
    maxOutputTokens: 50,
    temperature: 0.7,
  },
})

使用 memory
使用 memory的直接链接

通过配置 memory 选项，让 Agent 能够访问并持久化对话历史记录。这使 Agent 可以记住之前的交互，并在不同消息间保持上下文。

const memoryResult = await agent.generate('Remember my favorite color is blue', {
  memory: {
    thread: 'user-123-thread',
    resource: 'user-123',
  },
})

访问响应 header
访问响应 header的直接链接

某些模型 Provider 会在响应 header 中返回有用的信息，例如剩余 token 数或速率限制状态。生成完成后，可以从结果对象中访问这些 header。

const result = await agent.generate('Hello!')
const remainingRequests = result.response?.headers?.['anthropic-ratelimit-requests-remaining']
const remainingTokens = result.response?.headers?.['x-ratelimit-remaining-tokens']
console.log(`Remaining requests: ${remainingRequests}, Remaining tokens: ${remainingTokens}`)

分析图片
分析图片的直接链接

Agent 可以通过处理视觉内容及其中的文本来分析和描述图片。要启用图片分析，请在 content 数组中传入一个包含 type: 'image' 和图片 URL 的对象。可以将图片内容与文本 prompt 结合，以引导 Agent 进行分析。

const response = await agent.generate([
  {
    role: 'user',
    content: [
      {
        type: 'image',
        image: 'https://placebear.com/cache/395-205.jpg',
        mimeType: 'image/jpeg',
      },
      {
        type: 'text',
        text: 'Describe the image in detail, and extract all the text in the image.',
      },
    ],
  },
])

console.log(response.text)

使用 `maxSteps`
using-maxsteps的直接链接

maxSteps 参数控制 Agent 可连续调用 LLM 的最大次数。每个步骤都会生成响应并执行所有 Tool 调用，然后再处理结果。限制步骤数有助于防止无限循环并降低延迟，同时还可以控制使用 Tool 的 Agent 的 token 用量。默认值为 5，但可以增加：

const response = await agent.generate('Help me organize my day', {
  maxSteps: 10,
})

console.log(response.text)

使用 `onStepFinish`
using-onstepfinish的直接链接

可以使用 onStepFinish 回调监控多步骤操作的进度。这适合用于调试或向用户提供进度更新。

onStepFinish 仅在流式生成或不使用结构化输出生成文本时可用。

const response = await agent.generate('Help me organize my day', {
  onStepFinish: ({ text, toolCalls, toolResults, finishReason, usage }) => {
    console.log({ text, toolCalls, toolResults, finishReason, usage })
  },
})

使用 `onTitleGenerated`
using-ontitlegenerated的直接链接

在 memory 选项中启用 generateTitle 后，标题生成会在响应完成后异步运行。使用 onTitleGenerated 可在标题就绪时进行处理，例如通过 SSE 将其推送到客户端。

const response = await agent.generate('What is quantum computing?', {
  memory: {
    thread: threadId,
    resource: userId,
    onTitleGenerated: title => {
      console.log('Thread title:', title)
    },
  },
})

用法示例用法示例的直接链接

参数参数的直接链接

messages:

options?:

maxSteps?:

stopWhen?:

onIterationComplete?:

context.iteration:

context.maxIterations:

context.text:

context.isFinal:

context.finishReason:

context.toolCalls:

context.messages:

return.continue?:

return.feedback?:

isTaskComplete?:

scorers:

strategy?:

onComplete?:

parallel?:

timeout?:

delegation?:

onDelegationStart?:

onDelegationComplete?:

messageFilter?:

scorers?:

scorer:

sampling?:

type:

rate?:

returnScorerData?:

onChunk?:

onError?:

onAbort?:

activeTools?:

abortSignal?:

prepareStep?:

requireToolApproval?:

autoResumeSuspendedTools?:

toolCallConcurrency?:

context?:

structuredOutput?:

schema:

model?:

errorStrategy?:

fallbackValue?:

instructions?:

jsonPromptInjection?:

logger?:

providerOptions?:

outputProcessors?:

maxProcessorRetries?:

inputProcessors?:

instructions?:

system?:

output?:

memory?:

thread:

resource:

options?:

onTitleGenerated?:

onFinish?:

onStepFinish?:

telemetry?:

isEnabled?:

recordInputs?:

recordOutputs?:

functionId?:

modelSettings?:

temperature?:

maxOutputTokens?:

maxRetries?:

topP?:

topK?:

presencePenalty?:

frequencyPenalty?:

stopSequences?:

toolChoice?:

'auto':

用法示例
用法示例的直接链接

参数
参数的直接链接

响应结构
响应结构的直接链接

返回值
返回值的直接链接