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

# ChunkType

`ChunkType` 类型定义 Agent 在 Stream 响应期间可发出的 Mastra Chunk 格式。

## 基本属性

所有 Chunk 都包含以下基本属性：

**type** (`string`): 特定Chunk类型标识符

**runId** (`string`): 此次执行的唯一标识符

**from** (`ChunkFrom`): Chunk来源

**from.AGENT** (`'AGENT'`): 来自 Agent 执行的Chunk

**from.USER** (`'USER'`): 来自用户输入的Chunk

**from.SYSTEM** (`'SYSTEM'`): 来自系统进程的Chunk

**from.WORKFLOW** (`'WORKFLOW'`): 来自 Workflow 执行的Chunk

## 文本Chunk

### text-start

表示文本生成开始。

**type** (`"text-start"`): Chunk类型标识符

**payload** (`TextStartPayload`): 文本开始数据

**payload.id** (`string`): 此次文本生成的唯一标识符

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的元数据

### text-delta

生成期间逐步产生的文本内容。

**type** (`"text-delta"`): Chunk类型标识符

**payload** (`TextDeltaPayload`): 逐步产生的文本内容

**payload.id** (`string`): 此次文本生成的唯一标识符

**payload.text** (`string`): 逐步产生的文本内容

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的元数据

### text-end

表示文本生成结束。

**type** (`"text-end"`): Chunk类型标识符

**payload** (`TextEndPayload`): 文本结束数据

**payload.id** (`string`): 此次文本生成的唯一标识符

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的元数据

## 推理Chunk

### reasoning-start

表示推理生成开始（适用于支持推理的模型）。

**type** (`"reasoning-start"`): Chunk类型标识符

**payload** (`ReasoningStartPayload`): 推理开始数据

**payload.id** (`string`): 此次推理生成的唯一标识符

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

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的元数据

### reasoning-delta

生成期间逐步产生的推理文本。

**type** (`"reasoning-delta"`): Chunk类型标识符

**payload** (`ReasoningDeltaPayload`): 逐步产生的推理内容

**payload.id** (`string`): 此次推理生成的唯一标识符

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

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的元数据

### reasoning-end

表示推理生成结束。

**type** (`"reasoning-end"`): Chunk类型标识符

**payload** (`ReasoningEndPayload`): 推理结束数据

**payload.id** (`string`): 此次推理生成的唯一标识符

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

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的元数据

### reasoning-signature

包含支持进阶推理的模型（例如 OpenAI o1 系列）所产生的推理签署。签署代表模型内部推理过程的元数据，例如投入程度或推理方式，但不包含实际推理内容。

**type** (`"reasoning-signature"`): Chunk类型标识符

**payload** (`ReasoningSignaturePayload`): 描述模型推理过程特征的元数据

**payload.id** (`string`): 推理工作阶段的唯一标识符

**payload.signature** (`string`): 描述 reasoning 方法或投入级别的 signature（例如 reasoning effort 设置）

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的元数据

## Tool Chunk

### tool-call

正在调用 Tool。

**type** (`"tool-call"`): Chunk类型标识符

**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"`): Chunk类型标识符

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

表示开始以Stream方式传送 Tool 调用参数。

**type** (`"tool-call-input-streaming-start"`): Chunk类型标识符

**payload** (`ToolCallInputStreamingStartPayload`): Tool 调用输入Stream开始数据

**payload.toolCallId** (`string`): 此次 Tool 调用的唯一标识符

**payload.toolName** (`string`): 正在调用的 Tool 名称

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

**payload.dynamic** (`boolean`): Tool 调用是否为动态

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的元数据

### `tool-call-delta`

Stream期间逐步产生的 Tool 调用参数。

**type** (`"tool-call-delta"`): Chunk类型标识符

**payload** (`ToolCallDeltaPayload`): 逐步产生的 Tool 调用参数

**payload.argsTextDelta** (`string`): Tool 参数的逐步文本差异

**payload.toolCallId** (`string`): 此次 Tool 调用的唯一标识符

**payload.toolName** (`string`): 正在调用的 Tool 名称

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的元数据

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

表示结束以Stream方式传送 Tool 调用参数。

