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

# Agent.streamLegacy()（舊版）

> **注意:** **已棄用**：此方法已棄用，並且只適用於 V1 模型。V2 模型請改用新的 [`.stream()`](https://mastra.zisheng.pro/zh-HK/reference/streaming/agents/stream) 方法。升級詳情請參閱[遷移指南](https://mastra.zisheng.pro/zh-HK/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 執行的訊號物件。訊號中止後，所有進行中的操作都會終止。

**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`): 記憶體設定。這是管理記憶體的建議方式。

**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`): 記憶體行為的設定，例如訊息記錄及語意回憶。

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

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

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

**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`): 工作記憶功能的設定。

**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`): 在請求的 'client' 端執行的 Tool。這些 Tool 的定義不包含 execute 函式。

**options.hooks** (`ToolHooks`): 每次執行專用的 hook，會在 Tool 呼叫前後運行，並在這次執行中覆蓋相符的 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 header。只適用於以 HTTP 為基礎的 Provider。

## 傳回值

**textStream** (`AsyncGenerator<string>`): 非同步產生器，在文字區塊可用時逐一產生。

**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-HK/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-HK/guides/migrations/vnext-to-standard-apis)
- [新的 .stream() 方法](https://mastra.zisheng.pro/zh-HK/reference/streaming/agents/stream)
- [產生回應](https://mastra.zisheng.pro/zh-HK/docs/agents/overview)
- [串流回應](https://mastra.zisheng.pro/zh-HK/docs/agents/overview)