跳至主要內容

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 執行的訊號物件。訊號中止後，所有進行中的操作都會終止。

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

thread:

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

resource:

string
與 thread 關聯的使用者或資源標識符。

options?:

MemoryConfig
記憶體行為的設定，例如訊息記錄及語意回憶。

maxSteps?:

number
允許的最大執行步驟數。

maxRetries?:

number
最大重試次數。設為 0 可停用重試。

memoryOptions?:

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

lastMessages?:

number | false
要加入內容脈絡的近期訊息數量；設為 false 可停用。

semanticRecall?:

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

workingMemory?:

WorkingMemory
工作記憶功能的設定。

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

hooks?:

ToolHooks
每次執行專用的 hook，會在 Tool 呼叫前後運行，並在這次執行中覆蓋相符的 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 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。

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