跳至主要內容

MastraModelOutput

.stream() 會傳回 MastraModelOutput 類別，讓你以串流及 Promise 方式存取模型輸出。它支援結構化輸出生成、Tool 呼叫、推理及詳細用量追蹤。

// MastraModelOutput is returned by agent.stream()
const stream = await agent.stream('Hello world')

有關設定及基本用法，請參閱 .stream() 方法文件。

串流屬性
串流屬性 的直接連結

這些屬性可在模型輸出生成時即時存取：

fullStream:

ReadableStream<ChunkType<OUTPUT>>
包含文字、Tool 呼叫、推理、中繼資料及控制分塊等所有分塊類型的完整串流。可細緻存取模型回應的每個部分。
ReadableStream

ChunkType:

ChunkType<OUTPUT>
串流期間可發出的所有分塊類型

textStream:

ReadableStream<string>
只包含逐步文字內容的串流。它會濾除所有中繼資料、Tool 呼叫及控制分塊，只提供正在生成的文字。

objectStream:

ReadableStream<Partial<OUTPUT>>
使用輸出結構描述時，逐步更新結構化物件的串流。物件建立期間會發出部分物件，以便即時顯示結構化資料生成進度。
ReadableStream

PartialSchemaOutput:

Partial<OUTPUT>
符合指定結構描述的部分完成物件

elementStream:

ReadableStream<OUTPUT extends (infer T)[] ? T : never>
輸出結構描述定義陣列類型時，逐一傳送陣列元素的串流。每個元素完成後便會發出，毋須等待整個陣列完成。

以 Promise 為基礎的屬性
以 Promise 為基礎的屬性 的直接連結

串流完成後，這些屬性會解析為最終值：

text:

Promise<string>
模型傳回的完整串接文字回應。文字生成完成時解析。

object:

Promise<OUTPUT>
使用輸出結構描述時的完整結構化物件回應。解析前會按結構描述驗證；驗證失敗時會拒絕。
Promise

InferSchemaOutput:

OUTPUT
完全符合指定結構描述定義的強類型物件

reasoning:

Promise<string>
支援推理之模型（例如 OpenAI o1 系列）的完整推理文字。不具推理能力的模型會傳回空字串。

reasoningText:

Promise<string | undefined>
另一種存取推理內容的方式。不支援推理的模型可能會傳回 undefined，而 'reasoning' 則會傳回空字串。

toolCalls:

Promise<ToolCallChunk[]>
執行期間所有 Tool 呼叫分塊的陣列。每個分塊均包含 Tool 中繼資料及執行詳情。
ToolCallChunk

type:

'tool-call'
分塊類型識別碼

runId:

string
執行 run 識別碼

from:

ChunkFrom
分塊的來源（AGENT、WORKFLOW 等）

payload:

ToolCallPayload
Tool 呼叫資料，包括 toolCallId、toolName、args 及執行詳情

toolResults:

Promise<ToolResultChunk[]>
與 Tool 呼叫對應之所有 Tool 結果分塊的陣列。包含執行結果及錯誤資料。
ToolResultChunk

type:

'tool-result'
分塊類型識別碼

runId:

string
執行 run 識別碼

from:

ChunkFrom
分塊的來源（AGENT、WORKFLOW 等）

payload:

ToolResultPayload
Tool 結果資料，包括 toolCallId、toolName、result 及錯誤狀態

usage:

Promise<LanguageModelUsage>
Token 用量統計資料，包括輸入 token、輸出 token、token 總數及推理 token（適用於推理模型）。
Record

inputTokens:

number
輸入提示所耗用的 token

outputTokens:

number
回應中生成的 token

totalTokens:

number
輸入與輸出 token 的總和

reasoningTokens?:

number
隱藏的推理 token（適用於推理模型）

cachedInputTokens?:

number
快取命中的輸入 token 數目

finishReason:

Promise<string | undefined>
生成停止的原因（例如 'stop'、'length'、'tool_calls'、'content_filter'）。如串流尚未完成，則為 undefined。
enum

stop:

'stop'
模型自然完成

length:

'length'
達到 token 上限

tool_calls:

'tool_calls'
模型呼叫了 Tool

content_filter:

'content_filter'
內容已被過濾

response:

Promise<Response>
模型 Provider 的回應中繼資料及訊息。
Response

id?:

string
模型 Provider 傳回的回應 ID

timestamp?:

Date
回應的時間戳記

modelId?:

string
此回應所使用的模型識別碼

