# ChunkType

The `ChunkType` type defines the mastra format of stream chunks that can be emitted during streaming responses from agents.

## Base properties

All chunks include these base properties:

**type** (`string`): The specific chunk type identifier

**runId** (`string`): Unique identifier for this execution run

**from** (`ChunkFrom`): Source of the chunk

**from.AGENT** (`'AGENT'`): Chunk from agent execution

**from.USER** (`'USER'`): Chunk from user input

**from.SYSTEM** (`'SYSTEM'`): Chunk from system processes

**from.WORKFLOW** (`'WORKFLOW'`): Chunk from workflow execution

## Text chunks

### text-start

Signals the beginning of text generation.

**type** (`"text-start"`): Chunk type identifier

**payload** (`TextStartPayload`): Text start information

**payload.id** (`string`): Unique identifier for this text generation

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

### text-delta

Incremental text content during generation.

**type** (`"text-delta"`): Chunk type identifier

**payload** (`TextDeltaPayload`): Incremental text content

**payload.id** (`string`): Unique identifier for this text generation

**payload.text** (`string`): The incremental text content

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

### text-end

Signals the end of text generation.

**type** (`"text-end"`): Chunk type identifier

**payload** (`TextEndPayload`): Text end information

**payload.id** (`string`): Unique identifier for this text generation

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

## Reasoning chunks

### reasoning-start

Signals the beginning of reasoning generation (for models that support reasoning).

**type** (`"reasoning-start"`): Chunk type identifier

**payload** (`ReasoningStartPayload`): Reasoning start information

**payload.id** (`string`): Unique identifier for this reasoning generation

**payload.signature** (`string`): Reasoning signature if available

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

### reasoning-delta

Incremental reasoning text during generation.

**type** (`"reasoning-delta"`): Chunk type identifier

**payload** (`ReasoningDeltaPayload`): Incremental reasoning content

**payload.id** (`string`): Unique identifier for this reasoning generation

**payload.text** (`string`): The incremental reasoning text

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

### reasoning-end

Signals the end of reasoning generation.

**type** (`"reasoning-end"`): Chunk type identifier

**payload** (`ReasoningEndPayload`): Reasoning end information

**payload.id** (`string`): Unique identifier for this reasoning generation

**payload.signature** (`string`): Final reasoning signature if available

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

### reasoning-signature

