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

# MastraModelOutput

[.stream()](https://mastra.zisheng.pro/reference/streaming/agents/stream) 会传回 `MastraModelOutput` 类别，让你以Stream及 Promise 方式访问模型输出。它支持结构化输出生成、Tool 调用、推理及详细用量追踪。

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

有关设定及基本用法，请参阅 [.stream()](https://mastra.zisheng.pro/reference/streaming/agents/stream) 方法文档。

## Stream属性

这些属性可在模型输出生成时即时访问：

**fullStream** (`ReadableStream<ChunkType<OUTPUT>>`): 包含文本、Tool 调用、推理、中继资料及控制chunk等所有chunk类型的完整Stream。可细致访问模型回应的每个部分。

**fullStream.ChunkType** (`ChunkType<OUTPUT>`): Stream期间可发出的所有chunk类型

**textStream** (`ReadableStream<string>`): 只包含逐步文本内容的Stream。它会滤除所有中继资料、Tool 调用及控制chunk，只提供正在生成的文本。

**objectStream** (`ReadableStream<Partial<OUTPUT>>`): 使用输出结构描述时，逐步更新结构化对象的Stream。对象创建期间会发出部分对象，以便即时显示结构化资料生成进度。

**objectStream.PartialSchemaOutput** (`Partial<OUTPUT>`): 符合指定结构描述的部分完成对象

**elementStream** (`ReadableStream<OUTPUT extends (infer T)[] ? T : never>`): 输出结构描述定义阵列类型时，逐一传送阵列元素的Stream。每个元素完成后便会发出，毋须等待整个阵列完成。

## 以 Promise 为基础的属性

Stream完成后，这些属性会解析为最终值：

**text** (`Promise<string>`): 模型传回的完整串接文本回应。文本生成完成时解析。

**object** (`Promise<OUTPUT>`): 使用输出结构描述时的完整结构化对象回应。解析前会按结构描述验证；验证失败时会拒绝。

**object.InferSchemaOutput** (`OUTPUT`): 完全符合指定结构描述定义的强类型对象

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

**reasoningText** (`Promise<string | undefined>`): 访问 reasoning 内容的另一种方式。对于不支持 reasoning 的模型，该值可能为 undefined，而 'reasoning' 会返回空字符串。

**toolCalls** (`Promise<ToolCallChunk[]>`): 执行期间所有 Tool 调用chunk的阵列。每个chunk均包含 Tool 中继资料及执行详情。

**toolCalls.type** (`'tool-call'`): chunk类型识别码

**toolCalls.runId** (`string`): 执行 run 识别码

**toolCalls.from** (`ChunkFrom`): 来源：chunk (AGENT, WORKFLOW, etc.)

**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, etc.)

**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'）。如果 Stream 尚未结束，则为 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[]`): 回应 messages in model format

**response.uiMessages** (`UIMessage[]`): 回应 messages in UI format, includes any 中继资料 added by 输出 processors

## 错误属性

**error** (`string | Error | { message: string; stack: string; } | undefined`): Stream遇到错误时的错误资料。如未发生错误则为 undefined。可以是字符串讯息、Error 对象，或包含堆叠追踪的串行化错误。

## 方法

**getFullOutput** (`() => Promise<FullOutput>`): 传回包含所有结果的完整输出对象：文本、结构化对象、Tool 调用、用量统计资料、推理及中继资料。只需一个方法即可方便地访问所有Stream结果。

**getFullOutput.text** (`string`): 完整text 回应

**getFullOutput.object** (`OUTPUT`): 如有提供结构描述，则为结构化输出

**getFullOutput.toolCalls** (`ToolCallChunk[]`): 所有已产生的 Tool 调用chunk

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

**getFullOutput.usage** (`Record<string, number>`): Token 用量统计资料

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

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

**getFullOutput.response** (`Response`): 模型 Provider 的回应中继资料及讯息

**consumeStream** (`(options?: ConsumeStreamOptions) => Promise<void>`): 手动取用整个Stream而不处理chunk。当你只需要最终 Promise 结果，并希望触发Stream取用时相当实用。

**consumeStream.onError** (`(error: Error) => void`): 处理Stream错误的回呼函数

## 使用范例

### 基本文本Stream

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

### 结构化输出Stream

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

### 访问完整输出

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

### 完整 Stream 处理

```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/reference/streaming/agents/stream)：传回 MastraModelOutput 的方法
- [ChunkType](https://mastra.zisheng.pro/reference/streaming/ChunkType)：完整Stream中所有可能的chunk类型