> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# Agent.generate()

`.generate()` 方法讓 Agent 能以增強功能進行非串流回應生成。此方法接受訊息與選用的生成選項。

## 使用範例

以訊息呼叫 Agent 以生成回應：

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

## 參數

**messages** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): 要傳送給 Agent 的訊息。可以是單一字串、字串陣列或結構化訊息物件。

**options** (`AgentExecutionOptions<Output, Format>`): 生成流程的選用設定。

**options.maxSteps** (`number`): 執行期間最多可執行的步驟數。

**options.stopWhen** (`LoopOptions['stopWhen']`): 停止執行的條件（例如步驟數、token 上限）。

**options.onIterationComplete** (`(context: IterationCompleteContext) => { continue?: boolean; feedback?: string } | void | Promise<{ continue?: boolean; feedback?: string } | void>`): 每次反覆運算完成後呼叫的 callback 函式。可用來監控進度、提供 feedback 以引導 Agent，或提早停止執行。callback 會收到反覆運算的 context，包括目前文字、Tool 呼叫與完成原因。

**options.onIterationComplete.context.iteration** (`number`): 目前的反覆運算編號（從 1 開始）。

**options.onIterationComplete.context.maxIterations** (`number | undefined`): 允許的反覆運算次數上限（若已設定）。

**options.onIterationComplete.context.text** (`string`): 此次反覆運算的文字回應。

**options.onIterationComplete.context.isFinal** (`boolean`): 這是否為最後一次反覆運算。

**options.onIterationComplete.context.finishReason** (`string`): 此次反覆運算完成的原因（例如 'stop'、'length'、'tool-calls'）。

**options.onIterationComplete.context.toolCalls** (`ToolCall[]`): 此次反覆運算進行的 Tool 呼叫。

**options.onIterationComplete.context.messages** (`MastraDBMessage[]`): 目前累積的所有訊息。

**options.onIterationComplete.return.continue** (`boolean`): 設為 false 可提早停止執行。

**options.onIterationComplete.return.feedback** (`string`): 用來引導 Agent 下一次反覆運算的 feedback 訊息。

**options.isTaskComplete** (`IsTaskCompleteConfig`): 用來驗證任務是否完成的任務完成評分設定。使用 Mastra 的評估 Scorer，自動檢查 Agent 回應是否符合完成條件。

**options.isTaskComplete.scorers** (`MastraScorer[]`): 用來評估任務是否完成的 Scorer 陣列。每個 Scorer 會回傳 0（失敗）或 1（通過）。

**options.isTaskComplete.strategy** (`'all' | 'any'`): 組合 Scorer 結果的策略。'all' 要求所有 Scorer 都通過；'any' 則要求至少一個通過。

**options.isTaskComplete.onComplete** (`(result: IsTaskCompleteRunResult) => void | Promise<void>`): 任務完成檢查結束時呼叫的 callback。會收到包含各 Scorer 分數的結果。

**options.isTaskComplete.parallel** (`boolean`): 是否平行執行 Scorer。

**options.isTaskComplete.timeout** (`number`): 等待所有 Scorer 完成的最長時間（毫秒）。

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

**options.delegation.onDelegationStart** (`(context: DelegationStartContext) => DelegationStartResult | void | Promise<DelegationStartResult | void>`): 委派給子 Agent 前呼叫。可用來修改委派參數、完全拒絕委派，或變更 context.requestContext 以在子 Agent run 的 request context 中新增項目。

**options.delegation.onDelegationComplete** (`(context: DelegationCompleteContext) => { feedback?: string } | void | Promise<{ feedback?: string } | void>`): 子 Agent 委派完成後呼叫。context 包含可停止後續執行的 bail() 方法；您也可以回傳 { feedback } 來引導 supervisor 的下一個動作。feedback 會以 assistant 訊息儲存至 supervisor 記憶體。

**options.delegation.messageFilter** (`(context: MessageFilterContext) => MastraDBMessage[] | Promise<MastraDBMessage[]>`): 委派給子 Agent 前呼叫的 callback 函式。可用來篩選要傳給子 Agent 的訊息。

