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

# ChunkType

`ChunkType` 類型定義 Agent 串流回應期間可發出的串流分塊 Mastra 格式。

## 基本屬性

所有分塊都包含以下基本屬性：

**type** (`string`): 特定分塊類型識別碼

**runId** (`string`): 此次執行的唯一識別碼

**from** (`ChunkFrom`): 分塊來源

**from.AGENT** (`'AGENT'`): 來自 Agent 執行的分塊

**from.USER** (`'USER'`): 來自使用者輸入的分塊

**from.SYSTEM** (`'SYSTEM'`): 來自系統程序的分塊

**from.WORKFLOW** (`'WORKFLOW'`): 來自 Workflow 執行的分塊

## 文字分塊

### text-start

表示文字生成開始。

**type** (`"text-start"`): 分塊類型識別碼

**payload** (`TextStartPayload`): 文字開始資料

**payload.id** (`string`): 此次文字生成的唯一識別碼

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

### text-delta

生成期間逐步產生的文字內容。

**type** (`"text-delta"`): 分塊類型識別碼

**payload** (`TextDeltaPayload`): 逐步產生的文字內容

**payload.id** (`string`): 此次文字生成的唯一識別碼

**payload.text** (`string`): 逐步產生的文字內容

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

### text-end

表示文字生成結束。

**type** (`"text-end"`): 分塊類型識別碼

**payload** (`TextEndPayload`): 文字結束資料

**payload.id** (`string`): 此次文字生成的唯一識別碼

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

## 推理分塊

### reasoning-start

表示推理生成開始（適用於支援推理的模型）。

**type** (`"reasoning-start"`): 分塊類型識別碼

**payload** (`ReasoningStartPayload`): 推理開始資料

**payload.id** (`string`): 此次推理生成的唯一識別碼

**payload.signature** (`string`): 推理簽署（如有）

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

### reasoning-delta

生成期間逐步產生的推理文字。

**type** (`"reasoning-delta"`): 分塊類型識別碼

**payload** (`ReasoningDeltaPayload`): 逐步產生的推理內容

**payload.id** (`string`): 此次推理生成的唯一識別碼

**payload.text** (`string`): 逐步產生的推理文字

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

### reasoning-end

表示推理生成結束。

**type** (`"reasoning-end"`): 分塊類型識別碼

**payload** (`ReasoningEndPayload`): 推理結束資料

**payload.id** (`string`): 此次推理生成的唯一識別碼

**payload.signature** (`string`): 最終推理簽署（如有）

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

### reasoning-signature

包含支援進階推理的模型（例如 OpenAI o1 系列）所產生的推理簽署。簽署代表模型內部推理過程的中繼資料，例如投入程度或推理方式，但不包含實際推理內容。

**type** (`"reasoning-signature"`): 分塊類型識別碼

**payload** (`ReasoningSignaturePayload`): 描述模型推理過程特徵的中繼資料

**payload.id** (`string`): 推理工作階段的唯一識別碼

**payload.signature** (`string`): 描述推理方式或投入程度的簽署（例如推理投入程度設定）

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

## Tool 分塊

### tool-call

正在呼叫 Tool。

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

**payload** (`ToolCallPayload`): Tool 呼叫資料

**payload.toolCallId** (`string`): 此次 Tool 呼叫的唯一識別碼

**payload.toolName** (`string`): 正在呼叫的 Tool 名稱

**payload.args** (`Record<string, any>`): 傳給 Tool 的引數

**payload.providerExecuted** (`boolean`): Provider 是否已執行 Tool

**payload.output** (`any`): Tool 輸出（如有）

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

### tool-result

Tool 執行結果。

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

**payload** (`ToolResultPayload`): Tool 執行結果

**payload.toolCallId** (`string`): Tool 呼叫的唯一識別碼

**payload.toolName** (`string`): 已執行的 Tool 名稱

**payload.result** (`any`): Tool 執行結果

**payload.isError** (`boolean`): 結果是否為錯誤

**payload.providerExecuted** (`boolean`): Provider 是否已執行 Tool

**payload.args** (`Record<string, any>`): 已傳給 Tool 的引數

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

### `tool-call-input-streaming-start`

表示開始以串流方式傳送 Tool 呼叫引數。

**type** (`"tool-call-input-streaming-start"`): 分塊類型識別碼

**payload** (`ToolCallInputStreamingStartPayload`): Tool 呼叫輸入串流開始資料

**payload.toolCallId** (`string`): 此次 Tool 呼叫的唯一識別碼

**payload.toolName** (`string`): 正在呼叫的 Tool 名稱

