# 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`): enumAGENT:'AGENT'Chunk from agent executionUSER:'USER'Chunk from user inputSYSTEM:'SYSTEM'Chunk from system processesWORKFLOW:'WORKFLOW'Chunk from workflow execution

## Text Chunks

### text-start

Signals the beginning of text generation.

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

**payload:** (`TextStartPayload`): TextStartPayloadid:stringUnique identifier for this text generationproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata

### text-delta

Incremental text content during generation.

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

**payload:** (`TextDeltaPayload`): TextDeltaPayloadid:stringUnique identifier for this text generationtext:stringThe incremental text contentproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata

### text-end

Signals the end of text generation.

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

**payload:** (`TextEndPayload`): TextEndPayloadid:stringUnique identifier for this text generationproviderMetadata?:SharedV2ProviderMetadataProvider-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`): ReasoningStartPayloadid:stringUnique identifier for this reasoning generationsignature?:stringReasoning signature if availableproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata

### reasoning-delta

Incremental reasoning text during generation.

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

**payload:** (`ReasoningDeltaPayload`): ReasoningDeltaPayloadid:stringUnique identifier for this reasoning generationtext:stringThe incremental reasoning textproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata

### reasoning-end

Signals the end of reasoning generation.

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

**payload:** (`ReasoningEndPayload`): ReasoningEndPayloadid:stringUnique identifier for this reasoning generationsignature?:stringFinal reasoning signature if availableproviderMetadata?:SharedV2ProviderMetadataProvider-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`): ReasoningSignaturePayloadid:stringUnique identifier for the reasoning sessionsignature:stringSignature describing the reasoning approach or effort level (e.g., reasoning effort settings)providerMetadata?:SharedV2ProviderMetadataProvider-specific metadata

## Tool Chunks

### tool-call

A tool is being called.

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

**payload:** (`ToolCallPayload`): ToolCallPayloadtoolCallId:stringUnique identifier for this tool calltoolName:stringName of the tool being calledargs?:Record\<string, any>Arguments passed to the toolproviderExecuted?:booleanWhether the provider executed the tooloutput?:anyTool output if availableproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata

### tool-result

Result from a tool execution.

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

**payload:** (`ToolResultPayload`): ToolResultPayloadtoolCallId:stringUnique identifier for the tool calltoolName:stringName of the executed toolresult:anyThe result of the tool executionisError?:booleanWhether the result is an errorproviderExecuted?:booleanWhether the provider executed the toolargs?:Record\<string, any>Arguments that were passed to the toolproviderMetadata?:SharedV2ProviderMetadataProvider-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`): ToolCallInputStreamingStartPayloadtoolCallId:stringUnique identifier for this tool calltoolName:stringName of the tool being calledproviderExecuted?:booleanWhether the provider executed the tooldynamic?:booleanWhether the tool call is dynamicproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata

### tool-call-delta

Incremental tool call arguments during streaming.

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

**payload:** (`ToolCallDeltaPayload`): ToolCallDeltaPayloadargsTextDelta:stringIncremental text delta for tool argumentstoolCallId:stringUnique identifier for this tool calltoolName?:stringName of the tool being calledproviderMetadata?:SharedV2ProviderMetadataProvider-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`): ToolCallInputStreamingEndPayloadtoolCallId:stringUnique identifier for this tool callproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata

### tool-error

An error occurred during tool execution.

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

**payload:** (`ToolErrorPayload`): ToolErrorPayloadid?:stringOptional identifiertoolCallId:stringUnique identifier for the tool calltoolName:stringName of the tool that failedargs?:Record\<string, any>Arguments that were passed to the toolerror:unknownThe error that occurredproviderExecuted?:booleanWhether the provider executed the toolproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata

## Source and File Chunks

### source

Contains source information for content.

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

**payload:** (`SourcePayload`): SourcePayloadid:stringUnique identifiersourceType:'url' | 'document'Type of sourcetitle:stringTitle of the sourcemimeType?:stringMIME type of the sourcefilename?:stringFilename if applicableurl?:stringURL if applicableproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata

### file

Contains file data.

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

**payload:** (`FilePayload`): FilePayloaddata:string | Uint8ArrayThe file database64?:stringBase64 encoded data if applicablemimeType:stringMIME type of the fileproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata

## Control Chunks

### start

Signals the start of streaming.

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

**payload:** (`StartPayload`): StartPayload\[key: string]:anyAdditional start data

### step-start

Signals the start of a processing step.

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

**payload:** (`StepStartPayload`): StepStartPayloadmessageId?:stringOptional message identifierrequest:objectRequest information including body and other datawarnings?: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`): StepFinishPayloadid?:stringOptional identifiermessageId?:stringOptional message identifierstepResult:objectStep execution result with reason, warnings, and continuation infooutput:objectOutput information including usage statisticsmetadata:objectExecution metadata including request and provider infototalUsage?:LanguageModelV2UsageTotal usage statisticsresponse?:LanguageModelV2ResponseMetadataResponse metadataproviderMetadata?:SharedV2ProviderMetadataProvider-specific metadata

### raw

Contains raw data from the provider.

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

**payload:** (`RawPayload`): RawPayload\[key: string]:anyRaw data from the provider

### finish

Stream has completed successfully.

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

**payload:** (`FinishPayload`): FinishPayloadstepResult:objectStep execution resultoutput:objectOutput information including usagemetadata:objectExecution metadatamessages:objectMessage historyresponse:objectResponse metadata and messages from the model provider

### error

An error occurred during streaming.

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

**payload:** (`ErrorPayload`): ErrorPayloaderror:unknownThe error that occurred

### abort

Stream was aborted.

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

**payload:** (`AbortPayload`): AbortPayload\[key: string]:anyAdditional 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`): ToolOutputPayloadoutput:ChunkTypeNested 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`): StepOutputPayloadoutput:ChunkTypeNested chunk data from step execution, typically containing finish events or other step results

## 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`): ResponseMetadataPayloadsignature?:stringResponse signature if available\[key: string]:anyAdditional 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`): WatchPayloadworkflowState?:objectCurrent workflow execution state (when used in workflows)eventTimestamp?:numberTimestamp when the event occurred\[key: string]:anyAdditional 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`): TripwirePayloadreason:stringExplanation of why the content was blocked (e.g., 'Output processor blocked content')retry?:booleanWhether the processor requested a retry of the stepmetadata?:unknownAdditional metadata from the processor (e.g., scores, categories)processorId?:stringID 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