**options.scorers** (`MastraScorers | Record<string, { scorer: MastraScorer['name']; sampling?: ScoringSamplingConfig }>`): 要針對執行結果執行的評估 Scorer。

**options.scorers.scorer** (`string`): 要使用的 Scorer 名稱。

**options.scorers.sampling** (`ScoringSamplingConfig`): Scorer 的取樣設定。

**options.scorers.sampling.type** (`'none' | 'ratio'`): 取樣策略類型。使用 'none' 可停用取樣；使用 'ratio' 可依百分比取樣。

**options.scorers.sampling.rate** (`number`): 取樣率（0 至 1）。type 為 'ratio' 時必填。

**options.returnScorerData** (`boolean`): 是否在回應中回傳詳細評分資料。

**options.onChunk** (`(chunk: ChunkType) => Promise<void> | void`): 生成期間每個 chunk 都會呼叫的 callback 函式。

**options.onError** (`({ error }: { error: Error | string }) => Promise<void> | void`): 生成期間發生錯誤時呼叫的 callback 函式。

**options.onAbort** (`(event: any) => Promise<void> | void`): 生成中止時呼叫的 callback 函式。

**options.activeTools** (`Array<keyof ToolSet> | undefined`): 執行期間應啟用的 Tool 名稱陣列。若為 undefined，則會啟用所有可用 Tool。

**options.abortSignal** (`AbortSignal`): 可讓您中止 Agent 執行的 signal 物件。signal 中止時，所有進行中的作業都會終止，包括 Agent 委派且正在執行的子 Agent run。

**options.prepareStep** (`PrepareStepFunction`): 多步驟執行的每個步驟前呼叫的 callback 函式。

**options.requireToolApproval** (`boolean`): 設為 true 時，所有 Tool 呼叫都必須在執行前明確核准。generate() 方法會回傳 finishReason: 'suspended'，並包含具有 Tool 呼叫詳細資料（toolCallId、toolName、args）的 suspendPayload。使用 approveToolCallGenerate() 或 declineToolCallGenerate() 繼續。詳細資訊請參閱 Agent 核准。

**options.autoResumeSuspendedTools** (`boolean`): 設為 true 時，使用者在同一 thread 傳送新訊息後會自動恢復已暫停的 Tool。Agent 會依 Tool 的 resumeSchema 從使用者訊息擷取 resumeData。必須設定記憶體。

**options.toolCallConcurrency** (`number`): 可同時執行的 Tool 呼叫數量上限。可能需要核准時預設為 1，否則為 10。

**options.context** (`ModelMessage[]`): 要提供給 Agent 的其他 context 訊息。

**options.structuredOutput** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): 用來微調結構化輸出生成的選項。

**options.structuredOutput.schema** (`StandardJSONSchemaV1`): 定義預期輸出結構的 Standard JSON Schema。

**options.structuredOutput.model** (`MastraLanguageModel`): 結構化輸出生成要使用的語言模型。提供此值後，Agent 能以多個步驟回應 Tool 呼叫、文字與結構化輸出

**options.structuredOutput.errorStrategy** (`'strict' | 'warn' | 'fallback'`): 處理 schema 驗證錯誤的策略。'strict' 會擲回錯誤、'warn' 會記錄警告、'fallback' 會使用 fallback 值。

**options.structuredOutput.fallbackValue** (`<S extends ZodTypeAny>`): schema 驗證失敗且 errorStrategy 為 'fallback' 時使用的 fallback 值。

**options.structuredOutput.instructions** (`string`): 提供給結構化輸出模型的其他指示。

**options.structuredOutput.jsonPromptInjection** (`boolean | 'system' | 'inline' | 'auto'`): 控制 JSON schema 傳給模型的方式。設為 'auto' 可在支援時使用原生結構化輸出，否則使用 inline prompt injection。

**options.structuredOutput.logger** (`IMastraLogger`): 輸出生成期間進行結構化 logging 的選用 logger 執行個體。

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

