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

# MastraModelOutput

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

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

如需設定與基本用法，請參閱 [.stream()](https://mastra.zisheng.pro/zh-TW/reference/streaming/agents/stream) 方法文件。

## 串流屬性

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

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

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

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

**objectStream** (`ReadableStream<Partial<OUTPUT>>`): 使用輸出 schema 時，逐步更新結構化物件的串流。它會在建構過程中發出部分物件，讓你即時呈現結構化資料的生成進度。

**objectStream.PartialSchemaOutput** (`Partial<OUTPUT>`): 符合所定義 schema 的部分完成物件

**elementStream** (`ReadableStream<OUTPUT extends (infer T)[] ? T : never>`): 輸出 schema 定義為陣列類型時，個別陣列元素的串流。每個元素完成後就會發出，不必等待整個陣列完成。

## Promise 型屬性

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

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

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

**object.InferSchemaOutput** (`OUTPUT`): 與 schema 定義完全相符的完整型別物件

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

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

**toolCalls** (`Promise<ToolCallChunk[]>`): 執行期間產生的所有 Tool 呼叫 chunk 陣列。每個 chunk 都包含 Tool 中繼資料與執行詳細資訊。

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

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

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

**toolCalls.payload** (`ToolCallPayload`): Tool 呼叫資料，包含 toolCallId、toolName、args 與執行詳細資訊

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

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

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

**toolResults.from** (`ChunkFrom`): chunk 的來源（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 格式的回應訊息，包含輸出 processor 加入的任何中繼資料

## 錯誤屬性

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

## 方法

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

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

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

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

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

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

**getFullOutput.reasoning** (`string`): 可用的推理文字

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

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

**consumeStream** (`(options?: ConsumeStreamOptions) => Promise<void>`): 手動取用整個串流，但不處理 chunk。適合只需要最終 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,
})
```

### 完整串流處理

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

### 錯誤處理

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