**payload.providerExecuted** (`boolean`): Provider 是否已執行 Tool

**payload.dynamic** (`boolean`): Tool 呼叫是否為動態

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

### `tool-call-delta`

串流期間逐步產生的 Tool 呼叫引數。

**type** (`"tool-call-delta"`): 分塊類型識別碼

**payload** (`ToolCallDeltaPayload`): 逐步產生的 Tool 呼叫引數

**payload.argsTextDelta** (`string`): Tool 引數的逐步文字差異

**payload.toolCallId** (`string`): 此次 Tool 呼叫的唯一識別碼

**payload.toolName** (`string`): 正在呼叫的 Tool 名稱

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

### `tool-call-input-streaming-end`

表示結束以串流方式傳送 Tool 呼叫引數。

**type** (`"tool-call-input-streaming-end"`): 分塊類型識別碼

**payload** (`ToolCallInputStreamingEndPayload`): Tool 呼叫輸入串流結束資料

**payload.toolCallId** (`string`): 此次 Tool 呼叫的唯一識別碼

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

### tool-error

執行 Tool 時發生錯誤。

**type** (`"tool-error"`): 分塊類型識別碼

**payload** (`ToolErrorPayload`): Tool 錯誤資料

**payload.id** (`string`): 可選識別碼

**payload.toolCallId** (`string`): Tool 呼叫的唯一識別碼

**payload.toolName** (`string`): 執行失敗的 Tool 名稱

**payload.args** (`Record<string, any>`): 已傳給 Tool 的引數

**payload.error** (`unknown`): 發生的錯誤

**payload.providerExecuted** (`boolean`): Provider 是否已執行 Tool

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

## 來源及檔案分塊

### source

包含內容的來源資料。

**type** (`"source"`): 分塊類型識別碼

**payload** (`SourcePayload`): 來源資料

**payload.id** (`string`): 唯一識別碼

**payload.sourceType** (`'url' | 'document'`): 來源類型

**payload.title** (`string`): 來源標題

**payload.mimeType** (`string`): 來源的 MIME 類型

**payload.filename** (`string`): 檔案名稱（如適用）

**payload.url** (`string`): URL（如適用）

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

### file

包含檔案資料。

**type** (`"file"`): 分塊類型識別碼

**payload** (`FilePayload`): 檔案資料

**payload.data** (`string | Uint8Array`): 檔案資料

**payload.base64** (`string`): Base64 編碼資料（如適用）

**payload.mimeType** (`string`): 檔案的 MIME 類型

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

## 控制分塊

### start

表示串流開始。

**type** (`"start"`): 分塊類型識別碼

**payload** (`StartPayload`): 開始資料

**payload.\[key: string]** (`any`): 其他開始資料

### step-start

表示處理步驟開始。

**type** (`"step-start"`): 分塊類型識別碼

**payload** (`StepStartPayload`): 步驟開始資料

**payload.messageId** (`string`): 可選訊息識別碼

**payload.request** (`object`): 請求資料，包括主體及其他資料

**payload.warnings** (`LanguageModelV2CallWarning[]`): 語言模型呼叫傳回的任何警告

### step-finish

表示處理步驟完成。

**type** (`"step-finish"`): 分塊類型識別碼

**payload** (`StepFinishPayload`): 步驟完成資料

**payload.id** (`string`): 可選識別碼

**payload.messageId** (`string`): 可選訊息識別碼

**payload.stepResult** (`object`): 步驟執行結果，包括原因、警告及延續資料

**payload.output** (`object`): 輸出資料，包括用量統計資料

**payload.metadata** (`object`): 執行中繼資料，包括請求及 Provider 資料

**payload.totalUsage** (`LanguageModelV2Usage`): 總用量統計資料

**payload.response** (`LanguageModelV2ResponseMetadata`): 回應中繼資料

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的中繼資料

### raw

包含 Provider 的原始資料。

**type** (`"raw"`): 分塊類型識別碼

**payload** (`RawPayload`): Provider 原始資料

**payload.\[key: string]** (`any`): 來自 Provider 的原始資料

### finish

串流已成功完成。

**type** (`"finish"`): 分塊類型識別碼

**payload** (`FinishPayload`): 完成資料

**payload.stepResult** (`object`): 步驟執行結果

**payload.output** (`object`): 輸出資料，包括用量資料

**payload.metadata** (`object`): 執行中繼資料

**payload.messages** (`object`): 訊息記錄

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

### error

串流期間發生錯誤。

**type** (`"error"`): 分塊類型識別碼

**payload** (`ErrorPayload`): 錯誤資料

**payload.error** (`unknown`): 發生的錯誤

