ChunkType

Le type ChunkType définit le format Mastra des fragments de flux pouvant être émis pendant les réponses diffusées des Agents.

Propriétés de base

Tous les fragments comprennent les propriétés de base suivantes :

type:

string

Identifiant précis du type de fragment

runId:

string

Identifiant unique de cette exécution

from:

ChunkFrom

Source du fragment

enum

AGENT:

'AGENT'

Fragment issu de l’exécution de l’Agent

USER:

'USER'

Fragment issu de l’entrée utilisateur

SYSTEM:

'SYSTEM'

Fragment issu des processus système

WORKFLOW:

'WORKFLOW'

Fragment issu de l’exécution du Workflow

Fragments de texte

text-start

Signale le début de la génération de texte.

type:

"text-start"

Identifiant du type de fragment

payload:

TextStartPayload

Informations sur le début du texte

TextStartPayload

id:

string

Identifiant unique de cette génération de texte

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

text-delta

Contenu textuel incrémentiel pendant la génération.

type:

"text-delta"

Identifiant du type de fragment

payload:

TextDeltaPayload

Contenu textuel incrémentiel

TextDeltaPayload

id:

string

Identifiant unique de cette génération de texte

text:

string

Contenu textuel incrémentiel

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

text-end

Signale la fin de la génération de texte.

type:

"text-end"

Identifiant du type de fragment

payload:

TextEndPayload

Informations sur la fin du texte

TextEndPayload

id:

string

Identifiant unique de cette génération de texte

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

Fragments de raisonnement

reasoning-start

Signale le début de la génération du raisonnement pour les modèles qui prennent en charge cette fonctionnalité.

type:

"reasoning-start"

Identifiant du type de fragment

payload:

ReasoningStartPayload

Informations sur le début du raisonnement

ReasoningStartPayload

id:

string

Identifiant unique de cette génération de raisonnement

signature?:

string

Signature du raisonnement, si elle est disponible

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

reasoning-delta

Texte de raisonnement incrémentiel pendant la génération.

type:

"reasoning-delta"

Identifiant du type de fragment

payload:

ReasoningDeltaPayload

Contenu de raisonnement incrémentiel

ReasoningDeltaPayload

id:

string

Identifiant unique de cette génération de raisonnement

text:

string

Texte de raisonnement incrémentiel

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

reasoning-end

Signale la fin de la génération du raisonnement.

type:

"reasoning-end"

Identifiant du type de fragment

payload:

ReasoningEndPayload

Informations sur la fin du raisonnement

ReasoningEndPayload

id:

string

Identifiant unique de cette génération de raisonnement

signature?:

string

Signature finale du raisonnement, si elle est disponible

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

reasoning-signature

Contient la signature de raisonnement des modèles prenant en charge le raisonnement avancé, tels que la série o1 d’OpenAI. La signature représente des métadonnées sur le processus de raisonnement interne du modèle, comme le niveau d’effort ou l’approche de raisonnement, mais pas le contenu du raisonnement lui-même.

type:

"reasoning-signature"

Identifiant du type de fragment

payload:

ReasoningSignaturePayload

Métadonnées sur les caractéristiques du processus de raisonnement du modèle

ReasoningSignaturePayload

id:

string

Identifiant unique de la session de raisonnement

signature:

string

Signature décrivant l’approche ou le niveau d’effort de raisonnement, par exemple les paramètres d’effort de raisonnement

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

Fragments de Tool

tool-call

Un Tool est en cours d’appel.

type:

"tool-call"

Identifiant du type de fragment

payload:

ToolCallPayload

Informations sur l’appel du Tool

ToolCallPayload

toolCallId:

string

Identifiant unique de cet appel de Tool

toolName:

string

Nom du Tool appelé

args?:

Record<string, any>

Arguments transmis au Tool

providerExecuted?:

boolean

Indique si le Provider a exécuté le Tool

output?:

any

Sortie du Tool, si elle est disponible

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

tool-result

Résultat de l’exécution d’un Tool.

type:

"tool-result"

Identifiant du type de fragment

payload:

ToolResultPayload

Résultat de l’exécution du Tool

ToolResultPayload

toolCallId:

string

Identifiant unique de l’appel du Tool

toolName:

string

Nom du Tool exécuté

result:

any

Résultat de l’exécution du Tool

isError?:

boolean

Indique si le résultat est une erreur

providerExecuted?:

boolean

Indique si le Provider a exécuté le Tool

args?:

Record<string, any>

Arguments qui ont été transmis au Tool

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

tool-call-input-streaming-start

Signale le début de la diffusion des arguments de l’appel du Tool.

type:

