> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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

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

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

**object** (`Partial<OUTPUT>`): 符合已定義 schema 的部分或完整結構化資料。型別由 OUTPUT schema 參數決定。

### tool-output

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

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

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

**payload.output** (`ChunkType`): 巢狀區塊資料，通常包含具有用量統計資料的 finish 事件

### step-output

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

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

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

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

## 背景任務區塊

將 Tool 呼叫分派為[背景任務](https://mastra.zisheng.pro/zh-TW/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-TW/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 回傳錯誤結果而非擲回例外，則為真

### background-task-failed

任務擲回例外或逾時時發出。由 [`Agent.streamUntilIdle()`](https://mastra.zisheng.pro/zh-TW/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-TW/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`，接著重新啟動 Tool 的 `execute`，並填入 `resumeData`。

**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-TW/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、timestamp、headers）

### watch

包含 Agent 執行的監控與可觀測性資料。依使用 `stream()` 的情境而定，可能包含 Workflow 狀態資訊、執行進度或其他執行階段詳細資訊。

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

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

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

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

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

### goal

每次評估 Agent 的[目標](https://mastra.zisheng.pro/zh-TW/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-TW/reference/streaming/agents/stream): 回傳會發出這些區塊之串流的方法
- [MastraModelOutput](https://mastra.zisheng.pro/zh-TW/reference/streaming/agents/MastraModelOutput): 會發出這些區塊的串流物件
- [workflow.stream()](https://mastra.zisheng.pro/zh-TW/reference/streaming/workflows/stream): 回傳會為 Workflow 發出這些區塊之串流的方法