**type** (`"tool-call-input-streaming-end"`): Chunk类型标识符

**payload** (`ToolCallInputStreamingEndPayload`): Tool 调用输入Stream结束数据

**payload.toolCallId** (`string`): 此次 Tool 调用的唯一标识符

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的元数据

### tool-error

执行 Tool 时发生错误。

**type** (`"tool-error"`): Chunk类型标识符

**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 特定的元数据

## 来源及文档Chunk

### source

包含内容的来源数据。

**type** (`"source"`): Chunk类型标识符

**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"`): Chunk类型标识符

**payload** (`FilePayload`): 文档数据

**payload.data** (`string | Uint8Array`): 文档数据

**payload.base64** (`string`): Base64 编码数据（如适用）

**payload.mimeType** (`string`): 文档的 MIME 类型

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider 特定的元数据

## 控制Chunk

### start

表示Stream开始。

**type** (`"start"`): Chunk类型标识符

**payload** (`StartPayload`): 开始数据

**payload.\[key: string]** (`any`): 其他开始数据

### step-start

表示处理步骤开始。

**type** (`"step-start"`): Chunk类型标识符

**payload** (`StepStartPayload`): 步骤开始数据

**payload.messageId** (`string`): 可选消息标识符

**payload.request** (`object`): 请求数据，包括主体及其他数据

**payload.warnings** (`LanguageModelV2CallWarning[]`): 语言模型调用传回的任何警告

### step-finish

表示处理步骤完成。

**type** (`"step-finish"`): Chunk类型标识符

**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"`): Chunk类型标识符

**payload** (`RawPayload`): Provider 原始数据

**payload.\[key: string]** (`any`): 来自 Provider 的原始数据

### finish

Stream已成功完成。

**type** (`"finish"`): Chunk类型标识符

**payload** (`FinishPayload`): 完成数据

**payload.stepResult** (`object`): 步骤执行结果

**payload.output** (`object`): 输出数据，包括用量信息

**payload.metadata** (`object`): 执行元数据

**payload.messages** (`object`): 消息记录

**payload.response** (`object`): 模型 Provider 的回应元数据及消息

### error

Stream期间发生错误。

**type** (`"error"`): Chunk类型标识符

**payload** (`ErrorPayload`): 错误数据

**payload.error** (`unknown`): 发生的错误

### abort

Stream已中止。

**type** (`"abort"`): Chunk类型标识符

**payload** (`AbortPayload`): 中止数据

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

## 对象及输出Chunk

### object

使用已定义结构描述生成输出时发出。包含符合指定 Zod 或 JSON 结构描述的部分或完整结构化数据。在部分执行上下文中通常会略过此Chunk；此Chunk用于以Stream方式生成结构化对象。

**type** (`"object"`): Chunk类型标识符

**object** (`Partial<OUTPUT>`): 符合指定结构描述的部分或完整结构化数据。类型由 OUTPUT 结构描述参数决定。

### tool-output

包含 Agent 或 Workflow 执行输出，尤其用于追踪用量统计数据及完成事件。它通常会包装其他Chunk类型（例如 finish Chunk），以提供嵌套执行上下文。

**type** (`"tool-output"`): Chunk类型标识符

**payload** (`ToolOutputPayload`): 经包装的执行输出及元数据

**payload.output** (`ChunkType`): 嵌套Chunk数据，通常包含完成事件及用量统计数据

### step-output

包含 Workflow 步骤执行输出，主要用于追踪用量及步骤完成事件。它与 tool-output 相似，但专门用于个别 Workflow 步骤。

**type** (`"step-output"`): Chunk类型标识符

**payload** (`StepOutputPayload`): Workflow 步骤执行输出及元数据

**payload.output** (`ChunkType`): 步骤执行的嵌套Chunk数据，通常包含完成事件或其他步骤结果

## 背景任务Chunk

