청크 유형

그만큼ChunkTypetype은 Agent의 스트리밍 응답 중에 방출될 수 있는 스트림 청크의 마스터 형식을 정의합니다.

기본 속성

모든 청크에는 다음과 같은 기본 속성이 포함됩니다.

type:

string

특정 청크 유형 식별자

runId:

string

이 실행의 고유 식별자

from:

ChunkFrom

청크의 출처

enum

AGENT:

'AGENT'

Agent 실행에서 생성된 청크

USER:

'USER'

사용자 입력에서 생성된 청크

SYSTEM:

'SYSTEM'

시스템 프로세스에서 생성된 청크

WORKFLOW:

'WORKFLOW'

Workflow 실행에서 생성된 청크

텍스트 덩어리

텍스트 시작

텍스트 생성의 시작을 알립니다.

type:

"text-start"

청크 유형 식별자

payload:

TextStartPayload

텍스트 시작 정보

TextStartPayload

id:

string

이 텍스트 생성의 고유 식별자

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

텍스트-델타

생성 중 증분 텍스트 콘텐츠입니다.

type:

"text-delta"

청크 유형 식별자

payload:

TextDeltaPayload

증분 텍스트 콘텐츠

TextDeltaPayload

id:

string

이 텍스트 생성의 고유 식별자

text:

string

증분 텍스트 콘텐츠

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

텍스트 끝

텍스트 생성이 끝났음을 알립니다.

type:

"text-end"

청크 유형 식별자

payload:

TextEndPayload

텍스트 종료 정보

TextEndPayload

id:

string

이 텍스트 생성의 고유 식별자

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

추론 덩어리

추론 시작

추론 생성의 시작을 알립니다(추론을 지원하는 Model의 경우).

type:

"reasoning-start"

청크 유형 식별자

payload:

ReasoningStartPayload

추론 시작 정보

ReasoningStartPayload

id:

string

이 추론 생성의 고유 식별자

signature?:

string

사용 가능한 경우 추론 서명

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

추론-델타

생성 중 증분 추론 텍스트입니다.

type:

"reasoning-delta"

청크 유형 식별자

payload:

ReasoningDeltaPayload

증분 추론 콘텐츠

ReasoningDeltaPayload

id:

string

이 추론 생성의 고유 식별자

text:

string

증분 추론 텍스트

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

추론 종료

추론 생성의 끝을 알립니다.

type:

"reasoning-end"

청크 유형 식별자

payload:

ReasoningEndPayload

추론 종료 정보

ReasoningEndPayload

id:

string

이 추론 생성의 고유 식별자

signature?:

string

사용 가능한 경우 최종 추론 서명

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

추론 서명

고급 추론을 지원하는 Model(예: OpenAI의 o1 시리즈)의 추론 서명을 포함합니다. 서명은 노력 수준이나 추론 접근 방식과 같은 Model의 내부 추론 프로세스에 대한 메타데이터를 나타내지만 실제 추론 콘텐츠 자체는 아닙니다.

type:

"reasoning-signature"

청크 유형 식별자

payload:

ReasoningSignaturePayload

Model의 추론 프로세스 특성에 관한 메타데이터

ReasoningSignaturePayload

id:

string

추론 세션의 고유 식별자

signature:

string

추론 방식 또는 노력 수준을 설명하는 서명(예: 추론 노력 설정)

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

Tool 덩어리

Tool 호출

Tool이 호출되고 있습니다.

type:

"tool-call"

청크 유형 식별자

payload:

ToolCallPayload

Tool 호출 정보

ToolCallPayload

toolCallId:

string

이 Tool 호출의 고유 식별자

toolName:

string

호출되는 Tool의 이름

args?:

Record<string, any>

Tool에 전달된 인수

providerExecuted?:

boolean

Provider가 Tool을 실행했는지 여부

output?:

any

사용 가능한 경우 Tool 출력

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

Tool 결과

Tool 실행의 결과입니다.

type:

"tool-result"

청크 유형 식별자

payload:

ToolResultPayload

Tool 실행 결과

ToolResultPayload

toolCallId:

string

Tool 호출의 고유 식별자

toolName:

string

실행된 Tool의 이름

result:

any

Tool 실행 결과

isError?:

boolean

결과가 오류인지 여부

providerExecuted?:

boolean

Provider가 Tool을 실행했는지 여부

args?:

Record<string, any>

Tool에 전달된 인수

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

tool-call-input-streaming-start

스트리밍 Tool 호출 인수의 시작을 알립니다.

type:

"tool-call-input-streaming-start"