### abort

串流已中止。

**type** (`"abort"`): 分塊類型識別碼

**payload** (`AbortPayload`): 中止資料

**payload.\[key: string]** (`any`): 其他中止資料

## 物件及輸出分塊

### object

使用已定義結構描述生成輸出時發出。包含符合指定 Zod 或 JSON 結構描述的部分或完整結構化資料。在部分執行情境中通常會略過此分塊；此分塊用於以串流方式生成結構化物件。

**type** (`"object"`): 分塊類型識別碼

**object** (`Partial<OUTPUT>`): 符合指定結構描述的部分或完整結構化資料。類型由 OUTPUT 結構描述參數決定。

### tool-output

包含 Agent 或 Workflow 執行輸出，尤其用於追蹤用量統計資料及完成事件。它通常會包裝其他分塊類型（例如 finish 分塊），以提供巢狀執行情境。

**type** (`"tool-output"`): 分塊類型識別碼

**payload** (`ToolOutputPayload`): 經包裝的執行輸出及中繼資料

**payload.output** (`ChunkType`): 巢狀分塊資料，通常包含完成事件及用量統計資料

### step-output

包含 Workflow 步驟執行輸出，主要用於追蹤用量及步驟完成事件。它與 tool-output 相似，但專門用於個別 Workflow 步驟。

**type** (`"step-output"`): 分塊類型識別碼

**payload** (`StepOutputPayload`): Workflow 步驟執行輸出及中繼資料

**payload.output** (`ChunkType`): 步驟執行的巢狀分塊資料，通常包含完成事件或其他步驟結果

## 背景任務分塊

