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 的評估評分器，自動檢查 Agent 回應是否符合完成條件。

IsTaskCompleteConfig

scorers:

MastraScorer[]

評估工作完成情況的評分器陣列。每個評分器會傳回 0（失敗）或 1（通過）。

strategy?:

'all' | 'any'

合併評分器結果的策略。'all' 要求所有評分器均通過；'any' 則要求至少一個通過。

onComplete?:

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

工作完成檢查結束時呼叫的回呼。它會接收包含各評分器分數的結果。

parallel?:

boolean

是否並行運行評分器。

timeout?:

number

等待所有評分器完成的最長時間（毫秒）。

delegation?:

DelegationConfig

子 Agent 委派的設定。用來控制及監察 Agent 何時將工作委派給其他 Agent，亦可修改或拒絕委派，以及提供意見來引導監督 Agent。

DelegationConfig

onDelegationStart?:

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

委派給子 Agent 前呼叫。可用來修改委派參數、完全拒絕委派，或改動 context.requestContext，在子 Agent 運行的要求情境中加入項目。

onDelegationComplete?:

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

子 Agent 委派完成後呼叫。情境包含可停止後續執行的 bail() 方法；你亦可傳回 { feedback } 來引導監督 Agent 的下一步。意見會以助理訊息形式儲存至監督 Agent 的記憶體。

messageFilter?:

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

委派給子 Agent 前呼叫的回呼函式。可用來篩選傳送給子 Agent 的訊息。

scorers?:

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

要對執行結果運行的評估評分器。

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

scorer:

string

要使用的評分器名稱。

sampling?:

ScoringSamplingConfig

評分器的抽樣設定。

ScoringSamplingConfig

type:

'none' | 'ratio'

抽樣策略類型。使用 'none' 停用抽樣，或使用 'ratio' 按百分比抽樣。

rate?:

number

抽樣率（0 至 1）。當類型為 'ratio' 時必須提供。

returnScorerData?:

boolean

是否在回應中傳回詳細評分資料。

onChunk?:

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

產生期間每個區塊都會呼叫的回呼函式。

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 執行的訊號物件。訊號中止後，所有進行中的操作都會終止，包括 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。必須設定記憶體。

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'，支援時會使用原生結構化輸出，否則會使用行內提示注入。

logger?:

IMastraLogger

產生輸出期間用於結構化記錄的可選 logger 實例。

providerOptions?:

ProviderOptions

傳送給內部結構化 Agent 的 Provider 專用選項。可用來控制模型行為，例如思考模型的推理強度（例如 { openai: { reasoningEffort: 'low' } }）。

outputProcessors?:

OutputProcessorOrWorkflow[]

此執行使用的輸出處理器（覆寫 Agent 的預設值）。

maxProcessorRetries?:

number

處理器可觸發此產生程序重試的次數上限。覆寫 Agent 的預設 maxProcessorRetries。

inputProcessors?:

InputProcessorOrWorkflow[]

此執行使用的輸入處理器（覆寫 Agent 的預設值）。

instructions?:

覆寫 Agent 在此執行中預設指示的自訂指示。可以是單一字串、訊息物件或兩者之一的陣列。

system?:

要加入提示的自訂 system 訊息。可以是單一字串、訊息物件或兩者之一的陣列。system 訊息會提供額外情境或行為指示，以補充 Agent 的主要指示。

output?:

Zod schema | JsonSchema7

**已棄用。** 使用不含模型的 structuredOutput 可達到相同效果。定義預期的輸出結構。可以是 JSON Schema 物件或 Zod schema。

memory?:

object

用於保存及擷取對話的記憶體設定。

object

thread:

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

維持對話連續性的 thread 識別碼。可以是字串 ID，或包含 ID 及可選 metadata/title 的物件。

resource:

string

按使用者、session 或情境整理對話的資源識別碼。

options?:

MemoryConfig

額外記憶體設定選項，包括 lastMessages、readOnly、semanticRecall、workingMemory 及 filterIncompleteToolCalls。

onTitleGenerated?:

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

產生 thread 標題並保存至儲存空間後，以非同步方式觸發的回呼。標題會在背景產生，並可能在 generate() 傳回後才完成。只有在記憶體選項啟用 generateTitle，而且 thread 沒有現有標題時才會觸發。

onFinish?:

LoopConfig['onFinish']

產生程序完成時觸發的回呼。

onStepFinish?:

LoopConfig['onStepFinish']

每個產生步驟完成後觸發的回呼。

telemetry?:

TelemetrySettings

產生期間收集 OTLP 遙測資料的設定（並非 Tracing）。

TelemetrySettings

isEnabled?:

boolean

是否啟用遙測資料收集。

recordInputs?:

boolean

是否在遙測資料中記錄輸入資料。

recordOutputs?:

boolean

是否在遙測資料中記錄輸出資料。

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）。啟用觀察式記憶體時會在內部停用。

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

包含動態設定及狀態的要求情境。

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 或功能旗標等自訂屬性。

requestContextKeys?:

string[]

要擷取作此 trace metadata 的額外 RequestContext key。支援以點標記法表示巢狀值（例如 'user.id'）。

traceId?:

string

此執行使用的 Trace ID（1 至 32 個十六進位字元）。如有提供，此 trace 將屬於指定 trace。

parentSpanId?:

string

此執行使用的上層 span ID（1 至 16 個十六進位字元）。如有提供，根 span 會建立為此 span 的子項。

tags?:

string[]

要套用至此 trace 的標籤。用於分類及篩選 trace 的字串標籤。

versions?:

VersionOverrides

每次呼叫的子 Agent 委派版本覆寫。它會合併至 Mastra 實例層級版本之上，並透過 requestContext 在子 Agent 呼叫之間自動傳遞。需要 editor 套件。請參閱 Editor 版本控制。

VersionOverrides

agents?:

Record<string, VersionSelector>

Agent ID 至其版本選擇器的對應。

VersionSelector

versionId?:

string

按 ID 指定特定版本。

status?:

'draft' | 'published'

指定具此發佈狀態的最新版本。

includeRawChunks?:

boolean

是否在串流輸出中包含原始區塊。並非所有模型 Provider 均支援。

回應結構
回應結構的直接連結

Agent.generate() 會傳回執行期間收集的最終資料。steps 是步驟物件陣列。結果中的 Tool 陣列，包括最上層的 toolCalls 和 toolResults，以及巢狀的 step.toolCalls 和 step.toolResults 陣列，均使用 Mastra 的區塊格式。

亦即 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)
  }
}

如需相同區塊結構的串流版本，請參閱 ChunkType 參考。

傳回值
傳回值的直接連結

result:

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

傳回產生程序的完整輸出，包括文字、物件（如為結構化輸出）、Tool 呼叫、Tool 結果、用量統計及步驟資料。

text:

string

Agent 產生的文字回應。

object?:

Output | undefined

如有提供 structuredOutput，則為已按 schema 驗證的結構化輸出物件。

toolCalls:

ToolCallChunk[]

產生期間發出的 Tool 呼叫區塊陣列。

ToolCallChunk

type:

'tool-call'

區塊類型識別碼。

runId:

string

執行運行識別碼。

from:

ChunkFrom

區塊來源，例如 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 結果區塊陣列。

ToolResultChunk

type:

'tool-result'

區塊類型識別碼。

runId:

string

執行運行識別碼。

from:

ChunkFrom

區塊來源，例如 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 格式的回應訊息，包括輸出處理器加入的任何 metadata。

request?:

object

傳送給模型的要求。

object

body?:

unknown

傳送給模型 Provider 的要求 body。

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

此執行運行的唯一識別碼。 Required when calling approveToolCallGenerate() or declineToolCallGenerate() to resume a suspended execution.

traceId?:

string

啟用 Tracing 時與此執行相關聯的 trace ID。可用來關聯記錄及偵錯執行流程。

spanId?:

string

啟用 Tracing 時與此執行相關聯的根 span ID。可用於 span 層級查找及關聯。

messages:

MastraDBMessage[]

此執行的所有訊息，包括輸入、記憶體記錄及回應。

rememberedMessages:

MastraDBMessage[]

僅從記憶體載入的訊息（對話記錄）。

error?:

Error

產生失敗時的錯誤物件。

tripwire?:

StepTripwireData

內容被處理器封鎖時的 tripwire 資料。

scoringData?:

object

啟用 returnScorerData 時供 Evals 使用的評分資料。

更多範例
更多範例的直接連結

使用模型設定
使用模型設定的直接連結

限制輸出 token 並設定 temperature 的範例：

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

使用記憶體
使用記憶體的直接連結

透過設定記憶體選項，讓 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 的物件。你可將圖像內容與文字提示結合，以引導 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 的直接連結

在記憶體選項中啟用 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':

使用範例
使用範例的直接連結

參數
參數的直接連結

回應結構
回應結構的直接連結

傳回值
傳回值的直接連結