청크 유형 식별자

payload:

ToolCallInputStreamingStartPayload

Tool 호출 입력 스트리밍 시작 정보

ToolCallInputStreamingStartPayload

toolCallId:

string

이 Tool 호출의 고유 식별자

toolName:

string

호출되는 Tool의 이름

providerExecuted?:

boolean

Provider가 Tool을 실행했는지 여부

dynamic?:

boolean

Tool 호출이 동적인지 여부

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

tool-call-delta

스트리밍 중 증분 Tool 호출 인수입니다.

type:

"tool-call-delta"

청크 유형 식별자

payload:

ToolCallDeltaPayload

증분 Tool 호출 인수

ToolCallDeltaPayload

argsTextDelta:

string

Tool 인수의 증분 텍스트 델타

toolCallId:

string

이 Tool 호출의 고유 식별자

toolName?:

string

호출되는 Tool의 이름

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

tool-call-input-streaming-end

스트리밍 Tool 호출 인수의 끝을 신호합니다.

type:

"tool-call-input-streaming-end"

청크 유형 식별자

payload:

ToolCallInputStreamingEndPayload

Tool 호출 입력 스트리밍 종료 정보

ToolCallInputStreamingEndPayload

toolCallId:

string

이 Tool 호출의 고유 식별자

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

Tool 오류

Tool 실행 중 오류가 발생했습니다.

type:

"tool-error"

청크 유형 식별자

payload:

ToolErrorPayload

Tool 오류 정보

ToolErrorPayload

id?:

string

선택적 식별자

toolCallId:

string

Tool 호출의 고유 식별자

toolName:

string

실패한 Tool의 이름

args?:

Record<string, any>

Tool에 전달된 인수

error:

unknown

발생한 오류

providerExecuted?:

boolean

Provider가 Tool을 실행했는지 여부

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

소스 및 파일 청크

원천

콘텐츠의 소스 정보가 포함되어 있습니다.

type:

"source"

청크 유형 식별자

payload:

SourcePayload

소스 정보

SourcePayload

id:

string

Unique identifier

sourceType:

'url' | 'document'

소스 유형

title:

string

소스 제목

mimeType?:

string

소스의 MIME 유형

filename?:

string

해당하는 경우 파일 이름

url?:

string

해당하는 경우 URL

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

파일

파일 데이터를 포함합니다.

type:

"file"

청크 유형 식별자

payload:

FilePayload

파일 데이터

FilePayload

data:

string | Uint8Array

파일 데이터

base64?:

string

해당하는 경우 Base64로 인코딩된 데이터

mimeType:

string

파일의 MIME 유형

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

제어 청크

시작

스트리밍 시작을 알립니다.

type:

"start"

청크 유형 식별자

payload:

StartPayload

시작 정보

StartPayload

[key: string]:

any

추가 시작 데이터

단계적으로 시작하다

처리 단계의 시작을 알립니다.

type:

"step-start"

청크 유형 식별자

payload:

StepStartPayload

단계 시작 정보

StepStartPayload

messageId?:

string

선택적 메시지 식별자

request:

object

본문 및 기타 데이터를 포함한 요청 정보

warnings?:

LanguageModelV2CallWarning[]

언어 Model 호출에서 발생한 경고

단계 마무리

처리 단계가 완료되었음을 나타냅니다.

type:

"step-finish"

청크 유형 식별자

payload:

StepFinishPayload

단계 완료 정보

StepFinishPayload

id?:

string

선택적 식별자

messageId?:

string

선택적 메시지 식별자

stepResult:

object

이유, 경고, 계속 진행 정보를 포함한 단계 실행 결과

output:

object

사용량 통계를 포함한 출력 정보

metadata:

object

요청 및 Provider 정보를 포함한 실행 메타데이터

totalUsage?:

LanguageModelV2Usage

총 사용량 통계

response?:

LanguageModelV2ResponseMetadata

응답 메타데이터

providerMetadata?:

SharedV2ProviderMetadata

Provider별 메타데이터

날것의

공급자의 원시 데이터를 포함합니다.

type:

"raw"

청크 유형 식별자

payload:

RawPayload

원시 Provider 데이터

RawPayload

[key: string]:

any

Provider의 원시 데이터

마치다

스트림이 성공적으로 완료되었습니다.

type:

"finish"

청크 유형 식별자

payload:

FinishPayload

완료 정보

FinishPayload

stepResult:

object

단계 실행 결과

output:

object

사용량을 포함한 출력 정보

metadata:

object

실행 메타데이터

messages:

object

메시지 기록

response:

object

