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

# MastraModelOutput

[.stream()](https://mastra.zisheng.pro/zh-HK/reference/streaming/agents/stream) 會傳回 `MastraModelOutput` 類別，讓你以串流及 Promise 方式存取模型輸出。它支援結構化輸出生成、Tool 呼叫、推理及詳細用量追蹤。

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

有關設定及基本用法，請參閱 [.stream()](https://mastra.zisheng.pro/zh-HK/reference/streaming/agents/stream) 方法文件。

## 串流屬性

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

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

**fullStream.ChunkType** (`ChunkType<OUTPUT>`): 串流期間可發出的所有分塊類型

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

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

**objectStream.PartialSchemaOutput** (`Partial<OUTPUT>`): 符合指定結構描述的部分完成物件

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

## 以 Promise 為基礎的屬性

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

**text** (`Promise<string>`): 模型傳回的完整串接文字回應。文字生成完成時解析。

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

**object.InferSchemaOutput** (`OUTPUT`): 完全符合指定結構描述定義的強類型物件

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

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

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

**toolCalls.type** (`'tool-call'`): 分塊類型識別碼

**toolCalls.runId** (`string`): 執行 run 識別碼

**toolCalls.from** (`ChunkFrom`): 分塊的來源（AGENT、WORKFLOW 等）

**toolCalls.payload** (`ToolCallPayload`): Tool 呼叫資料，包括 toolCallId、toolName、args 及執行詳情

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

**toolResults.type** (`'tool-result'`): 分塊類型識別碼

**toolResults.runId** (`string`): 執行 run 識別碼

**toolResults.from** (`ChunkFrom`): 分塊的來源（AGENT、WORKFLOW 等）

**toolResults.payload** (`ToolResultPayload`): Tool 結果資料，包括 toolCallId、toolName、result 及錯誤狀態

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

**usage.inputTokens** (`number`): 輸入提示所耗用的 token

**usage.outputTokens** (`number`): 回應中生成的 token

**usage.totalTokens** (`number`): 輸入與輸出 token 的總和

**usage.reasoningTokens** (`number`): 隱藏的推理 token（適用於推理模型）

**usage.cachedInputTokens** (`number`): 快取命中的輸入 token 數目

**finishReason** (`Promise<string | undefined>`): 生成停止的原因（例如 'stop'、'length'、'tool\_calls'、'content\_filter'）。如串流尚未完成，則為 undefined。

**finishReason.stop** (`'stop'`): 模型自然完成

**finishReason.length** (`'length'`): 達到 token 上限

**finishReason.tool\_calls** (`'tool_calls'`): 模型呼叫了 Tool

**finishReason.content\_filter** (`'content_filter'`): 內容已被過濾

**response** (`Promise<Response>`): 模型 Provider 的回應中繼資料及訊息。

**response.id** (`string`): 模型 Provider 傳回的回應 ID

**response.timestamp** (`Date`): 回應的時間戳記

**response.modelId** (`string`): 此回應所使用的模型識別碼

**response.headers** (`Record<string, string>`): 模型 Provider 傳回的回應標頭

**response.messages** (`ResponseMessage[]`): 採用模型格式的回應訊息

**response.uiMessages** (`UIMessage[]`): 採用 UI 格式的回應訊息，包括輸出處理器加入的任何中繼資料

## 錯誤屬性

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

## 方法

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

**getFullOutput.text** (`string`): 完整文字回應

**getFullOutput.object** (`OUTPUT`): 如有提供結構描述，則為結構化輸出

**getFullOutput.toolCalls** (`ToolCallChunk[]`): 所有已產生的 Tool 呼叫分塊

**getFullOutput.toolResults** (`ToolResultChunk[]`): 所有 Tool 結果分塊

**getFullOutput.usage** (`Record<string, number>`): Token 用量統計資料

**getFullOutput.reasoning** (`string`): 推理文字（如有）

**getFullOutput.finishReason** (`string`): 生成結束的原因

**getFullOutput.response** (`Response`): 模型 Provider 的回應中繼資料及訊息

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

**consumeStream.onError** (`(error: Error) => void`): 處理串流錯誤的回呼函式

## 使用範例

### 基本文字串流

```typescript
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)
```

### 結構化輸出串流

```typescript
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" }
```

````text
### 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

```typescript
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

```typescript
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

```typescript
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()](https://mastra.zisheng.pro/zh-HK/reference/streaming/agents/stream)：傳回 MastraModelOutput 的方法
- [ChunkType](https://mastra.zisheng.pro/zh-HK/reference/streaming/ChunkType)：完整串流中所有可能的分塊類型