> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-HK/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 及加入 metadata 的 Tracing context。

**tracingContext.currentSpan** (`Span`): 用於建立子 span 及加入 metadata 的目前 span。

**tracingOptions** (`TracingOptions`): Tracing 配置選項。

**tracingOptions.metadata** (`Record<string, any>`): 要加入根 Trace span 的 metadata。

**tracingOptions.requestContextKeys** (`string[]`): 要擷取為此 Trace metadata 的額外 RequestContext key。支援以點號表示法存取巢狀值（例如 'user.id'）。

**tracingOptions.traceId** (`string`): 此執行所使用的 Trace ID（1 至 32 個十六進制字元）。如有提供，此 Trace 會成為指定 Trace 的一部分。

**tracingOptions.parentSpanId** (`string`): 此執行所使用的父 span ID（1 至 16 個十六進制字元）。如有提供，根 span 會建立為此 span 的子項。

**tracingOptions.tags** (`string[]`): 要套用至此 Trace 的標籤。這些字串標籤可用於分類及篩選 Trace。

**closeOnSuspend** (`boolean`): 是否在 Workflow 暫停時關閉串流，或讓串流保持開啟，直至 Workflow 成功完成或發生錯誤。預設值為 true。

## 傳回值

傳回實作非同步 iterable 介面的 `WorkflowRunOutput` 物件（可直接用於 `for await...of` 迴圈），並可存取串流及 Workflow 執行結果。

**fullStream** (`ReadableStream<WorkflowStreamEvent>`): Workflow 事件的 ReadableStream，可供反覆運算以即時追蹤進度。你亦可直接反覆運算 WorkflowRunOutput 物件。

**result** (`Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>`): 會解析為最終 Workflow 結果的 promise

**status** (`WorkflowRunStatus`): 目前的 Workflow run 狀態（'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)
```

## 串流事件

串流會在 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 的最終結果，串流使用者無需再擷取一次

## 相關內容

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