当 Tool 调用以[背景任务](https://mastra.zisheng.pro/docs/long-running-agents/background-tasks)方式派送，并使用 `streamUntilIdle()` 时发出。

### background-task-started

当 Tool 调用排入背景任务队列并获指派 `taskId` 时发出。

**type** (`"background-task-started"`): Chunk类型标识符

**payload** (`BackgroundTaskStartedPayload`): 识别新排入队列的任务

**payload.taskId** (`string`): 背景任务的唯一标识符

**payload.toolName** (`string`): 正在执行的 Tool 名称

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

### background-task-running

当 worker 接手任务并开始执行时发出。

**type** (`"background-task-running"`): Chunk类型标识符

**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"`): Chunk类型标识符

**payload** (`BackgroundTaskProgressPayload`): 所有执行中任务的整体进度

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

**payload.runningCount** (`number`): 当前正在运行的后台任务数量

**payload.elapsedMs** (`number`): Agent 开始执行后经过的毫秒数

### background-task-output

由任务的 `execute` 函数发出的Stream输出 chunk，包装了一个内部 [`tool-output`](#tool-output) chunk。

**type** (`"background-task-output"`): Chunk类型标识符

**payload** (`BackgroundTaskOutputPayload`): 执行中任务的Stream输出

**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 Chunk

### background-task-completed

任务成功完成时发出。由 [`Agent.streamUntilIdle()`](https://mastra.zisheng.pro/reference/streaming/agents/streamUntilIdle) 取用时会触发延续回合。

**type** (`"background-task-completed"`): Chunk类型标识符

**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/reference/streaming/agents/streamUntilIdle) 取用时会触发延续回合。

**type** (`"background-task-failed"`): Chunk类型标识符

**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/reference/streaming/agents/streamUntilIdle) 取用时，此Chunk会将任务从循圈的等待集合移除，而不会排入延续操作。Agent 回应随即结束；恢复后的任务最终完成时，结果会加入下一个用户回合的消息清单。

**type** (`"background-task-suspended"`): Chunk类型标识符

**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"`): Chunk类型标识符

**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/reference/streaming/agents/streamUntilIdle) 取用时会触发延续回合。

**type** (`"background-task-cancelled"`): Chunk类型标识符

**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`): 任务取消时的时间戳记

## 元数据及特殊Chunk

### response-metadata

包含 LLM Provider 回应的元数据。部分 Provider 会在文本生成后发出此Chunk，以提供模型 ID、时间戳记及回应标头等额外上下文。此Chunk在内部用于追踪状态，不会影响消息组合。

**type** (`"response-metadata"`): Chunk类型标识符

**payload** (`ResponseMetadataPayload`): 用于追踪及侦错的 Provider 回应元数据

**payload.signature** (`string`): 回应 signature（如有）

**payload.\[key: string]** (`any`): 其他 Provider 特定的元数据字段（例如 id、modelId、时间戳和 headers）

### watch

包含 Agent 执行的监察及可观测性数据。视乎使用 `stream()` 的上下文，可包括 Workflow 状态数据、执行进度或其他执行阶段详情。

**type** (`"watch"`): Chunk类型标识符

**payload** (`WatchPayload`): 用于 Agent 执行可观测性及侦错的监察数据

**payload.workflowState** (`object`): 当前 Workflow 的执行状态（用于 Workflow 时）

**payload.eventTimestamp** (`number`): 事件发生时的时间戳记

**payload.\[key: string]** (`any`): 其他监察及执行数据

### goal

每次评估 Agent [goal](https://mastra.zisheng.pro/docs/long-running-agents/goals) 时发出。取用者会用它在执行期间呈现评审进度及结果。未设定评审模型的目标不会产生 `goal` Chunk。

**type** (`"goal"`): Chunk类型标识符

**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

当处理器封锁内容而强制终止Stream时发出。这是一项安全机制，可避免Stream传送有害或不当内容。payload包含内容遭封锁的原因，以及是否已要求重试。

**type** (`"tripwire"`): Chunk类型标识符

**payload** (`TripwirePayload`): Stream因安全机制而终止的原因

**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/reference/streaming/agents/stream)：传回会发出这些Chunk之Stream的方法
- [MastraModelOutput](https://mastra.zisheng.pro/reference/streaming/agents/MastraModelOutput)：发出这些Chunk的Stream对象
- [workflow.stream()](https://mastra.zisheng.pro/reference/streaming/workflows/stream)：传回会为 Workflow 发出这些Chunk之Stream的方法