Contains the reasoning signature from models that support advanced reasoning (like OpenAI's o1 series). The signature represents metadata about the model's internal reasoning process, such as effort level or reasoning approach, but not the actual reasoning content itself.

**type** (`"reasoning-signature"`): Chunk type identifier

**payload** (`ReasoningSignaturePayload`): Metadata about the model's reasoning process characteristics

**payload.id** (`string`): Unique identifier for the reasoning session

**payload.signature** (`string`): Signature describing the reasoning approach or effort level (e.g., reasoning effort settings)

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

## Tool chunks

### tool-call

A tool is being called.

**type** (`"tool-call"`): Chunk type identifier

**payload** (`ToolCallPayload`): Tool call information

**payload.toolCallId** (`string`): Unique identifier for this tool call

**payload.toolName** (`string`): Name of the tool being called

**payload.args** (`Record<string, any>`): Arguments passed to the tool

**payload.providerExecuted** (`boolean`): Whether the provider executed the tool

**payload.output** (`any`): Tool output if available

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

### tool-result

Result from a tool execution.

**type** (`"tool-result"`): Chunk type identifier

**payload** (`ToolResultPayload`): Tool execution result

**payload.toolCallId** (`string`): Unique identifier for the tool call

**payload.toolName** (`string`): Name of the executed tool

**payload.result** (`any`): The result of the tool execution

**payload.isError** (`boolean`): Whether the result is an error

**payload.providerExecuted** (`boolean`): Whether the provider executed the tool

**payload.args** (`Record<string, any>`): Arguments that were passed to the tool

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

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

Signals the start of streaming tool call arguments.

**type** (`"tool-call-input-streaming-start"`): Chunk type identifier

**payload** (`ToolCallInputStreamingStartPayload`): Tool call input streaming start information

**payload.toolCallId** (`string`): Unique identifier for this tool call

**payload.toolName** (`string`): Name of the tool being called

**payload.providerExecuted** (`boolean`): Whether the provider executed the tool

**payload.dynamic** (`boolean`): Whether the tool call is dynamic

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

### `tool-call-delta`

Incremental tool call arguments during streaming.

**type** (`"tool-call-delta"`): Chunk type identifier

**payload** (`ToolCallDeltaPayload`): Incremental tool call arguments

**payload.argsTextDelta** (`string`): Incremental text delta for tool arguments

**payload.toolCallId** (`string`): Unique identifier for this tool call

**payload.toolName** (`string`): Name of the tool being called

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

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

Signals the end of streaming tool call arguments.

**type** (`"tool-call-input-streaming-end"`): Chunk type identifier

**payload** (`ToolCallInputStreamingEndPayload`): Tool call input streaming end information

**payload.toolCallId** (`string`): Unique identifier for this tool call

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

### tool-error

An error occurred during tool execution.

**type** (`"tool-error"`): Chunk type identifier

**payload** (`ToolErrorPayload`): Tool error information

**payload.id** (`string`): Optional identifier

**payload.toolCallId** (`string`): Unique identifier for the tool call

**payload.toolName** (`string`): Name of the tool that failed

**payload.args** (`Record<string, any>`): Arguments that were passed to the tool

**payload.error** (`unknown`): The error that occurred

**payload.providerExecuted** (`boolean`): Whether the provider executed the tool

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

## Source and file chunks

### source

Contains source information for content.

**type** (`"source"`): Chunk type identifier

**payload** (`SourcePayload`): Source information

**payload.id** (`string`): Unique identifier

**payload.sourceType** (`'url' | 'document'`): Type of source

**payload.title** (`string`): Title of the source

**payload.mimeType** (`string`): MIME type of the source

**payload.filename** (`string`): Filename if applicable

**payload.url** (`string`): URL if applicable

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

### file

Contains file data.

**type** (`"file"`): Chunk type identifier

**payload** (`FilePayload`): File data

**payload.data** (`string | Uint8Array`): The file data

**payload.base64** (`string`): Base64 encoded data if applicable

**payload.mimeType** (`string`): MIME type of the file

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

## Control chunks

### start

Signals the start of streaming.

**type** (`"start"`): Chunk type identifier

**payload** (`StartPayload`): Start information

**payload.\[key: string]** (`any`): Additional start data

### step-start

Signals the start of a processing step.

**type** (`"step-start"`): Chunk type identifier

**payload** (`StepStartPayload`): Step start information

**payload.messageId** (`string`): Optional message identifier

**payload.request** (`object`): Request information including body and other data

**payload.warnings** (`LanguageModelV2CallWarning[]`): Any warnings from the language model call

### step-finish

Signals the completion of a processing step.

**type** (`"step-finish"`): Chunk type identifier

**payload** (`StepFinishPayload`): Step completion information

**payload.id** (`string`): Optional identifier

**payload.messageId** (`string`): Optional message identifier

**payload.stepResult** (`object`): Step execution result with reason, warnings, and continuation info

**payload.output** (`object`): Output information including usage statistics

**payload.metadata** (`object`): Execution metadata including request and provider info

**payload.totalUsage** (`LanguageModelV2Usage`): Total usage statistics

**payload.response** (`LanguageModelV2ResponseMetadata`): Response metadata

**payload.providerMetadata** (`SharedV2ProviderMetadata`): Provider-specific metadata

### raw

Contains raw data from the provider.

**type** (`"raw"`): Chunk type identifier

**payload** (`RawPayload`): Raw provider data

**payload.\[key: string]** (`any`): Raw data from the provider

### finish

Stream has completed successfully.

**type** (`"finish"`): Chunk type identifier

**payload** (`FinishPayload`): Completion information

**payload.stepResult** (`object`): Step execution result

**payload.output** (`object`): Output information including usage

**payload.metadata** (`object`): Execution metadata

**payload.messages** (`object`): Message history

**payload.response** (`object`): Response metadata and messages from the model provider

### error

An error occurred during streaming.

**type** (`"error"`): Chunk type identifier

**payload** (`ErrorPayload`): Error information

**payload.error** (`unknown`): The error that occurred

### abort

Stream was aborted.

**type** (`"abort"`): Chunk type identifier

**payload** (`AbortPayload`): Abort information

**payload.\[key: string]** (`any`): Additional abort data

## Object and output chunks

### object

Emitted when using output generation with defined schemas. Contains partial or complete structured data that conforms to the specified Zod or JSON schema. This chunk is typically skipped in some execution contexts and used for streaming structured object generation.

**type** (`"object"`): Chunk type identifier

**object** (`Partial<OUTPUT>`): Partial or complete structured data matching the defined schema. The type is determined by the OUTPUT schema parameter.

### tool-output

Contains output from agent or workflow execution, particularly used for tracking usage statistics and completion events. Often wraps other chunk types (like finish chunks) to provide nested execution context.

**type** (`"tool-output"`): Chunk type identifier

**payload** (`ToolOutputPayload`): Wrapped execution output with metadata

**payload.output** (`ChunkType`): Nested chunk data, often containing finish events with usage statistics

### step-output

Contains output from workflow step execution, used primarily for usage tracking and step completion events. Similar to tool-output but specifically for individual workflow steps.

**type** (`"step-output"`): Chunk type identifier

**payload** (`StepOutputPayload`): Workflow step execution output with metadata

**payload.output** (`ChunkType`): Nested chunk data from step execution, typically containing finish events or other step results

## Background task chunks

Emitted when a tool call is dispatched as a [background task](https://mastra.ai/docs/agents/background-tasks) and `streamUntilIdle()` is used.

### background-task-started

Emitted when a tool call is enqueued as a background task and assigned a `taskId`.

**type** (`"background-task-started"`): Chunk type identifier

**payload** (`BackgroundTaskStartedPayload`): Identifies the newly enqueued task

**payload.taskId** (`string`): Unique identifier for the background task

**payload.toolName** (`string`): Name of the tool being executed

**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call

### background-task-running

Emitted when a worker picks up the task and execution begins.

**type** (`"background-task-running"`): Chunk type identifier

**payload** (`BackgroundTaskRunningPayload`): Details about the running task

**payload.taskId** (`string`): Unique identifier for the background task

**payload.toolName** (`string`): Name of the tool being executed

**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call

**payload.runId** (`string`): Run ID of the agent that dispatched the task

**payload.agentId** (`string`): ID of the agent that dispatched the task

**payload.startedAt** (`Date`): Timestamp at which execution started

**payload.args** (`Record<string, unknown>`): Arguments passed to the tool's execute function

### background-task-progress

Periodic snapshot of how many background tasks are currently running across the agent.

**type** (`"background-task-progress"`): Chunk type identifier

**payload** (`BackgroundTaskProgressPayload`): Aggregate progress for all running tasks

**payload.taskIds** (`string[]`): IDs of all currently running background tasks

**payload.runningCount** (`number`): Number of background tasks currently running

**payload.elapsedMs** (`number`): Milliseconds elapsed since the agent run started

### background-task-output

A streamed output chunk emitted by the task's `execute` function. Wraps an inner [`tool-output`](#tool-output) chunk.

**type** (`"background-task-output"`): Chunk type identifier

**payload** (`BackgroundTaskOutputPayload`): Streamed output from the running task

**payload.taskId** (`string`): Unique identifier for the background task

**payload.toolName** (`string`): Name of the tool being executed

**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call

**payload.runId** (`string`): Run ID of the agent that dispatched the task

**payload.agentId** (`string`): ID of the agent that dispatched the task

**payload.payload** (`ToolOutputChunk`): Inner tool-output chunk produced by the task

### background-task-completed

Emitted when the task finishes successfully. Triggers a continuation turn when consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle).

**type** (`"background-task-completed"`): Chunk type identifier

**payload** (`BackgroundTaskResultPayload`): The completed task's result

**payload.taskId** (`string`): Unique identifier for the background task

**payload.toolName** (`string`): Name of the tool that was executed

**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call

**payload.agentId** (`string`): ID of the agent that dispatched the task

**payload.runId** (`string`): Run ID of the agent that dispatched the task

**payload.result** (`unknown`): The tool's resolved return value

**payload.completedAt** (`Date`): Timestamp at which the task completed

**payload.isError** (`boolean`): True when the tool returned an error result rather than throwing

### background-task-failed

Emitted when the task throws or times out. Triggers a continuation turn when consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle).