**options.outputProcessors** (`OutputProcessorOrWorkflow[]`): 此次執行要使用的輸出 Processor（覆寫 Agent 預設值）。

**options.maxProcessorRetries** (`number`): 此次生成中 Processor 可觸發重試的次數上限。覆寫 Agent 的預設 maxProcessorRetries。

**options.inputProcessors** (`InputProcessorOrWorkflow[]`): 此次執行要使用的輸入 Processor（覆寫 Agent 預設值）。

**options.instructions** (`string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]`): 覆寫 Agent 此次執行所用預設指示的自訂指示。可以是單一字串、訊息物件，或兩者任一的陣列。

**options.system** (`string | string[] | CoreSystemMessage | SystemModelMessage | CoreSystemMessage[] | SystemModelMessage[]`): 要包含在 prompt 中的自訂 system message。可以是單一字串、訊息物件，或兩者任一的陣列。system message 會提供其他 context 或行為指示，以補充 Agent 的主要指示。

**options.output** (`Zod schema | JsonSchema7`): \*\*已棄用。\*\* 使用不含 model 的 structuredOutput 可達到相同效果。定義預期的輸出結構。可以是 JSON Schema 物件或 Zod schema。

**options.memory** (`object`): 用於保存及擷取對話的記憶體設定。

**options.memory.thread** (`string | { id: string; metadata?: Record<string, any>, title?: string }`): 用於延續對話的 thread 識別碼。可以是字串 ID，或包含 ID 與選用 metadata/title 的物件。

**options.memory.resource** (`string`): 用來依使用者、session 或 context 組織對話的 resource 識別碼。

**options.memory.options** (`MemoryConfig`): 其他記憶體設定選項，包括 lastMessages、readOnly、semanticRecall、workingMemory 與 filterIncompleteToolCalls。

**options.memory.onTitleGenerated** (`(title: string) => void | Promise<void>`): 生成 thread 標題並保存至儲存空間時非同步觸發的 callback。標題生成會在背景執行，可能在 generate() 回傳後才完成。只有在記憶體選項中啟用 generateTitle，且 thread 沒有現有標題時才會觸發。

**options.onFinish** (`LoopConfig['onFinish']`): 生成完成時觸發的 callback。

**options.onStepFinish** (`LoopConfig['onStepFinish']`): 每個生成步驟後觸發的 callback。

**options.telemetry** (`TelemetrySettings`): 生成期間的 OTLP telemetry 收集設定（並非 Tracing）。

**options.telemetry.isEnabled** (`boolean`): 是否啟用 telemetry 收集。

**options.telemetry.recordInputs** (`boolean`): 是否在 telemetry 中記錄輸入資料。

**options.telemetry.recordOutputs** (`boolean`): 是否在 telemetry 中記錄輸出資料。

**options.telemetry.functionId** (`string`): 正在執行之函式的識別碼。

**options.modelSettings** (`CallSettings`): Model-specific settings like temperature, maxOutputTokens, topP, etc. These settings control how the language model generates responses.

**options.modelSettings.temperature** (`number`): Controls randomness in generation (0-2). Higher values make output more random.

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

**options.modelSettings.maxRetries** (`number`): Maximum number of retry attempts for failed requests.

**options.modelSettings.topP** (`number`): Nucleus sampling parameter (0-1). Controls diversity of generated text.

**options.modelSettings.topK** (`number`): Top-k sampling parameter. Limits vocabulary to k most likely tokens.

**options.modelSettings.presencePenalty** (`number`): Penalty for token presence (-2 to 2). Reduces repetition.

**options.modelSettings.frequencyPenalty** (`number`): Penalty for token frequency (-2 to 2). Reduces repetition of frequent tokens.

**options.modelSettings.stopSequences** (`string[]`): Stop sequences. If set, the model will stop generating text when one of the stop sequences is generated.

**options.toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): 控制生成期間選擇 Tool 的方式。

**options.toolChoice.'auto'** (`string`): 讓模型決定何時使用 Tool（預設值）。

**options.toolChoice.'none'** (`string`): 完全停用 Tool。

