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

# Agent.generateLegacy()（舊版）

> **警告:** **已棄用**：此方法已棄用，且僅適用於舊版模型 adapter。若使用目前的模型 adapter，請改用 [`.generate()`](https://mastra.zisheng.pro/zh-TW/reference/agents/generate)。

`.generateLegacy()` 方法是 Agent 生成 API 的舊版，搭配舊版模型 adapter 產生文字或結構化回應。此方法接受訊息與選用的生成選項。

## 使用範例

```typescript
await agent.generateLegacy('message for agent')
```

## Processor 重試支援

`generateLegacy()` 不會執行錯誤 Processor 或 `maxProcessorRetries`，而是使用舊版 AI SDK 生成路徑。

使用舊版模型 adapter 的 Scorer judge 會呼叫 `generateLegacy()`。它們不會取得使用 Mastra 目前生成 API 之 Scorer judge 可用的協調式 `StreamErrorRetryProcessor` 額度。若需要錯誤 Processor 重試，請使用目前的模型 adapter。舊版 `maxRetries` 選項仍會分開計算，預設為 `2`。

## 參數

**messages** (`string | string[] | CoreMessage[] | AiMessageType[] | UIMessageWithMetadata[]`): 要傳送給 Agent 的訊息。可以是單一字串、字串陣列，或包含多模態內容（文字、圖片等）的結構化訊息物件。

**options** (`AgentGenerateOptions`): 生成流程的選用設定。

**options.abortSignal** (`AbortSignal`): 可讓您中止 Agent 執行的 signal 物件。signal 中止時，所有進行中的作業都會終止。

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

**options.structuredOutput** (`StructuredOutputOptions<S extends ZodTypeAny = ZodTypeAny>`): 啟用具備更佳開發體驗的結構化輸出生成。會在內部自動建立並使用 StructuredOutputProcessor。

**options.structuredOutput.schema** (`z.ZodSchema<S>`): 用來驗證輸出的 Zod schema。

**options.structuredOutput.model** (`MastraLanguageModel`): 內部結構化 Agent 要使用的模型。

**options.structuredOutput.errorStrategy** (`'strict' | 'warn' | 'fallback'`): 解析或驗證失敗時採用的策略。預設為 'strict'。

**options.structuredOutput.fallbackValue** (`<S extends ZodTypeAny>`): errorStrategy 為 'fallback' 時的 fallback 值。

**options.structuredOutput.instructions** (`string`): 結構化 Agent 的自訂指示。

**options.outputProcessors** (`Processor[]`): 覆寫 Agent 上設定的輸出 Processor。輸出 Processor 可在 Agent 訊息回傳給使用者前修改或驗證訊息。必須實作 processOutputResult 與 processOutputStream 函式其中之一或兩者。

**options.inputProcessors** (`Processor[]`): 覆寫 Agent 上設定的輸入 Processor。輸入 Processor 可在 Agent 處理訊息前修改或驗證訊息。必須實作 processInput 函式。

**options.experimental\_output** (`Zod schema | JsonSchema7`): 請注意，建議使用 structuredOutput 屬性。此屬性可在文字生成與 Tool 呼叫的同時啟用結構化輸出生成。模型會生成符合所提供 schema 的回應。

**options.instructions** (`string`): 覆寫 Agent 此次生成所用預設指示的自訂指示。可動態修改 Agent 行為，而不必建立新的 Agent 執行個體。

**options.output** (`Zod schema | JsonSchema7`): 定義預期的輸出結構。可以是 JSON Schema 物件或 Zod schema。

**options.memory** (`object`): 記憶體設定。這是管理記憶體的建議方式。

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

**options.memory.resource** (`string`): 與 thread 關聯之使用者或 resource 的識別碼。

**options.memory.options** (`MemoryConfig`): 記憶體行為設定，例如訊息歷程與語意回想。請參閱下方的 MemoryConfig。

**options.maxSteps** (`number`): 允許的執行步驟數上限。

**options.maxRetries** (`number`): 重試次數上限。設為 0 可停用重試。

**options.onStepFinish** (`GenerateTextOnStepFinishCallback<any> | never`): 每個執行步驟後呼叫的 callback 函式。以 JSON 字串接收步驟詳細資料。不適用於結構化輸出

**options.runId** (`string`): 此次生成 run 的唯一 ID，適合用於追蹤與偵錯。

**options.telemetry** (`TelemetrySettings`): 生成期間的 telemetry 收集設定。

**options.telemetry.isEnabled** (`boolean`): 啟用或停用 telemetry。此功能仍為實驗性質，因此預設停用。

**options.telemetry.recordInputs** (`boolean`): 啟用或停用輸入記錄。預設為啟用。若要避免記錄敏感資訊，您可以停用輸入記錄。

**options.telemetry.recordOutputs** (`boolean`): 啟用或停用輸出記錄。預設為啟用。若要避免記錄敏感資訊，您可以停用輸出記錄。

**options.telemetry.functionId** (`string`): 此函式的識別碼，用來依函式將 telemetry 資料分組。

**options.temperature** (`number`): 控制模型輸出的隨機程度。較高的值（例如 0.8）會讓輸出更隨機；較低的值（例如 0.2）會讓輸出更聚焦且具確定性。

**options.toolChoice** (`'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }`): 控制 Agent 在生成期間使用 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`): 生成期間額外提供給 Agent 的 toolset。

**options.clientTools** (`ToolsInput`): 在 request 的 'client' 端執行的 Tool。這些 Tool 的定義中沒有 execute 函式。

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

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

**options.providerOptions** (`Record<string, Record<string, JSONValue>>`): 傳遞給底層 LLM Provider 的其他 Provider 專屬選項。結構為 { providerName: { optionKey: value } }。由於 Mastra 擴充 AI SDK，完整的 Provider 選項請參閱 AI SDK 文件。

**options.providerOptions.openai** (`Record<string, JSONValue>`): OpenAI 專屬選項。例如： { reasoningEffort: 'high' }

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

**options.providerOptions.google** (`Record<string, JSONValue>`): Google 專屬選項。例如： { safetySettings: \[...] }

**options.providerOptions.\[providerName]** (`Record<string, JSONValue>`): 其他 Provider 專屬選項。key 是 Provider 名稱，value 是 Provider 專屬選項的記錄。

**options.requestContext** (`RequestContext`): 用於相依性注入與情境資訊的 Request Context。

**options.maxTokens** (`number`): 要生成的 token 數量上限。

**options.topP** (`number`): 核心取樣。此數值介於 0 與 1 之間。建議設定 temperature 或 topP，但不要同時設定兩者。

**options.topK** (`number`): 每個後續 token 只從機率最高的 K 個選項取樣，用來排除「長尾」低機率回應。

**options.presencePenalty** (`number`): 存在懲罰設定。會影響模型重複 prompt 中既有資訊的機率。數值介於 -1（增加重複）與 1（最大懲罰，減少重複）之間。

**options.frequencyPenalty** (`number`): 頻率懲罰設定。會影響模型重複使用相同字詞或片語的機率。數值介於 -1（增加重複）與 1（最大懲罰，減少重複）之間。

**options.stopSequences** (`string[]`): 停止序列。設定後，模型生成任一停止序列時會停止生成文字。

**options.seed** (`number`): 隨機取樣使用的 seed（整數）。設定此值且模型支援時，呼叫會生成確定性結果。

**options.headers** (`Record<string, string | undefined>`): 要與 request 一併傳送的其他 HTTP header。僅適用於以 HTTP 為基礎的 Provider。

## 回傳值

**text** (`string`): 生成的文字回應。輸出為 'text'（未提供 schema）時存在。

**object** (`object`): 生成的結構化回應。透過 output、structuredOutput 或 experimental\_output 提供 schema 時存在。

**toolCalls** (`Array<ToolCall>`): 生成流程期間進行的 Tool 呼叫。在文字與物件模式中都存在。

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

**toolCalls.args** (`any`): 傳給 Tool 的引數。

## 遷移至新 API

> **資訊:** 新的 `.generate()` 方法提供增強功能，包括 AI SDK v5+ 相容性、更完善的結構化輸出處理，以及改良的串流支援。詳細遷移指示請參閱[遷移指南](https://mastra.zisheng.pro/zh-TW/guides/migrations/vnext-to-standard-apis)。

### 快速遷移範例

#### 遷移前（舊版）

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

#### 遷移後（新 API）

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

## 延伸使用範例

```typescript
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 }),
    ],
  },
)
```

## 相關內容

- [遷移指南](https://mastra.zisheng.pro/zh-TW/guides/migrations/vnext-to-standard-apis)
- [新的 .generate() 方法](https://mastra.zisheng.pro/zh-TW/reference/agents/generate)
- [生成回應](https://mastra.zisheng.pro/zh-TW/docs/agents/overview)
- [串流回應](https://mastra.zisheng.pro/zh-TW/docs/agents/overview)