**type** (`"background-task-failed"`): Chunk type identifier

**payload** (`BackgroundTaskFailedPayload`): Failure details for the task

**payload.taskId** (`string`): Unique identifier for the background task

**payload.toolName** (`string`): Name of the tool that was executed

**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call

**payload.runId** (`string`): Run ID of the agent that dispatched the task

**payload.agentId** (`string`): ID of the agent that dispatched the task

**payload.error** (`{ message: string }`): Error details thrown by the task

**payload.completedAt** (`Date`): Timestamp at which the task failed

### background-task-suspended

Emitted when a tool calls `suspend()` from inside its background execution. Pauses the task's workflow run with its snapshot persisted; resume with `mastra.backgroundTaskManager.resume(taskId, resumeData)`.

When consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle), this chunk drops the task from the loop's wait set without queuing a continuation — the agent's response ends, and the resumed task's eventual completion injects into the message list for the next user turn.

**type** (`"background-task-suspended"`): Chunk type identifier

**payload** (`BackgroundTaskSuspendedPayload`): Suspension details for the task

**payload.taskId** (`string`): Unique identifier for the background task

**payload.toolName** (`string`): Name of the tool that was executed

**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call

**payload.runId** (`string`): Run ID of the agent that dispatched the task

**payload.agentId** (`string`): ID of the agent that dispatched the task

