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

# Run.stream()

`.stream()` 方法支持从 Workflow 实时流式传输响应。它会直接返回事件的 `ReadableStream`。

## 用法示例

```typescript
const run = await workflow.createRun()

const stream = await run.stream({
  inputData: {
    value: 'initial data',
  },
})

for await (const chunk of stream) {
  console.log(chunk)
}
```

## 参数

**inputData** (`z.infer<TInput>`): 与 Workflow 输入 schema 匹配的输入数据

**requestContext** (`RequestContext`): Workflow 执行期间使用的 Request Context 数据

**tracingContext** (`TracingContext`): 用于创建子 span 和添加元数据的 Tracing 上下文。

**tracingContext.currentSpan** (`Span`): 用于创建子 span 和添加元数据的当前 span。

**tracingOptions** (`TracingOptions`): Tracing 配置选项。

**tracingOptions.metadata** (`Record<string, any>`): 要添加到根 Trace span 的元数据。

**tracingOptions.requestContextKeys** (`string[]`): 要作为此 Trace 的元数据提取的其他 RequestContext 键。支持使用点号表示法访问嵌套值（例如 'user.id'）。

**tracingOptions.traceId** (`string`): 本次执行使用的 Trace ID（1–32 个十六进制字符）。如果提供，该 Trace 将成为指定 Trace 的一部分。

**tracingOptions.parentSpanId** (`string`): 本次执行使用的父 span ID（1–16 个十六进制字符）。如果提供，将创建根 span 作为该 span 的子 span。

**tracingOptions.tags** (`string[]`): 要应用到此 Trace 的标签。用于对 Trace 进行分类和筛选的字符串标签。

**closeOnSuspend** (`boolean`): 是要在 Workflow 暂停时关闭 Stream，还是保持 Stream 打开直至 Workflow 完成（成功或出错）。默认值为 true。

## 返回值

返回一个实现异步可迭代接口（可直接用于 `for await...of` 循环）的 `WorkflowRunOutput` 对象，并可通过该对象访问 Stream 和 Workflow 执行结果。

**fullStream** (`ReadableStream<WorkflowStreamEvent>`): 可供迭代的 Workflow 事件 ReadableStream，用于实时跟踪进度。也可以直接迭代 WorkflowRunOutput 对象。

**result** (`Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>`): 解析为最终 Workflow 结果的 Promise

**status** (`WorkflowRunStatus`): 当前 Workflow 运行状态（'running'、'suspended'、'success'、'failed'、'canceled' 或 'tripwire'）

**usage** (`Promise<{ inputTokens: number; outputTokens: number; totalTokens: number, reasoningTokens?: number, cachedInputTokens?: number }>`): 解析为 token 用量统计信息的 Promise

## 扩展用法示例

```typescript
const run = await workflow.createRun()

const stream = run.stream({
  inputData: {
    value: 'initial data',
  },
})

// Iterate over stream events (you can iterate over stream directly or use stream.fullStream)
for await (const chunk of stream) {
  console.log(chunk)
}

// Access the final result
const result = await stream.result
console.log('Final result:', result)

// Access token usage
const usage = await stream.usage
console.log('Token usage:', usage)

// Check current status
console.log('Status:', stream.status)
```

## Stream 事件

Stream 会在 Workflow 执行期间发出不同类型的事件。每个事件都有一个 `type` 字段，以及一个包含相关数据的 `payload`：

- **`workflow-start`**：Workflow 开始执行
- **`workflow-step-start`**：步骤开始执行
- **`workflow-step-output`**：步骤的自定义输出
- **`workflow-step-progress`**：foreach 步骤报告每次迭代的进度（包括 `completedCount`、`totalCount`、`currentIndex`、`iterationStatus` 以及可选的 `iterationOutput`）
- **`workflow-step-result`**：步骤完成并产生结果
- **`workflow-finish`**：Workflow 执行完成，并附带用量统计信息。对于成功的运行，`payload.finalWorkflowResult` 包含 Workflow 的最终结果，因此 Stream 使用方无需后续获取

## 相关内容

- [Workflow 概览](https://mastra.zisheng.pro/docs/workflows/overview)
- [Workflow.createRun()](https://mastra.zisheng.pro/reference/workflows/workflow-methods/create-run)
- [Run.resumeStream()](https://mastra.zisheng.pro/reference/streaming/workflows/resumeStream)