**options.toolChoice.'required'** (`string`): 強制模型至少使用一個 Tool。

**options.toolChoice.{ type: 'tool'; toolName: string }** (`object`): 強制模型使用特定 Tool。

**options.toolsets** (`ToolsetsInput`): 此次執行可使用的其他 Tool set。

**options.clientTools** (`ToolsInput`): 執行期間可用的 client 端 Tool。

**options.hooks** (`ToolHooks`): Tool 呼叫前後執行的單次執行 hook。會覆寫此次執行中相符的 Agent 層級 hook。beforeToolCall 可回傳 { proceed: false, output } 以略過 Tool 呼叫。

**options.savePerStep** (`boolean`): 每個生成步驟完成後逐步儲存訊息（預設：false）。啟用觀察式記憶體時會在內部停用。

**options.providerOptions** (`Record<string, Record<string, JSONValue>>`): 傳給語言模型的 Provider 專屬選項。

**options.providerOptions.openai** (`Record<string, JSONValue>`): OpenAI 專屬選項，例如 reasoningEffort、responseFormat 等。

**options.providerOptions.anthropic** (`Record<string, JSONValue>`): Anthropic 專屬選項，例如 maxTokens 等。

**options.providerOptions.google** (`Record<string, JSONValue>`): Google 專屬選項。

**options.providerOptions.\[providerName]** (`Record<string, JSONValue>`): 任何 Provider 專屬選項。

**options.runId** (`string`): 此次執行 run 的唯一識別碼。

**options.requestContext** (`RequestContext`): 包含動態設定與狀態的 Request Context。

**options.tracingContext** (`TracingContext`): 用於建立子 span 及新增 metadata 的 Tracing context。使用 Mastra 的 Tracing 系統時會自動注入。

**options.tracingContext.currentSpan** (`Span`): 目前的 span，用於建立子 span 及新增 metadata。可用來在執行期間建立自訂子 span 或更新 span 屬性。

**options.tracingOptions** (`TracingOptions`): Tracing 設定選項。

**options.tracingOptions.metadata** (`Record<string, any>`): 要新增至根 Trace span 的 metadata。適合用來加入使用者 ID、session ID 或功能旗標等自訂屬性。

**options.tracingOptions.requestContextKeys** (`string[]`): 要擷取為此 Trace metadata 的其他 RequestContext key。巢狀值支援點號表示法（例如 'user.id'）。

**options.tracingOptions.traceId** (`string`): 此執行作業要使用的 Trace ID（1 至 32 個十六進位字元）。若提供此值，這個 Trace 會成為指定 Trace 的一部分。

**options.tracingOptions.parentSpanId** (`string`): 此執行作業要使用的父 span ID（1 至 16 個十六進位字元）。若提供此值，根 span 會建立為此 span 的子項。

**options.tracingOptions.tags** (`string[]`): 要套用至此 Trace 的標籤。可用這些字串標籤將 Trace 分類及篩選。

**options.versions** (`VersionOverrides`): 子 Agent 委派的單次叫用版本覆寫值。會合併於 Mastra 執行個體層級版本之上，並透過 requestContext 隨子 Agent 呼叫自動傳播。需要 editor 套件。請參閱 Editor 版本控制。

**options.versions.agents** (`Record<string, VersionSelector>`): Agent ID 至版本 selector 的對應表。

**options.versions.agents.versionId** (`string`): 依 ID 指定特定版本。

**options.versions.agents.status** (`'draft' | 'published'`): 指定具有此發布狀態的最新版本。

**options.includeRawChunks** (`boolean`): 是否在 stream 輸出中包含原始 chunk。並非所有模型 Provider 都支援。

## 回應結構

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

也就是說，Tool 資料會包裝在 `payload` 中：