**payload.suspendData** (`unknown`): Whatever the tool passed to \`suspend(data)\`

### background-task-resumed

Emitted when a suspended task is resumed via `mastra.backgroundTaskManager.resume(taskId, resumeData)`. The task transitions back to `running` and the tool's `execute` is restarted with `resumeData` populated.

**type** (`"background-task-resumed"`): Chunk type identifier

**payload** (`BackgroundTaskResumedPayload`): Resume details for the task

**payload.taskId** (`string`): Unique identifier for the background task

**payload.toolName** (`string`): Name of the tool that was executed

**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call

**payload.runId** (`string`): Run ID of the agent that dispatched the task

**payload.agentId** (`string`): ID of the agent that dispatched the task

**payload.startedAt** (`Date`): Timestamp at which the task resumed

**payload.args** (`Record<string, unknown>`): Original tool arguments

### background-task-cancelled

Emitted when the task is cancelled before completing. Triggers a continuation turn when consumed by [`Agent.streamUntilIdle()`](https://mastra.ai/reference/streaming/agents/streamUntilIdle).

**type** (`"background-task-cancelled"`): Chunk type identifier

**payload** (`BackgroundTaskCancelledPayload`): Cancellation details for the task

**payload.taskId** (`string`): Unique identifier for the background task

**payload.toolName** (`string`): Name of the tool that was executed

**payload.toolCallId** (`string`): Tool-call ID from the originating LLM tool call

**payload.runId** (`string`): Run ID of the agent that dispatched the task

**payload.agentId** (`string`): ID of the agent that dispatched the task

**payload.completedAt** (`Date`): Timestamp at which the task was cancelled

## Metadata and special chunks

### response-metadata

Contains metadata about the LLM provider's response. Emitted by some providers after text generation to provide additional context like model ID, timestamps, and response headers. This chunk is used internally for state tracking and doesn't affect message assembly.

**type** (`"response-metadata"`): Chunk type identifier

**payload** (`ResponseMetadataPayload`): Provider response metadata for tracking and debugging

**payload.signature** (`string`): Response signature if available

**payload.\[key: string]** (`any`): Additional provider-specific metadata fields (e.g., id, modelId, timestamp, headers)

### watch

Contains monitoring and observability data from agent execution. Can include workflow state information, execution progress, or other runtime details depending on the context where `stream()` is used.

**type** (`"watch"`): Chunk type identifier

**payload** (`WatchPayload`): Monitoring data for observability and debugging of agent execution

**payload.workflowState** (`object`): Current workflow execution state (when used in workflows)

**payload.eventTimestamp** (`number`): Timestamp when the event occurred

**payload.\[key: string]** (`any`): Additional monitoring and execution data

### tripwire

Emitted when the stream is forcibly terminated due to content being blocked by a processor. This acts as a safety mechanism to prevent harmful or inappropriate content from being streamed. The payload includes information about why the content was blocked and whether a retry was requested.

**type** (`"tripwire"`): Chunk type identifier

**payload** (`TripwirePayload`): Information about why the stream was terminated by safety mechanisms

**payload.reason** (`string`): Explanation of why the content was blocked (e.g., 'Output processor blocked content')

**payload.retry** (`boolean`): Whether the processor requested a retry of the step

**payload.metadata** (`unknown`): Additional metadata from the processor (e.g., scores, categories)

**payload.processorId** (`string`): ID of the processor that triggered the tripwire

## Usage example

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

## Related types

- [.stream()](https://mastra.ai/reference/streaming/agents/stream): Method that returns streams emitting these chunks
- [MastraModelOutput](https://mastra.ai/reference/streaming/agents/MastraModelOutput): The stream object that emits these chunks
- [workflow.stream()](https://mastra.ai/reference/streaming/workflows/stream): Method that returns streams emitting these chunks for workflows