當 Tool 呼叫以[背景任務](https://mastra.zisheng.pro/zh-HK/docs/long-running-agents/background-tasks)方式派送，並使用 `streamUntilIdle()` 時發出。

### background-task-started

當 Tool 呼叫排入背景任務佇列並獲指派 `taskId` 時發出。

**type** (`"background-task-started"`): 分塊類型識別碼

**payload** (`BackgroundTaskStartedPayload`): 識別新排入佇列的任務

**payload.taskId** (`string`): 背景任務的唯一識別碼

**payload.toolName** (`string`): 正在執行的 Tool 名稱

**payload.toolCallId** (`string`): 源自原始 LLM Tool 呼叫的 Tool 呼叫 ID

### background-task-running

當工作程序接手任務並開始執行時發出。

**type** (`"background-task-running"`): 分塊類型識別碼

**payload** (`BackgroundTaskRunningPayload`): 執行中任務的詳情

**payload.taskId** (`string`): 背景任務的唯一識別碼

**payload.toolName** (`string`): 正在執行的 Tool 名稱

**payload.toolCallId** (`string`): 源自原始 LLM Tool 呼叫的 Tool 呼叫 ID

**payload.runId** (`string`): 派送任務之 Agent 的執行 ID

**payload.agentId** (`string`): 派送任務之 Agent 的 ID

**payload.startedAt** (`Date`): 開始執行時的時間戳記

**payload.args** (`Record<string, unknown>`): 傳給 Tool execute 函式的引數

### background-task-progress

定期提供 Agent 中目前執行之背景任務數目的快照。

**type** (`"background-task-progress"`): 分塊類型識別碼

**payload** (`BackgroundTaskProgressPayload`): 所有執行中任務的整體進度

**payload.taskIds** (`string[]`): 所有目前執行中背景任務的 ID

**payload.runningCount** (`number`): 目前執行中的背景任務數目

**payload.elapsedMs** (`number`): Agent 開始執行後經過的毫秒數

### background-task-output

由任務的 `execute` 函數發出的串流輸出分塊，當中包裝了一個內部 [`tool-output`](#tool-output) 分塊。

**type** (`"background-task-output"`): 分塊類型識別碼

**payload** (`BackgroundTaskOutputPayload`): 執行中任務的串流輸出

**payload.taskId** (`string`): 背景任務的唯一識別碼

**payload.toolName** (`string`): 正在執行的 Tool 名稱

**payload.toolCallId** (`string`): 源自原始 LLM Tool 呼叫的 Tool 呼叫 ID

**payload.runId** (`string`): 派送任務之 Agent 的執行 ID

**payload.agentId** (`string`): 派送任務之 Agent 的 ID

**payload.payload** (`ToolOutputChunk`): 任務產生的內部 tool-output 分塊

### background-task-completed

任務成功完成時發出。由 [`Agent.streamUntilIdle()`](https://mastra.zisheng.pro/zh-HK/reference/streaming/agents/streamUntilIdle) 取用時會觸發延續回合。

**type** (`"background-task-completed"`): 分塊類型識別碼

**payload** (`BackgroundTaskResultPayload`): 已完成任務的結果

**payload.taskId** (`string`): 背景任務的唯一識別碼

**payload.toolName** (`string`): 已執行的 Tool 名稱

**payload.toolCallId** (`string`): 源自原始 LLM Tool 呼叫的 Tool 呼叫 ID

**payload.agentId** (`string`): 派送任務之 Agent 的 ID

**payload.runId** (`string`): 派送任務之 Agent 的執行 ID

**payload.result** (`unknown`): Tool 解析後的傳回值

**payload.completedAt** (`Date`): 任務完成時的時間戳記

**payload.isError** (`boolean`): Tool 傳回錯誤結果而非擲回例外時為 true

### background-task-failed

任務擲回例外或逾時時發出。由 [`Agent.streamUntilIdle()`](https://mastra.zisheng.pro/zh-HK/reference/streaming/agents/streamUntilIdle) 取用時會觸發延續回合。

**type** (`"background-task-failed"`): 分塊類型識別碼

**payload** (`BackgroundTaskFailedPayload`): 任務失敗詳情

**payload.taskId** (`string`): 背景任務的唯一識別碼

**payload.toolName** (`string`): 已執行的 Tool 名稱

**payload.toolCallId** (`string`): 源自原始 LLM Tool 呼叫的 Tool 呼叫 ID

**payload.runId** (`string`): 派送任務之 Agent 的執行 ID

**payload.agentId** (`string`): 派送任務之 Agent 的 ID

**payload.error** (`{ message: string }`): 任務擲回的錯誤詳情

**payload.completedAt** (`Date`): 任務失敗時的時間戳記

### background-task-suspended

當 Tool 在背景執行期間呼叫 `suspend()` 時發出。它會暫停任務的 Workflow 執行並保留快照。請使用 `mastra.backgroundTaskManager.resume(taskId, resumeData)` 恢復。

由 [`Agent.streamUntilIdle()`](https://mastra.zisheng.pro/zh-HK/reference/streaming/agents/streamUntilIdle) 取用時，此分塊會將任務從迴圈的等待集合移除，而不會排入延續操作。Agent 回應隨即結束；恢復後的任務最終完成時，結果會加入下一個使用者回合的訊息清單。

**type** (`"background-task-suspended"`): 分塊類型識別碼

**payload** (`BackgroundTaskSuspendedPayload`): 任務暫停詳情

**payload.taskId** (`string`): 背景任務的唯一識別碼

**payload.toolName** (`string`): 已執行的 Tool 名稱

**payload.toolCallId** (`string`): 源自原始 LLM Tool 呼叫的 Tool 呼叫 ID

**payload.runId** (`string`): 派送任務之 Agent 的執行 ID

**payload.agentId** (`string`): 派送任務之 Agent 的 ID

**payload.suspendData** (`unknown`): Tool 傳給 suspend(data) 的任何資料

### background-task-resumed

透過 `mastra.backgroundTaskManager.resume(taskId, resumeData)` 恢復已暫停的任務時發出。任務會轉回 `running`，並以已填入的 `resumeData` 重新啟動 Tool 的 `execute`。

**type** (`"background-task-resumed"`): 分塊類型識別碼

**payload** (`BackgroundTaskResumedPayload`): 任務恢復詳情

**payload.taskId** (`string`): 背景任務的唯一識別碼

**payload.toolName** (`string`): 已執行的 Tool 名稱

**payload.toolCallId** (`string`): 源自原始 LLM Tool 呼叫的 Tool 呼叫 ID

**payload.runId** (`string`): 派送任務之 Agent 的執行 ID

**payload.agentId** (`string`): 派送任務之 Agent 的 ID

**payload.startedAt** (`Date`): 任務恢復時的時間戳記

**payload.args** (`Record<string, unknown>`): 原始 Tool 引數

### background-task-cancelled

任務在完成前遭取消時發出。由 [`Agent.streamUntilIdle()`](https://mastra.zisheng.pro/zh-HK/reference/streaming/agents/streamUntilIdle) 取用時會觸發延續回合。

**type** (`"background-task-cancelled"`): 分塊類型識別碼

**payload** (`BackgroundTaskCancelledPayload`): 任務取消詳情

**payload.taskId** (`string`): 背景任務的唯一識別碼

**payload.toolName** (`string`): 已執行的 Tool 名稱

**payload.toolCallId** (`string`): 源自原始 LLM Tool 呼叫的 Tool 呼叫 ID

**payload.runId** (`string`): 派送任務之 Agent 的執行 ID

**payload.agentId** (`string`): 派送任務之 Agent 的 ID

**payload.completedAt** (`Date`): 任務取消時的時間戳記

## 中繼資料及特殊分塊

### response-metadata

包含 LLM Provider 回應的中繼資料。部分 Provider 會在文字生成後發出此分塊，以提供模型 ID、時間戳記及回應標頭等額外情境。此分塊在內部用於追蹤狀態，不會影響訊息組合。

**type** (`"response-metadata"`): 分塊類型識別碼

**payload** (`ResponseMetadataPayload`): 用於追蹤及偵錯的 Provider 回應中繼資料

**payload.signature** (`string`): 回應簽署（如有）

**payload.\[key: string]** (`any`): 其他 Provider 特定的中繼資料欄位（例如 id、modelId、時間戳記及標頭）

### watch

包含 Agent 執行的監察及可觀測性資料。視乎使用 `stream()` 的情境，可包括 Workflow 狀態資料、執行進度或其他執行階段詳情。

**type** (`"watch"`): 分塊類型識別碼

**payload** (`WatchPayload`): 用於 Agent 執行可觀測性及偵錯的監察資料

**payload.workflowState** (`object`): 目前的 Workflow 執行狀態（用於 Workflow 時）

**payload.eventTimestamp** (`number`): 事件發生時的時間戳記

**payload.\[key: string]** (`any`): 其他監察及執行資料

### goal

每次評估 Agent [goal](https://mastra.zisheng.pro/zh-HK/docs/long-running-agents/goals) 時發出。取用者會用它在執行期間呈現評審進度及結果。未設定評審模型的目標不會產生 `goal` 分塊。

**type** (`"goal"`): 分塊類型識別碼

**payload** (`GoalEvaluationPayload`): 一次目標評估的結果

**payload.objective** (`string`): 正在評審的目標

**payload.iteration** (`number`): 目前已耗用的目標評估次數（此次評估後的 runsUsed）

**payload.maxRuns** (`number`): 目標停止前的評估次數上限

**payload.passed** (`boolean`): 目標是否被判定為完成

**payload.status** (`"active" | "paused" | "done"`): 此次評估後的目標狀態

**payload.results** (`ScorerResult[]`): 個別評分器結果

**payload.reason** (`string`): 評審意見或停止原因

**payload.duration** (`number`): 目標評分檢查的總時長

**payload.timedOut** (`boolean`): 評分是否逾時

**payload.maxRunsReached** (`boolean`): 是否已達執行次數上限（maxRuns）

**payload.suppressFeedback** (`boolean`): 是否禁止將目標意見訊息寫入記憶體

### tripwire

當處理器封鎖內容而強制終止串流時發出。這是一項安全機制，可避免串流傳送有害或不當內容。酬載包含內容遭封鎖的原因，以及是否已要求重試。

**type** (`"tripwire"`): 分塊類型識別碼

**payload** (`TripwirePayload`): 串流因安全機制而終止的原因

**payload.reason** (`string`): 內容遭封鎖的原因說明（例如「輸出處理器封鎖了內容」）

**payload.retry** (`boolean`): 處理器是否要求重試此步驟

**payload.metadata** (`unknown`): 處理器提供的其他中繼資料（例如分數、類別）

**payload.processorId** (`string`): 觸發 tripwire 的處理器 ID

## 使用範例

```typescript
const stream = await agent.stream('Hello')

for await (const chunk of stream.fullStream) {
  switch (chunk.type) {
    case 'text-delta':
      console.log('Text:', chunk.payload.text)
      break

    case 'tool-call':
      console.log('Calling tool:', chunk.payload.toolName)
      break

    case 'tool-result':
      console.log('Tool result:', chunk.payload.result)
      break

    case 'reasoning-delta':
      console.log('Reasoning:', chunk.payload.text)
      break

    case 'finish':
      console.log('Finished:', chunk.payload.stepResult.reason)
      console.log('Usage:', chunk.payload.output.usage)
      break

    case 'error':
      console.error('Error:', chunk.payload.error)
      break
  }
}
```

## 相關類型

- [.stream()](https://mastra.zisheng.pro/zh-HK/reference/streaming/agents/stream)：傳回會發出這些分塊之串流的方法
- [MastraModelOutput](https://mastra.zisheng.pro/zh-HK/reference/streaming/agents/MastraModelOutput)：發出這些分塊的串流物件
- [workflow.stream()](https://mastra.zisheng.pro/zh-HK/reference/streaming/workflows/stream)：傳回會為 Workflow 發出這些分塊之串流的方法