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

enum

AGENT:

'AGENT'

Chunk from agent execution

USER:

'USER'

Chunk from user input

SYSTEM:

'SYSTEM'

Chunk from system processes

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

TextStartPayload

id:

string

Unique identifier for this text generation

providerMetadata?:

SharedV2ProviderMetadata

Provider-specific metadata

text-delta

Incremental text content during generation.

type:

"text-delta"

Chunk type identifier

payload:

TextDeltaPayload

Incremental text content

TextDeltaPayload

id:

string

Unique identifier for this text generation

text:

string

The incremental text content

providerMetadata?:

SharedV2ProviderMetadata

Provider-specific metadata

text-end

Signals the end of text generation.

type:

"text-end"

Chunk type identifier

payload:

TextEndPayload

Text end information

TextEndPayload

id:

string

Unique identifier for this text generation

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

ReasoningStartPayload

id:

string

Unique identifier for this reasoning generation

signature?:

string

Reasoning signature if available

providerMetadata?:

SharedV2ProviderMetadata

Provider-specific metadata

reasoning-delta

Incremental reasoning text during generation.

type:

"reasoning-delta"

Chunk type identifier

payload:

ReasoningDeltaPayload

Incremental reasoning content

ReasoningDeltaPayload

id:

string

Unique identifier for this reasoning generation

text:

string

The incremental reasoning text

providerMetadata?:

SharedV2ProviderMetadata

Provider-specific metadata

reasoning-end

Signals the end of reasoning generation.

type:

"reasoning-end"

Chunk type identifier

payload:

ReasoningEndPayload

Reasoning end information

ReasoningEndPayload

id:

string

Unique identifier for this reasoning generation

signature?:

string

Final reasoning signature if available

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

ReasoningSignaturePayload

id:

string

Unique identifier for the reasoning session

signature:

string

Signature describing the reasoning approach or effort level (e.g., reasoning effort settings)

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

ToolCallPayload

toolCallId:

string

Unique identifier for this tool call

toolName:

string

Name of the tool being called

args?:

Record<string, any>

Arguments passed to the tool

providerExecuted?:

boolean

Whether the provider executed the tool

output?:

any

Tool output if available

providerMetadata?:

SharedV2ProviderMetadata

Provider-specific metadata

tool-result

Result from a tool execution.

type:

"tool-result"

Chunk type identifier

payload:

ToolResultPayload

Tool execution result

ToolResultPayload

toolCallId:

string

Unique identifier for the tool call

toolName:

string

Name of the executed tool

result:

any

The result of the tool execution

isError?:

boolean

Whether the result is an error

providerExecuted?:

boolean

Whether the provider executed the tool

args?:

Record<string, any>

Arguments that were passed to the tool

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

ToolCallInputStreamingStartPayload

toolCallId:

string

Unique identifier for this tool call

toolName:

string

Name of the tool being called

providerExecuted?:

boolean

Whether the provider executed the tool

dynamic?:

boolean

Whether the tool call is dynamic

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

ToolCallDeltaPayload

argsTextDelta:

string

Incremental text delta for tool arguments

toolCallId:

string

Unique identifier for this tool call

toolName?:

string

Name of the tool being called

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

ToolCallInputStreamingEndPayload

toolCallId:

string

Unique identifier for this tool call

providerMetadata?:

SharedV2ProviderMetadata

Provider-specific metadata

tool-error

An error occurred during tool execution.

type:

"tool-error"

Chunk type identifier

payload:

ToolErrorPayload

Tool error information

ToolErrorPayload

id?:

string

Optional identifier

toolCallId:

string

Unique identifier for the tool call

toolName:

string

Name of the tool that failed

args?:

Record<string, any>

Arguments that were passed to the tool

error:

unknown

The error that occurred

providerExecuted?:

boolean

Whether the provider executed the tool

providerMetadata?:

SharedV2ProviderMetadata

Provider-specific metadata

Source and File Chunks

source

Contains source information for content.

type:

"source"

Chunk type identifier

payload:

SourcePayload

Source information

SourcePayload

id:

string

Unique identifier

sourceType:

'url' | 'document'

Type of source

title:

string

Title of the source

mimeType?:

string

MIME type of the source

filename?:

string

Filename if applicable

url?:

string

URL if applicable

providerMetadata?:

SharedV2ProviderMetadata

Provider-specific metadata

file

Contains file data.

type:

"file"

Chunk type identifier

payload:

FilePayload

File data

FilePayload

data:

string | Uint8Array

The file data

base64?:

string

Base64 encoded data if applicable

mimeType:

string

MIME type of the file

providerMetadata?:

SharedV2ProviderMetadata

Provider-specific metadata

Control Chunks

start

Signals the start of streaming.

type:

"start"

Chunk type identifier

payload:

StartPayload

Start information

StartPayload

[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

StepStartPayload

messageId?:

string

Optional message identifier

request:

object

Request information including body and other data

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

StepFinishPayload

id?:

string

Optional identifier

messageId?:

string

Optional message identifier

stepResult:

object

Step execution result with reason, warnings, and continuation info

output:

object

Output information including usage statistics

metadata:

object

Execution metadata including request and provider info

totalUsage?:

LanguageModelV2Usage

Total usage statistics

response?:

LanguageModelV2ResponseMetadata

Response metadata

providerMetadata?:

SharedV2ProviderMetadata

Provider-specific metadata

raw

Contains raw data from the provider.

type:

"raw"

Chunk type identifier

payload:

RawPayload

Raw provider data

RawPayload

[key: string]:

any

Raw data from the provider

finish

Stream has completed successfully.

type:

"finish"

Chunk type identifier

payload:

FinishPayload

Completion information

FinishPayload

stepResult:

object

Step execution result

output:

object

Output information including usage

metadata:

object

Execution metadata

messages:

object

Message history

error

An error occurred during streaming.

type:

"error"

Chunk type identifier

payload:

ErrorPayload

Error information

ErrorPayload

error:

unknown

The error that occurred

abort

Stream was aborted.

type:

"abort"

Chunk type identifier

payload:

AbortPayload

Abort information

AbortPayload

[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:

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

ToolOutputPayload

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

StepOutputPayload

output:

ChunkType

Nested 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

Provider response metadata for tracking and debugging

ResponseMetadataPayload

signature?:

string

Response signature if available

[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

WatchPayload

workflowState?:

object

Current workflow execution state (when used in workflows)

eventTimestamp?:

number

Timestamp when the event occurred

[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

TripwirePayload

reason:

string

Explanation of why the content was blocked (e.g., 'Output processor blocked content')

retry?:

boolean

Whether the processor requested a retry of the step

metadata?:

unknown

Additional metadata from the processor (e.g., scores, categories)

processorId?:

string

ID of the processor that triggered the tripwire

Usage Example

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() - Method that returns streams emitting these chunks
• MastraModelOutput - The stream object that emits these chunks
• workflow.stream() - Method that returns streams emitting these chunks for workflows