"tool-call-input-streaming-start"

Identifiant du type de fragment

payload:

ToolCallInputStreamingStartPayload

Informations sur le début de la diffusion de l’entrée de l’appel du Tool

ToolCallInputStreamingStartPayload

toolCallId:

string

Identifiant unique de cet appel de Tool

toolName:

string

Nom du Tool appelé

providerExecuted?:

boolean

Indique si le Provider a exécuté le Tool

dynamic?:

boolean

Indique si l’appel du Tool est dynamique

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

tool-call-delta

Arguments incrémentiels de l’appel du Tool pendant la diffusion.

type:

"tool-call-delta"

Identifiant du type de fragment

payload:

ToolCallDeltaPayload

Arguments incrémentiels de l’appel du Tool

ToolCallDeltaPayload

argsTextDelta:

string

Delta de texte incrémentiel pour les arguments du Tool

toolCallId:

string

Identifiant unique de cet appel de Tool

toolName?:

string

Nom du Tool appelé

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

tool-call-input-streaming-end

Signale la fin de la diffusion des arguments de l’appel du Tool.

type:

"tool-call-input-streaming-end"

Identifiant du type de fragment

payload:

ToolCallInputStreamingEndPayload

Informations sur la fin de la diffusion de l’entrée de l’appel du Tool

ToolCallInputStreamingEndPayload

toolCallId:

string

Identifiant unique de cet appel de Tool

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

tool-error

Une erreur est survenue pendant l’exécution du Tool.

type:

"tool-error"

Identifiant du type de fragment

payload:

ToolErrorPayload

Informations sur l’erreur du Tool

ToolErrorPayload

id?:

string

Identifiant facultatif

toolCallId:

string

Identifiant unique de l’appel du Tool

toolName:

string

Nom du Tool ayant échoué

args?:

Record<string, any>

Arguments qui ont été transmis au Tool

error:

unknown

Erreur survenue

providerExecuted?:

boolean

Indique si le Provider a exécuté le Tool

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

Fragments de source et de fichier

source

Contient les informations sur la source du contenu.

type:

"source"

Identifiant du type de fragment

payload:

SourcePayload

Informations sur la source

SourcePayload

id:

string

Identifiant unique

sourceType:

'url' | 'document'

Type de source

title:

string

Titre de la source

mimeType?:

string

Type MIME de la source

filename?:

string

Nom du fichier, le cas échéant

url?:

string

URL, le cas échéant

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

file

Contient les données du fichier.

type:

"file"

Identifiant du type de fragment

payload:

FilePayload

Données du fichier

FilePayload

data:

string | Uint8Array

Données du fichier

base64?:

string

Données encodées en base64, le cas échéant

mimeType:

string

Type MIME du fichier

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

Fragments de contrôle

start

Signale le début de la diffusion.

type:

"start"

Identifiant du type de fragment

payload:

StartPayload

Informations sur le démarrage

StartPayload

[key: string]:

any

Données de démarrage supplémentaires

step-start

Signale le début d’une étape de traitement.

type:

"step-start"

Identifiant du type de fragment

payload:

StepStartPayload

Informations sur le début de l’étape

StepStartPayload

messageId?:

string

Identifiant de message facultatif

request:

object

Informations sur la requête, notamment son corps et d’autres données

warnings?:

LanguageModelV2CallWarning[]

Avertissements éventuels provenant de l’appel au modèle de langage

step-finish

Signale la fin d’une étape de traitement.

type:

"step-finish"

Identifiant du type de fragment

payload:

StepFinishPayload

Informations sur la fin de l’étape

StepFinishPayload

id?:

string

Identifiant facultatif

messageId?:

string

Identifiant de message facultatif

stepResult:

object

Résultat de l’exécution de l’étape avec le motif, les avertissements et les informations de poursuite

output:

object

Informations de sortie, notamment les statistiques d’utilisation

metadata:

object

Métadonnées d’exécution, notamment les informations sur la requête et le Provider

totalUsage?:

LanguageModelV2Usage

Statistiques d’utilisation totales

response?:

LanguageModelV2ResponseMetadata

Métadonnées de la réponse

providerMetadata?:

SharedV2ProviderMetadata

Métadonnées propres au Provider

raw

Contient les données brutes provenant du Provider.

type:

"raw"

Identifiant du type de fragment

payload:

RawPayload

Données brutes du Provider

RawPayload

[key: string]:

any

Données brutes provenant du Provider

finish

Le flux s’est terminé correctement.

type:

"finish"

Identifiant du type de fragment

payload:

FinishPayload

Informations sur la fin de l’exécution

FinishPayload

stepResult:

object

