跳至主要內容

Agent.streamLegacy()（舊版）

警告

已棄用：此方法已棄用，且僅適用於 V1 模型。V2 模型請改用新的 .stream() 方法。升級詳情請參閱遷移指南。

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

使用範例
「使用範例」的直接連結

await agent.streamLegacy('message for agent')

參數
「參數」的直接連結

messages:

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

options?:

AgentStreamOptions<OUTPUT, EXPERIMENTAL_OUTPUT>
串流流程的選用設定。
AgentStreamOptions

abortSignal?:

AbortSignal
可讓你中止 Agent 執行的 signal 物件。signal 中止時，所有進行中的作業都會終止。

context?:

CoreMessage[]
提供給 Agent 的額外上下文訊息。

experimental_output?:

Zod schema | JsonSchema7
啟用結構化輸出生成，並同時進行文字生成與 Tool 呼叫。模型會生成符合所提供 schema 的回應。

instructions?:

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

output?:

Zod schema | JsonSchema7
定義預期的輸出結構。可以是 JSON Schema 物件或 Zod schema。

memory?:

object
memory 的設定。這是管理 memory 的建議方式。

thread:

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

resource:

string
與 thread 關聯的使用者或資源識別碼。

options?:

MemoryConfig
memory 行為的設定，例如訊息歷程與語意回憶。

maxSteps?:

number
允許的執行步驟數上限。

maxRetries?:

number
重試次數上限。設為 0 可停用重試。

memoryOptions?:

MemoryConfig
**已棄用。**請改用 memory.options。memory 管理的設定選項。

lastMessages?:

number | false
要納入上下文的近期訊息數量，設為 false 則停用。

semanticRecall?:

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

workingMemory?:

WorkingMemory
working memory 功能的設定。

threads?:

{ generateTitle?: boolean | { model: DynamicArgument<MastraLanguageModel>; instructions?: DynamicArgument<string> } }
thread 專用設定，包含自動產生標題。

onFinish?:

StreamTextOnFinishCallback<any> | StreamObjectOnFinishCallback<OUTPUT>
串流完成時呼叫的回呼函式。會接收最終結果。

onStepFinish?:

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

resourceId?:

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

telemetry?:

TelemetrySettings
串流期間的遙測收集設定。

isEnabled?:

boolean
啟用或停用遙測。實驗階段預設為停用。

recordInputs?:

boolean
啟用或停用輸入記錄。預設為啟用。為避免記錄敏感資訊，你可能需要停用輸入記錄。

recordOutputs?:

boolean
啟用或停用輸出記錄。預設為啟用。為避免記錄敏感資訊，你可能需要停用輸出記錄。

functionId?:

string
此函式的識別碼。用於依函式將遙測資料分組。

temperature?:

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

threadId?:

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

toolChoice?:

'auto' | 'none' | 'required' | { type: 'tool'; toolName: string }
控制 Agent 在串流期間如何使用 Tool。

'auto':

string
讓模型決定是否使用 Tool（預設）。

'none':

string
不使用任何 Tool。

'required':

string
要求模型至少使用一個 Tool。

{ type: 'tool'; toolName: string }:

object
要求模型依名稱使用特定 Tool。

toolsets?:

ToolsetsInput
讓 Agent 在串流期間可使用的其他 Toolset。

clientTools?:

ToolsInput
在請求的「使用者端」執行的 Tool。這些 Tool 的定義中沒有 execute 函式。

hooks?:

ToolHooks
每次執行專用、會在 Tool 呼叫前後執行的 hook。會覆寫這次執行中相符的 Agent 層級 hook。beforeToolCall 可以回傳 { proceed: false, output } 以略過 Tool 呼叫。

savePerStep?:

boolean
每個串流步驟完成後逐步儲存訊息（預設：false）。

providerOptions?:

Record<string, Record<string, JSONValue>>
傳遞至底層 LLM Provider 的其他 Provider 專用選項。結構為 { providerName: { optionKey: value } }。例如：{ openai: { reasoningEffort: 'high' }, anthropic: { maxTokens: 1000 } }。

openai?:

Record<string, JSONValue>
OpenAI 專用選項。例如：{ reasoningEffort: 'high' }

anthropic?:

Record<string, JSONValue>
Anthropic 專用選項。例如：{ maxTokens: 1000 }

google?:

Record<string, JSONValue>
Google 專用選項。例如：{ safetySettings: [...] }

[providerName]?:

Record<string, JSONValue>
其他 Provider 專用選項。鍵是 Provider 名稱，值則是 Provider 專用選項的記錄。

runId?:

string
這次生成執行的唯一 ID，適合用於追蹤與偵錯。

requestContext?:

RequestContext
用於相依性注入與上下文資訊的 Request Context。

maxTokens?:

number
要生成的 token 數量上限。

topP?:

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

topK?:

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

presencePenalty?:

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

frequencyPenalty?:

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

stopSequences?:

string[]
停止序列。設定後，模型生成任一停止序列時便會停止生成文字。

seed?:

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

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。

toolName:

string
所叫用 Tool 的名稱。

args:

any
傳給 Tool 的引數。

進階使用範例
「進階使用範例」的直接連結

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

遷移至新 API
「遷移至新 API」的直接連結

資訊

新的 .stream() 方法提供更多功能，包含 AI SDK v5+ 相容性、更完善的結構化輸出處理，以及改良的回呼系統。詳細遷移指示請參閱遷移指南。

快速遷移範例
「快速遷移範例」的直接連結

遷移前（舊版）
「遷移前（舊版）」的直接連結

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

遷移後（新 API）
「遷移後（新 API）」的直接連結

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