Model Provider의 응답 메타데이터 및 메시지

오류

스트리밍 중에 오류가 발생했습니다.

type:

"error"

청크 유형 식별자

payload:

ErrorPayload

오류 정보

ErrorPayload

error:

unknown

발생한 오류

중단하다

스트림이 중단되었습니다.

type:

"abort"

청크 유형 식별자

payload:

AbortPayload

중단 정보

AbortPayload

[key: string]:

any

추가 중단 데이터

객체 및 출력 청크

물체

정의된 스키마로 출력 생성을 사용할 때 발생합니다. 지정된 Zod 또는 JSON 스키마를 준수하는 부분 또는 전체 구조화된 데이터를 포함합니다. 이 청크는 일반적으로 일부 실행 컨텍스트에서 건너뛰고 구조화된 객체 생성 스트리밍에 사용됩니다.

type:

"object"

청크 유형 식별자

object:

Partial<OUTPUT>

정의된 스키마와 일치하는 부분적 또는 완전한 구조화 데이터입니다. 유형은 OUTPUT 스키마 매개변수에 의해 결정됩니다.

Tool 출력

특히 사용 통계 및 완료 이벤트를 추적하는 데 사용되는 Agent 또는 Workflow 실행의 출력을 포함합니다. 중첩된 실행 컨텍스트를 제공하기 위해 다른 청크 유형(마무리 청크 등)을 래핑하는 경우가 많습니다.

type:

"tool-output"

청크 유형 식별자

payload:

ToolOutputPayload

메타데이터로 래핑된 실행 출력

ToolOutputPayload

output:

ChunkType

주로 사용량 통계가 포함된 완료 이벤트를 담는 중첩 청크 데이터

스텝 아웃풋

주로 사용량 추적 및 단계 완료 이벤트에 사용되는 Workflow 단계 실행의 출력을 포함합니다. Tool 출력과 유사하지만 특히 개별 Workflow 단계에 해당합니다.

type:

"step-output"

청크 유형 식별자

payload:

StepOutputPayload

메타데이터가 포함된 Workflow 단계 실행 출력

StepOutputPayload

output:

ChunkType

단계 실행에서 생성된 중첩 청크 데이터로, 일반적으로 완료 이벤트나 기타 단계 결과를 포함합니다.

백그라운드 작업 청크

Tool 호출이 백그라운드 작업으로 위임되고 streamUntilIdle()을 사용할 때 발생합니다.

백그라운드 작업 시작

Tool 호출이 백그라운드 작업으로 대기열에 추가되고 할당될 때 발생합니다.taskId.

type:

"background-task-started"

청크 유형 식별자

payload:

BackgroundTaskStartedPayload

새로 대기열에 추가된 작업을 식별합니다.

BackgroundTaskStartedPayload

taskId:

string

백그라운드 작업의 고유 식별자

toolName:

string

실행되는 Tool의 이름

toolCallId:

string

원래 LLM Tool 호출의 Tool 호출 ID

백그라운드 작업 실행

작업자가 작업을 선택하고 실행이 시작될 때 발생합니다.

type:

"background-task-running"

청크 유형 식별자

payload:

BackgroundTaskRunningPayload

실행 중인 작업에 관한 세부 정보

BackgroundTaskRunningPayload

taskId:

string

백그라운드 작업의 고유 식별자

toolName:

string

실행되는 Tool의 이름

toolCallId:

string

원래 LLM Tool 호출의 Tool 호출 ID

runId:

string

작업을 전달한 Agent의 실행 ID

agentId:

string

작업을 전달한 Agent의 ID

startedAt:

Date

실행이 시작된 타임스탬프

args:

Record<string, unknown>

Tool의 execute 함수에 전달된 인수

백그라운드 작업 진행

현재 Agent 전체에서 실행 중인 백그라운드 작업 수에 대한 정기적인 스냅샷입니다.

type:

"background-task-progress"

청크 유형 식별자

payload:

BackgroundTaskProgressPayload

실행 중인 모든 작업의 집계 진행 상황

BackgroundTaskProgressPayload

taskIds:

string[]

현재 실행 중인 모든 백그라운드 작업의 ID

runningCount:

number

현재 실행 중인 백그라운드 작업 수

elapsedMs:

number

Agent 실행이 시작된 후 경과한 시간(밀리초)

백그라운드 작업 출력

작업의 execute 함수에서 내보낸 스트리밍 출력 청크입니다. 내부 tool-output 청크를 래핑합니다.

type:

"background-task-output"

청크 유형 식별자

payload:

BackgroundTaskOutputPayload