Résultat de l’exécution de l’étape

output:

object

Informations de sortie, notamment l’utilisation

metadata:

object

Métadonnées d’exécution

messages:

object

Historique des messages

response:

object

Métadonnées de la réponse et messages provenant du Provider de modèle

error

Une erreur est survenue pendant la diffusion.

type:

"error"

Identifiant du type de fragment

payload:

ErrorPayload

Informations sur l’erreur

ErrorPayload

error:

unknown

Erreur survenue

abort

Le flux a été interrompu.

type:

"abort"

Identifiant du type de fragment

payload:

AbortPayload

Informations sur l’interruption

AbortPayload

[key: string]:

any

Données d’interruption supplémentaires

Fragments d’objet et de sortie

object

Émis lors de l’utilisation d’une génération de sortie avec des schémas définis. Contient des données structurées partielles ou complètes conformes au schéma Zod ou JSON indiqué. Ce fragment est généralement ignoré dans certains contextes d’exécution et sert à diffuser la génération d’objets structurés.

type:

"object"

Identifiant du type de fragment

object:

Partial<OUTPUT>

Données structurées partielles ou complètes correspondant au schéma défini. Le type est déterminé par le paramètre de schéma OUTPUT.

tool-output

Contient la sortie de l’exécution d’un Agent ou d’un Workflow, notamment pour suivre les statistiques d’utilisation et les événements de fin. Encapsule souvent d’autres types de fragments, tels que les fragments finish, afin de fournir un contexte d’exécution imbriqué.

type:

"tool-output"

Identifiant du type de fragment

payload:

ToolOutputPayload

Sortie d’exécution encapsulée avec ses métadonnées

ToolOutputPayload

output:

ChunkType

Données du fragment imbriqué, contenant souvent des événements de fin accompagnés de statistiques d’utilisation

step-output

Contient la sortie de l’exécution d’une étape de Workflow, principalement utilisée pour suivre l’utilisation et les événements de fin d’étape. Similaire à tool-output, mais propre aux différentes étapes du Workflow.

type:

"step-output"

Identifiant du type de fragment

payload:

StepOutputPayload

Sortie de l’exécution de l’étape du Workflow avec ses métadonnées

StepOutputPayload

output:

ChunkType

Données du fragment imbriqué provenant de l’exécution de l’étape, contenant généralement des événements de fin ou d’autres résultats d’étape

Fragments de tâche en arrière-plan

Émis lorsqu’un appel de Tool est envoyé comme tâche en arrière-plan et que streamUntilIdle() est utilisé.

background-task-started

Émis lorsqu’un appel de Tool est mis en file d’attente comme tâche en arrière-plan et reçoit un taskId.

type:

"background-task-started"

Identifiant du type de fragment

payload:

BackgroundTaskStartedPayload

Identifie la tâche nouvellement mise en file d’attente

BackgroundTaskStartedPayload

taskId:

string

Identifiant unique de la tâche en arrière-plan

toolName:

string

Nom du Tool en cours d’exécution

toolCallId:

string

ID de l’appel de Tool provenant de l’appel initial effectué par le LLM

background-task-running

Émis lorsqu’un Worker prend en charge la tâche et que l’exécution commence.

type:

"background-task-running"

Identifiant du type de fragment

payload:

BackgroundTaskRunningPayload

Détails sur la tâche en cours d’exécution

BackgroundTaskRunningPayload

taskId:

string

Identifiant unique de la tâche en arrière-plan

toolName:

string

Nom du Tool en cours d’exécution

toolCallId:

string

ID de l’appel de Tool provenant de l’appel initial effectué par le LLM

runId:

string

ID de l’exécution de l’Agent ayant envoyé la tâche

agentId:

string

ID de l’Agent ayant envoyé la tâche

startedAt:

Date

Horodatage du début de l’exécution

args:

Record<string, unknown>

Arguments transmis à la fonction execute du Tool

background-task-progress

Instantané périodique du nombre de tâches en arrière-plan actuellement en cours d’exécution dans l’Agent.

type:

"background-task-progress"

Identifiant du type de fragment

payload:

BackgroundTaskProgressPayload

Progression agrégée de toutes les tâches en cours d’exécution

BackgroundTaskProgressPayload

taskIds:

string[]

ID de toutes les tâches en arrière-plan actuellement en cours d’exécution

runningCount:

number

Nombre de tâches en arrière-plan actuellement en cours d’exécution

elapsedMs:

number

Nombre de millisecondes écoulées depuis le début de l’exécution de l’Agent

background-task-output

Fragment de sortie diffusé par la fonction execute de la tâche. Encapsule un fragment interne tool-output.

type:

"background-task-output"

Identifiant du type de fragment

payload:

BackgroundTaskOutputPayload

Sortie diffusée de la tâche en cours d’exécution

BackgroundTaskOutputPayload

taskId:

string

Identifiant unique de la tâche en arrière-plan

toolName:

string

Nom du Tool en cours d’exécution

toolCallId:

string

ID de l’appel de Tool provenant de l’appel initial effectué par le LLM

runId:

string

ID de l’exécution de l’Agent ayant envoyé la tâche

agentId:

string

ID de l’Agent ayant envoyé la tâche

payload:

ToolOutputChunk

Fragment tool-output interne produit par la tâche

background-task-completed

Émis lorsque la tâche se termine correctement. Déclenche un tour de poursuite lorsqu’il est consommé par Agent.streamUntilIdle().

type:

"background-task-completed"

Identifiant du type de fragment

payload:

BackgroundTaskResultPayload

Résultat de la tâche terminée

BackgroundTaskResultPayload

taskId:

string

Identifiant unique de la tâche en arrière-plan

toolName:

string

Nom du Tool qui a été exécuté

toolCallId:

string

ID de l’appel de Tool provenant de l’appel initial effectué par le LLM

agentId:

string

ID de l’Agent ayant envoyé la tâche

runId:

string

ID de l’exécution de l’Agent ayant envoyé la tâche

result:

unknown

Valeur de retour résolue du Tool

completedAt:

Date

Horodatage de la fin de la tâche

isError?:

boolean

Vrai lorsque le Tool a renvoyé un résultat d’erreur au lieu de lever une erreur

background-task-failed

Émis lorsque la tâche lève une erreur ou expire. Déclenche un tour de poursuite lorsqu’il est consommé par Agent.streamUntilIdle().

type:

"background-task-failed"

Identifiant du type de fragment

payload:

BackgroundTaskFailedPayload

Détails sur l’échec de la tâche

BackgroundTaskFailedPayload

taskId:

string

Identifiant unique de la tâche en arrière-plan

toolName:

string

Nom du Tool qui a été exécuté

toolCallId:

string

ID de l’appel de Tool provenant de l’appel initial effectué par le LLM

runId:

string

ID de l’exécution de l’Agent ayant envoyé la tâche

agentId:

string

ID de l’Agent ayant envoyé la tâche

error:

{ message: string }

Détails de l’erreur levée par la tâche

completedAt:

Date

Horodatage de l’échec de la tâche

background-task-suspended

Émis lorsqu’un Tool appelle suspend() depuis son exécution en arrière-plan. Suspend l’exécution du Workflow de la tâche tout en persistant son instantané. Reprenez-la avec mastra.backgroundTaskManager.resume(taskId, resumeData).

Lorsqu’il est consommé par Agent.streamUntilIdle(), ce fragment retire la tâche de l’ensemble d’attente de la boucle sans mettre de poursuite en file d’attente. La réponse de l’Agent se termine, puis l’achèvement ultérieur de la tâche reprise est injecté dans la liste des messages pour le prochain tour de l’utilisateur.

type:

"background-task-suspended"

Identifiant du type de fragment

payload:

BackgroundTaskSuspendedPayload

Détails sur la suspension de la tâche

BackgroundTaskSuspendedPayload

taskId:

string

Identifiant unique de la tâche en arrière-plan

toolName:

string

Nom du Tool qui a été exécuté

toolCallId:

string

ID de l’appel de Tool provenant de l’appel initial effectué par le LLM

runId:

string

ID de l’exécution de l’Agent ayant envoyé la tâche

agentId:

string

ID de l’Agent ayant envoyé la tâche

suspendData?:

unknown

Valeur transmise par le Tool à suspend(data)

background-task-resumed

Émis lorsqu’une tâche suspendue est reprise via mastra.backgroundTaskManager.resume(taskId, resumeData). La tâche repasse à l’état running et la fonction execute du Tool redémarre avec resumeData renseigné.

type:

"background-task-resumed"

Identifiant du type de fragment

payload:

BackgroundTaskResumedPayload

Détails sur la reprise de la tâche

BackgroundTaskResumedPayload

taskId:

string

Identifiant unique de la tâche en arrière-plan

toolName:

string

Nom du Tool qui a été exécuté

toolCallId:

string

ID de l’appel de Tool provenant de l’appel initial effectué par le LLM

runId:

string

ID de l’exécution de l’Agent ayant envoyé la tâche

agentId:

string

ID de l’Agent ayant envoyé la tâche

startedAt:

Date

Horodatage de la reprise de la tâche

args:

Record<string, unknown>

Arguments d’origine du Tool

