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

# Agent.streamLegacy()（舊版）

> **警告:** **已棄用**：此方法已棄用，且僅適用於 V1 模型。V2 模型請改用新的 [`.stream()`](https://mastra.zisheng.pro/zh-TW/reference/streaming/agents/stream) 方法。升級詳情請參閱[遷移指南](https://mastra.zisheng.pro/zh-TW/guides/migrations/vnext-to-standard-apis)。

`.streamLegacy()` 方法是舊版 Agent 串流 API，用於即時串流 V1 模型 Agent 的回應。此方法接受訊息與選用串流選項。

## 使用範例

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

## 參數

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

**options** (`AgentStreamOptions<OUTPUT, EXPERIMENTAL_OUTPUT>`): 串流流程的選用設定。

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

**options.context** (`CoreMessage[]`): 提供給 Agent 的額外上下文訊息。

**options.experimental\_output** (`Zod schema | JsonSchema7`): 啟用結構化輸出生成，並同時進行文字生成與 Tool 呼叫。模型會生成符合所提供 schema 的回應。

**options.instructions** (`string`): 針對這次生成覆寫 Agent 預設指示的自訂指示。適合用來動態調整 Agent 行為，而不必建立新的 Agent 執行個體。

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

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

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

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

**options.memory.options** (`MemoryConfig`): memory 行為的設定，例如訊息歷程與語意回憶。

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

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

**options.memoryOptions** (`MemoryConfig`): \*\*已棄用。\*\*請改用 memory.options。memory 管理的設定選項。

**options.memoryOptions.lastMessages** (`number | false`): 要納入上下文的近期訊息數量，設為 false 則停用。

**options.memoryOptions.semanticRecall** (`boolean | { topK: number; messageRange: number | { before: number; after: number }; scope?: 'thread' | 'resource' }`): 啟用語意回憶以尋找相關的過往訊息。可以使用布林值或詳細設定。

**options.memoryOptions.workingMemory** (`WorkingMemory`): working memory 功能的設定。

**options.memoryOptions.threads** (`{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }`): thread 專用設定，包含自動產生標題。

**options.onFinish** (`StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>`): 串流完成時呼叫的回呼函式。會接收最終結果。

**options.onStepFinish** (`StreamTextOnStepFinishCallback<any> | never`): 每個執行步驟完成後呼叫的回呼函式。會以 JSON 字串接收步驟詳細資訊。結構化輸出無法使用此函式

**options.resourceId** (`string`): \*\*已棄用。\*\*請改用 memory.resource。與 Agent 互動的使用者或資源識別碼。若提供 threadId，就必須提供此值。

**options.telemetry** (`TelemetrySettings`): 串流期間的遙測收集設定。

**options.telemetry.isEnabled** (`boolean`): 啟用或停用遙測。實驗階段預設為停用。

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

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

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

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

**options.threadId** (`string`): \*\*已棄用。\*\*請改用 memory.thread。對話 thread 的識別碼，可在多次互動間維持上下文。若提供 resourceId，就必須提供此值。

**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`): 在請求的「使用者端」執行的 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 } }。例如：{ openai: { reasoningEffort: 'high' }, anthropic: { maxTokens: 1000 } }。

**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 專用選項。鍵是 Provider 名稱，值則是 Provider 專用選項的記錄。

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

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

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

**options.topP** (`number`): 核取樣。此值介於 0 到 1 之間。建議只設定 temperature 或 topP 其中一項，不要同時設定。

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

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

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

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

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

**options.headers** (`Record<string, string | undefined>`): 要隨請求傳送的其他 HTTP 標頭。僅適用於以 HTTP 為基礎的 Provider。

## 回傳值

**textStream** (`AsyncGenerator<string>`): 文字 chunk 可用時逐一產出的非同步 generator。

**fullStream** (`Promise<ReadableStream>`): 解析為完整回應 ReadableStream 的 Promise。

**text** (`Promise<string>`): 解析為完整文字回應的 Promise。

**usage** (`Promise<{ totalTokens: number; promptTokens: number; completionTokens: number }>`): 解析為 token 用量資訊的 Promise。

**finishReason** (`Promise<string>`): 解析為串流完成原因的 Promise。

**toolCalls** (`Promise<Array<ToolCall>>`): 解析為串流處理期間所進行之 Tool 呼叫的 Promise。

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

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

## 進階使用範例

```typescript
await agent.streamLegacy('message for agent', {
  temperature: 0.7,
  maxSteps: 3,
  memory: {
    thread: 'user-123',
    resource: 'test-app',
  },
  toolChoice: 'auto',
})
```

## 遷移至新 API

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

### 快速遷移範例

#### 遷移前（舊版）

```typescript
const result = await agent.streamLegacy('message', {
  temperature: 0.7,
  maxSteps: 3,
  onFinish: result => console.log(result),
})
```

#### 遷移後（新 API）

```typescript
const result = await agent.stream('message', {
  modelSettings: {
    temperature: 0.7,
  },
  maxSteps: 3,
  onFinish: result => console.log(result),
})
```

## 相關內容

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