headers?:

Record<string, string>
模型 Provider 傳回的回應標頭

messages?:

ResponseMessage[]
採用模型格式的回應訊息

uiMessages?:

UIMessage[]
採用 UI 格式的回應訊息，包括輸出處理器加入的任何中繼資料

錯誤屬性
錯誤屬性 的直接連結

error:

string | Error | { message: string; stack: string; } | undefined
串流遇到錯誤時的錯誤資料。如未發生錯誤則為 undefined。可以是字串訊息、Error 物件，或包含堆疊追蹤的序列化錯誤。

方法
方法 的直接連結

getFullOutput:

() => Promise<FullOutput>
傳回包含所有結果的完整輸出物件：文字、結構化物件、Tool 呼叫、用量統計資料、推理及中繼資料。只需一個方法即可方便地存取所有串流結果。
FullOutput

text:

string
完整文字回應

object?:

OUTPUT
如有提供結構描述，則為結構化輸出

toolCalls:

ToolCallChunk[]
所有已產生的 Tool 呼叫分塊

toolResults:

ToolResultChunk[]
所有 Tool 結果分塊

usage:

Record<string, number>
Token 用量統計資料

reasoning?:

string
推理文字（如有）

finishReason?:

string
生成結束的原因

response:

Response
模型 Provider 的回應中繼資料及訊息

consumeStream:

(options?: ConsumeStreamOptions) => Promise<void>
手動取用整個串流而不處理分塊。當你只需要最終 Promise 結果，並希望觸發串流取用時相當實用。
ConsumeStreamOptions

onError?:

(error: Error) => void
處理串流錯誤的回呼函式

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

基本文字串流
基本文字串流 的直接連結

const stream = await agent.stream('Write a haiku')

// Stream text as it's generated
for await (const text of stream.textStream) {
  process.stdout.write(text)
}

// Or get the complete text
const fullText = await stream.text
console.log(fullText)

結構化輸出串流
結構化輸出串流 的直接連結

const stream = await agent.stream('Generate user data', {
  structuredOutput: {
    schema: z.object({
      name: z.string(),
      age: z.number(),
      email: z.string(),
    }),
  },
})

// Stream partial objects
for await (const partial of stream.objectStream) {
  console.log('Progress:', partial) // { name: "John" }, { name: "John", age: 30 }, ...
}

// Get final validated object
const user = await stream.object
console.log('Final:', user) // { name: "John", age: 30, email: "john@example.com" }

### Tool Calls and Results

```typescript
const stream = await agent.stream("What's the weather in NYC?", {
  tools: { weather: weatherTool }
});

// Monitor tool calls
const toolCalls = await stream.toolCalls;
const toolResults = await stream.toolResults;

console.log("Tools called:", toolCalls);
console.log("Results:", toolResults);

Complete Output Access
Complete Output Access 的直接連結

const stream = await agent.stream('Analyze this data')

const output = await stream.getFullOutput()
console.log({
  text: output.text,
  usage: output.usage,
  reasoning: output.reasoning,
  finishReason: output.finishReason,
})

Full Stream Processing
Full Stream Processing 的直接連結

const stream = await agent.stream('Complex task')

for await (const chunk of stream.fullStream) {
  switch (chunk.type) {
    case 'text-delta':
      process.stdout.write(chunk.payload.text)
      break
    case 'tool-call':
      console.log(`Calling ${chunk.payload.toolName}...`)
      break
    case 'reasoning-delta':
      console.log(`Reasoning: ${chunk.payload.text}`)
      break
    case 'finish':
      console.log(`Done! Reason: ${chunk.payload.stepResult.reason}`)
      // Access response messages with any metadata added by output processors
      const uiMessages = chunk.payload.response?.uiMessages
      if (uiMessages) {
        console.log('Response messages:', uiMessages)
      }
      break
  }
}

Error handling
Error handling 的直接連結

const stream = await agent.stream('Analyze this data')

try {
  // Option 1: Handle errors in consumeStream
  await stream.consumeStream({
    onError: error => {
      console.error('Stream error:', error)
    },
  })

  const result = await stream.text
} catch (error) {
  console.error('Failed to get result:', error)
}

// Option 2: Check error property
const result = await stream.getFullOutput()
if (stream.error) {
  console.error('Stream had errors:', stream.error)
}
  • .stream()：傳回 MastraModelOutput 的方法
  • ChunkType：完整串流中所有可能的分塊類型
On this page