background-task-cancelled

Émis lorsque la tâche est annulée avant sa fin. Déclenche un tour de poursuite lorsqu’il est consommé par Agent.streamUntilIdle().

type:

"background-task-cancelled"

Identifiant du type de fragment

payload:

BackgroundTaskCancelledPayload

Détails sur l’annulation de la tâche

BackgroundTaskCancelledPayload

taskId:

string

Identifiant unique de la tâche en arrière-plan

toolName:

string

Nom du Tool qui a été exécuté

toolCallId:

string

ID de l’appel de Tool provenant de l’appel initial effectué par le LLM

runId:

string

ID de l’exécution de l’Agent ayant envoyé la tâche

agentId:

string

ID de l’Agent ayant envoyé la tâche

completedAt:

Date

Horodatage de l’annulation de la tâche

Métadonnées et fragments spéciaux

response-metadata

Contient des métadonnées sur la réponse du Provider de LLM. Émis par certains Providers après la génération du texte pour fournir un contexte supplémentaire, comme l’ID du modèle, les horodatages et les en-têtes de réponse. Ce fragment est utilisé en interne pour suivre l’état et n’affecte pas l’assemblage des messages.

type:

"response-metadata"

Identifiant du type de fragment

payload:

ResponseMetadataPayload

Métadonnées de la réponse du Provider pour le suivi et le débogage

ResponseMetadataPayload

signature?:

string

Signature de la réponse, si elle est disponible

[key: string]:

any

Champs de métadonnées supplémentaires propres au Provider, par exemple id, modelId, timestamp et headers

watch

Contient des données de surveillance et d’observabilité provenant de l’exécution de l’Agent. Peut inclure des informations sur l’état du Workflow, la progression de l’exécution ou d’autres détails du runtime selon le contexte dans lequel stream() est utilisé.

type:

"watch"

Identifiant du type de fragment

payload:

WatchPayload

Données de surveillance pour l’observabilité et le débogage de l’exécution de l’Agent

WatchPayload

workflowState?:

object

État actuel de l’exécution du Workflow, lorsqu’il est utilisé dans des Workflows

eventTimestamp?:

number

Horodatage de l’événement

[key: string]:

any

Données supplémentaires de surveillance et d’exécution

goal

Émis à chaque évaluation d’un objectif de l’Agent. Les consommateurs l’utilisent pour afficher la progression du juge et le résultat pendant l’exécution. Un objectif sans modèle de juge configuré ne produit aucun fragment goal.

type:

"goal"

Identifiant du type de fragment

payload:

GoalEvaluationPayload

Résultat d’une évaluation de l’objectif

GoalEvaluationPayload

objective:

string

Objectif en cours d’évaluation

iteration:

number

Évaluations de l’objectif consommées jusqu’à présent (runsUsed après cette évaluation)

maxRuns:

number

Nombre maximal d’évaluations avant l’arrêt de l’objectif

passed:

boolean

Indique si l’objectif est considéré comme atteint

status:

"active" | "paused" | "done"

État de l’objectif après cette évaluation

results:

ScorerResult[]

Résultats individuels des Scorers

reason?:

string

Retour du juge ou motif d’arrêt

duration:

number

Durée totale de la vérification du scoring de l’objectif

timedOut:

boolean

Indique si le scoring a expiré

maxRunsReached:

boolean

Indique si le budget d’exécution (maxRuns) a été atteint

suppressFeedback:

boolean

Indique si le message de retour sur l’objectif est supprimé de la Memory

tripwire

Émis lorsque le flux est interrompu de force parce qu’un Processor a bloqué le contenu. Il agit comme un mécanisme de sécurité empêchant la diffusion de contenu nuisible ou inapproprié. Le payload indique pourquoi le contenu a été bloqué et si une nouvelle tentative a été demandée.

type:

"tripwire"

Identifiant du type de fragment

payload:

TripwirePayload

Informations expliquant pourquoi le flux a été interrompu par les mécanismes de sécurité

TripwirePayload

reason:

string

Explication de la raison pour laquelle le contenu a été bloqué, par exemple « Output processor blocked content »

retry?:

boolean

Indique si le Processor a demandé une nouvelle tentative de l’étape

metadata?:

unknown

Métadonnées supplémentaires du Processor, par exemple les scores et les catégories

processorId?:

string

ID du Processor ayant déclenché le tripwire

Exemple d’utilisation

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

Types associés

• .stream() : méthode qui renvoie des flux émettant ces fragments
• MastraModelOutput : objet de flux qui émet ces fragments
• workflow.stream() : méthode qui renvoie des flux émettant ces fragments pour les Workflows