```ts
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 參考文件](https://mastra.zisheng.pro/zh-TW/reference/streaming/ChunkType)。

## 回傳值

**result** (`Awaited<ReturnType<MastraModelOutput<Output>['getFullOutput']>>`): 回傳生成流程的完整輸出，包括文字、物件（若為結構化輸出）、Tool 呼叫、Tool 結果、用量統計與步驟資訊。

**text** (`string`): Agent 生成的文字回應。

**object** (`Output | undefined`): 若提供 structuredOutput，則為依 schema 驗證的結構化輸出物件。

**toolCalls** (`ToolCallChunk[]`): 生成期間產生的 Tool 呼叫 chunk 陣列。

**toolCalls.type** (`'tool-call'`): chunk 類型識別碼。

**toolCalls.runId** (`string`): 執行 run 識別碼。

**toolCalls.from** (`ChunkFrom`): chunk 的來源，例如 AGENT 或 WORKFLOW。

**toolCalls.payload** (`ToolCallPayload`): Tool 呼叫資料。

**toolCalls.payload.toolCallId** (`string`): Tool 呼叫的唯一識別碼。

**toolCalls.payload.toolName** (`string`): 所呼叫 Tool 的名稱。

**toolCalls.payload.args** (`Record<string, unknown>`): 傳給 Tool 的引數。

**toolCalls.payload.providerExecuted** (`boolean`): 模型 Provider 是否直接執行 Tool。

**toolResults** (`ToolResultChunk[]`): Tool 執行所產生的 Tool 結果 chunk 陣列。

**toolResults.type** (`'tool-result'`): chunk 類型識別碼。

**toolResults.runId** (`string`): 執行 run 識別碼。

**toolResults.from** (`ChunkFrom`): chunk 的來源，例如 AGENT 或 WORKFLOW。

**toolResults.payload** (`ToolResultPayload`): Tool 結果資料。

**toolResults.payload.toolCallId** (`string`): Tool 呼叫的唯一識別碼。

**toolResults.payload.toolName** (`string`): 產生結果之 Tool 的名稱。

**toolResults.payload.result** (`unknown`): Tool 回傳的值。

**toolResults.payload.isError** (`boolean`): Tool 執行是否失敗。

**usage** (`TokenUsage`): 此次生成的 token 用量統計。

**steps** (`object[]`): 執行步驟陣列，適合用來偵錯多步驟生成。

**steps.text** (`string`): 此步驟生成的文字。

**steps.toolCalls** (`ToolCallChunk[]`): 此步驟發出的 Tool 呼叫。

**steps.toolResults** (`ToolResultChunk[]`): 此步驟發出的 Tool 結果。

**steps.finishReason** (`string`): 此步驟完成的原因。

**steps.usage** (`LanguageModelUsage`): 此步驟的 token 用量。

**steps.request** (`{ body?: unknown }`): 此步驟的 request metadata。

**steps.response** (`object`): 此步驟的回應 metadata。

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

**response** (`object`): 模型 Provider 的回應 metadata。適合用來存取 rate limit header 與 request ID。

**response.id** (`string`): 模型 Provider 的回應 ID。

**response.timestamp** (`Date`): 回應生成的時間戳記。

**response.modelId** (`string`): 此回應使用的模型識別碼。

**response.headers** (`Record<string, string>`): 模型 Provider 的 HTTP 回應 header。包含 rate limit 資訊（例如 anthropic-ratelimit-requests-remaining、x-ratelimit-remaining-tokens）與其他 Provider 專屬 metadata。

**response.messages** (`ResponseMessage[]`): 模型格式的回應訊息。

**response.uiMessages** (`UIMessage[]`): UI 格式的回應訊息，包括輸出 Processor 新增的任何 metadata。

**request** (`object`): 傳送給模型的 request。

**request.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 呼叫詳細資料。

**suspendPayload.toolCallId** (`string`): 待處理 Tool 呼叫的唯一識別碼。

**suspendPayload.toolName** (`string`): 需要核准之 Tool 的名稱。

**suspendPayload.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 的範例：

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

### 搭配記憶體

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

```ts
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。

```ts
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 進行分析。

```typescript
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，但可提高：

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

console.log(response.text)
```

### 使用 `onStepFinish`

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

`onStepFinish` 只有在串流或生成不含結構化輸出的文字時才可用。

```typescript
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。

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