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>

每次反覆運算完成後呼叫的 callback 函式。可用來監控進度、提供 feedback 以引導 Agent，或提早停止執行。callback 會收到反覆運算的 context，包括目前文字、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 下一次反覆運算的 feedback 訊息。

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>

任務完成檢查結束時呼叫的 callback。會收到包含各 Scorer 分數的結果。

parallel?:

boolean

是否平行執行 Scorer。

timeout?:

number

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

delegation?:

DelegationConfig

子 Agent 委派設定。可用來控制及監控 Agent 將任務委派給其他 Agent 的時機，包括修改或拒絕委派，以及提供 feedback 來引導 supervisor。

DelegationConfig

onDelegationStart?:

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

委派給子 Agent 前呼叫。可用來修改委派參數、完全拒絕委派，或變更 context.requestContext 以在子 Agent run 的 request context 中新增項目。

onDelegationComplete?:

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

子 Agent 委派完成後呼叫。context 包含可停止後續執行的 bail() 方法；您也可以回傳 { feedback } 來引導 supervisor 的下一個動作。feedback 會以 assistant 訊息儲存至 supervisor 記憶體。

messageFilter?:

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

委派給子 Agent 前呼叫的 callback 函式。可用來篩選要傳給子 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 都會呼叫的 callback 函式。

onError?:

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

生成期間發生錯誤時呼叫的 callback 函式。

onAbort?:

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

生成中止時呼叫的 callback 函式。

activeTools?:

Array<keyof ToolSet> | undefined

執行期間應啟用的 Tool 名稱陣列。若為 undefined，則會啟用所有可用 Tool。

abortSignal?:

AbortSignal

可讓您中止 Agent 執行的 signal 物件。signal 中止時，所有進行中的作業都會終止，包括 Agent 委派且正在執行的子 Agent run。

prepareStep?:

PrepareStepFunction

多步驟執行的每個步驟前呼叫的 callback 函式。

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 的其他 context 訊息。

structuredOutput?:

StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>

用來微調結構化輸出生成的選項。

StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>

schema:

StandardJSONSchemaV1

定義預期輸出結構的 Standard JSON Schema。

model?:

MastraLanguageModel

結構化輸出生成要使用的語言模型。提供此值後，Agent 能以多個步驟回應 Tool 呼叫、文字與結構化輸出

errorStrategy?:

'strict' | 'warn' | 'fallback'

處理 schema 驗證錯誤的策略。'strict' 會擲回錯誤、'warn' 會記錄警告、'fallback' 會使用 fallback 值。

fallbackValue?:

<S extends ZodTypeAny>

schema 驗證失敗且 errorStrategy 為 'fallback' 時使用的 fallback 值。

instructions?:

string

提供給結構化輸出模型的其他指示。

jsonPromptInjection?:

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

控制 JSON schema 傳給模型的方式。設為 'auto' 可在支援時使用原生結構化輸出，否則使用 inline prompt injection。

logger?:

IMastraLogger

輸出生成期間進行結構化 logging 的選用 logger 執行個體。

providerOptions?:

ProviderOptions

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

outputProcessors?:

OutputProcessorOrWorkflow[]

此次執行要使用的輸出 Processor（覆寫 Agent 預設值）。

maxProcessorRetries?:

number

此次生成中 Processor 可觸發重試的次數上限。覆寫 Agent 的預設 maxProcessorRetries。

inputProcessors?:

InputProcessorOrWorkflow[]

此次執行要使用的輸入 Processor（覆寫 Agent 預設值）。

instructions?:

string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]

覆寫 Agent 此次執行所用預設指示的自訂指示。可以是單一字串、訊息物件，或兩者任一的陣列。

system?:

string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]

要包含在 prompt 中的自訂 system message。可以是單一字串、訊息物件，或兩者任一的陣列。system message 會提供其他 context 或行為指示，以補充 Agent 的主要指示。

output?:

Zod schema | JsonSchema7

**已棄用。** 使用不含 model 的 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 或 context 組織對話的 resource 識別碼。

options?:

MemoryConfig

其他記憶體設定選項，包括 lastMessages、readOnly、semanticRecall、workingMemory 與 filterIncompleteToolCalls。

onTitleGenerated?:

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

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

onFinish?:

LoopConfig['onFinish']

生成完成時觸發的 callback。

onStepFinish?:

LoopConfig['onStepFinish']

每個生成步驟後觸發的 callback。

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 set。

clientTools?:

ToolsInput

執行期間可用的 client 端 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

此次執行 run 的唯一識別碼。

requestContext?:

RequestContext

包含動態設定與狀態的 Request Context。

tracingContext?:

TracingContext

用於建立子 span 及新增 metadata 的 Tracing context。使用 Mastra 的 Tracing 系統時會自動注入。

TracingContext

currentSpan?:

Span

目前的 span，用於建立子 span 及新增 metadata。可用來在執行期間建立自訂子 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 至版本 selector 的對應表。

VersionSelector

versionId?:

string

依 ID 指定特定版本。

status?:

'draft' | 'published'

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

includeRawChunks?:

boolean

是否在 stream 輸出中包含原始 chunk。並非所有模型 Provider 都支援。

回應結構

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

也就是說，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

執行 run 識別碼。

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

執行 run 識別碼。

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 }

此步驟的 request metadata。

response:

object

此步驟的回應 metadata。

finishReason:

string

生成完成的原因。值包括 'stop'（正常完成）、'tool-calls'（以 Tool 呼叫結束）、'suspended'（等待 Tool 核准）或 'error'（發生錯誤）。

response:

object

模型 Provider 的回應 metadata。適合用來存取 rate limit header 與 request ID。

object

id?:

string

模型 Provider 的回應 ID。

timestamp?:

Date

回應生成的時間戳記。

modelId?:

string

此回應使用的模型識別碼。

headers?:

Record<string, string>

模型 Provider 的 HTTP 回應 header。包含 rate limit 資訊（例如 anthropic-ratelimit-requests-remaining、x-ratelimit-remaining-tokens）與其他 Provider 專屬 metadata。

messages?:

ResponseMessage[]

模型格式的回應訊息。

uiMessages?:

UIMessage[]

UI 格式的回應訊息，包括輸出 Processor 新增的任何 metadata。

request?:

object

傳送給模型的 request。

object

body?:

unknown

傳送給模型 Provider 的 request 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

此次執行 run 的唯一識別碼。呼叫 approveToolCallGenerate() 或 declineToolCallGenerate() 以恢復已暫停執行時必填。

traceId?:

string

啟用 Tracing 時，與此執行作業關聯的 Trace ID。可用來關聯 log 及對執行流程進行偵錯。

spanId?:

string

啟用 Tracing 時，與此執行作業關聯的根 span ID。可用於 span 層級的查詢與關聯。

messages:

MastraDBMessage[]

此次執行的所有訊息，包括輸入、記憶體歷程與回應。

rememberedMessages:

MastraDBMessage[]

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

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,
  },
})

搭配記憶體

設定記憶體選項，讓 Agent 能存取並保存對話歷程。Agent 因此能記住先前互動，並跨訊息維持 context。

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

存取回應 header

部分模型 Provider 會在回應 header 中傳回實用資訊，例如剩餘 token 數或 rate limit 狀態。生成完成後，您可以從結果物件存取這些 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

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

您可以使用 onStepFinish callback 監控多步驟作業的進度，適合用來偵錯或向使用者提供進度更新。

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

在記憶體選項中啟用 generateTitle 後，標題生成會在回應完成後非同步執行。標題就緒時可使用 onTitleGenerated 回應，例如透過 SSE 推送至 client。

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