실행 중인 작업의 스트리밍 출력

BackgroundTaskOutputPayload

taskId:

string

백그라운드 작업의 고유 식별자

toolName:

string

실행되는 Tool의 이름

toolCallId:

string

원래 LLM Tool 호출의 Tool 호출 ID

runId:

string

작업을 전달한 Agent의 실행 ID

agentId:

string

작업을 전달한 Agent의 ID

payload:

ToolOutputChunk

작업에서 생성된 내부 Tool 출력 청크

백그라운드 작업 완료

작업이 성공적으로 완료되면 내보냅니다. 소비되면 연속 턴이 발생합니다.Agent.streamUntilIdle().

type:

"background-task-completed"

청크 유형 식별자

payload:

BackgroundTaskResultPayload

완료된 작업의 결과

BackgroundTaskResultPayload

taskId:

string

백그라운드 작업의 고유 식별자

toolName:

string

실행된 Tool의 이름

toolCallId:

string

원래 LLM Tool 호출의 Tool 호출 ID

agentId:

string

작업을 전달한 Agent의 ID

runId:

string

작업을 전달한 Agent의 실행 ID

result:

unknown

Tool에서 이행된 반환 값

completedAt:

Date

작업이 완료된 시점의 타임스탬프

isError?:

boolean

Tool이 예외를 발생시키는 대신 오류 결과를 반환했으면 true

백그라운드 작업 실패

작업이 발생하거나 시간 초과되면 발생합니다. 소비되면 연속 턴이 발생합니다.Agent.streamUntilIdle().

type:

"background-task-failed"

청크 유형 식별자

payload:

BackgroundTaskFailedPayload

작업의 실패 세부 정보

BackgroundTaskFailedPayload

taskId:

string

백그라운드 작업의 고유 식별자

toolName:

string

실행된 Tool의 이름

toolCallId:

string

호출을 시작한 LLM Tool 호출의 Tool 호출 ID

runId:

string

작업을 디스패치한 Agent의 실행 ID

agentId:

string

작업을 디스패치한 Agent의 ID

error:

{ message: string }

작업에서 발생한 오류의 세부 정보

completedAt:

Date

작업이 실패한 시점의 타임스탬프

백그라운드 작업 일시 중지

Tool의 백그라운드 실행 내부에서 suspend()가 호출될 때 발생합니다. 스냅샷을 유지한 채 작업의 Workflow 실행을 일시 중단합니다. mastra.backgroundTaskManager.resume(taskId, resumeData)으로 재개합니다. Agent.streamUntilIdle()로 소비할 때 이 청크는 연속 실행을 큐에 추가하지 않고 루프의 대기 집합에서 작업을 제거합니다. Agent의 응답이 종료되며, 재개된 작업이 나중에 완료되면 그 결과가 다음 사용자 턴의 메시지 목록에 삽입됩니다.

type:

"background-task-suspended"

청크 유형 식별자

payload:

BackgroundTaskSuspendedPayload

작업의 일시 중단 세부 정보

BackgroundTaskSuspendedPayload

taskId:

string

백그라운드 작업의 고유 식별자

toolName:

string

실행된 Tool의 이름

toolCallId:

string

호출을 시작한 LLM Tool 호출의 Tool 호출 ID

runId:

string

작업을 디스패치한 Agent의 실행 ID

agentId:

string

작업을 디스패치한 Agent의 ID

suspendData?:

unknown

Tool이 suspend(data)에 전달한 값

백그라운드 작업 재개

일시 중단된 작업이 mastra.backgroundTaskManager.resume(taskId, resumeData)을 통해 재개될 때 발생합니다. 작업은 다시 running 상태로 전환되며, resumeData가 채워진 상태로 Tool의 execute가 다시 시작됩니다.

type:

"background-task-resumed"

청크 유형 식별자

payload:

BackgroundTaskResumedPayload

작업의 재개 세부 정보

BackgroundTaskResumedPayload

taskId:

string

백그라운드 작업의 고유 식별자

toolName:

string

실행된 Tool의 이름

toolCallId:

string

호출을 시작한 LLM Tool 호출의 Tool 호출 ID

runId:

string

작업을 디스패치한 Agent의 실행 ID

agentId:

string

작업을 디스패치한 Agent의 ID

startedAt:

Date

작업이 재개된 시점의 타임스탬프

args:

Record<string, unknown>

원래 Tool 인수

백그라운드 작업이 취소됨

작업이 완료되기 전에 취소되면 발생합니다. 소비되면 연속 턴이 발생합니다.Agent.streamUntilIdle().

type:

"background-task-cancelled"

청크 유형 식별자

payload:

BackgroundTaskCancelledPayload

작업의 취소 세부 정보

BackgroundTaskCancelledPayload

taskId:

string

백그라운드 작업의 고유 식별자

toolName:

string

실행된 Tool의 이름

toolCallId:

string

호출을 시작한 LLM Tool 호출의 Tool 호출 ID

runId:

string

작업을 디스패치한 Agent의 실행 ID

agentId:

string

작업을 디스패치한 Agent의 ID

completedAt:

Date

작업이 취소된 시점의 타임스탬프

메타데이터 및 특수 청크

응답 메타데이터

LLM 제공자의 응답에 대한 메타데이터가 포함되어 있습니다. Model ID, 타임스탬프, 응답 헤더와 같은 추가 컨텍스트를 제공하기 위해 텍스트 생성 후 일부 공급자가 내보냅니다. 이 청크는 상태 추적을 위해 내부적으로 사용되며 메시지 어셈블리에는 영향을 주지 않습니다.

type:

"response-metadata"

청크 유형 식별자

payload:

ResponseMetadataPayload

추적 및 디버깅을 위한 Provider 응답 메타데이터

ResponseMetadataPayload

signature?:

string

사용 가능한 경우 응답 서명

[key: string]:

any

Provider별 추가 메타데이터 필드(예: id, modelId, timestamp, headers)

보다

Agent 실행의 모니터링 및 Observability 데이터가 포함됩니다. stream() 사용 방식에 따라 Workflow 상태 정보, 실행 진행률 또는 기타 런타임 세부 정보를 포함할 수 있습니다.

type:

"watch"

청크 유형 식별자

payload:

WatchPayload

Agent 실행의 Observability 및 디버깅을 위한 모니터링 데이터

WatchPayload

workflowState?:

object

현재 Workflow 실행 상태(Workflow에서 사용하는 경우)

eventTimestamp?:

number

이벤트가 발생한 시점의 타임스탬프

[key: string]:

any

추가 모니터링 및 실행 데이터

목표

Agent가 goal을 평가할 때마다 방출됩니다. 소비자는 이를 사용하여 평가 진행 상황과 실행 중간의 결과를 렌더링합니다. 판정 Model이 구성되지 않은 목표에서는 goal 청크가 생성되지 않습니다.

type:

"goal"

청크 유형 식별자

payload:

GoalEvaluationPayload

단일 목표 평가의 결과

GoalEvaluationPayload

objective:

string

판정 중인 목표

iteration:

number

지금까지 소비된 목표 평가 횟수(이 평가 이후의 runsUsed)

maxRuns:

number

목표가 중지되기 전까지의 최대 평가 횟수

passed:

boolean

목표가 완료된 것으로 판정되었는지 여부

status:

"active" | "paused" | "done"

이 평가 이후의 목표 상태

results:

ScorerResult[]

개별 채점기 결과

reason?:

string

판정 피드백 또는 중지 사유

duration:

number

목표 채점 검사에 걸린 총 시간

timedOut:

boolean

채점 시간이 초과되었는지 여부

maxRunsReached:

boolean

실행 예산(maxRuns)에 도달했는지 여부

suppressFeedback:

boolean

목표 피드백 메시지가 Memory에서 숨겨지는지 여부

인계철선

프로세서에 의해 콘텐츠가 차단되어 스트림이 강제로 종료될 때 발생합니다. 이는 유해하거나 부적절한 콘텐츠가 스트리밍되는 것을 방지하는 안전 메커니즘 역할을 합니다. 페이로드에는 콘텐츠가 차단된 이유와 재시도 요청 여부에 대한 정보가 포함됩니다.

type:

"tripwire"

청크 유형 식별자

payload:

TripwirePayload

안전 메커니즘에 의해 스트림이 종료된 이유에 관한 정보

TripwirePayload

reason:

string

콘텐츠가 차단된 이유에 대한 설명(예: 'Output processor blocked content')

retry?:

boolean

프로세서가 단계 재시도를 요청했는지 여부

metadata?:

unknown

프로세서에서 제공한 추가 메타데이터(예: 점수, 범주)

processorId?:

string

트립와이어를 트리거한 프로세서의 ID

사용예

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

관련 유형

• .개울(): 이러한 청크를 방출하는 스트림을 반환하는 메서드
• MastraModel출력: 이러한 청크를 방출하는 스트림 객체
• Workflow.스트림(): Workflow를 위해 이러한 청크를 내보내는 스트림을 반환하는 메서드