MastraModelOutput

La classe MastraModelOutput est renvoyée par .stream() et donne accès aux sorties du modèle à la fois par streaming et par Promise. Elle prend en charge la génération de sorties structurées, les appels de Tool, le raisonnement et le suivi détaillé de l'utilisation.

// MastraModelOutput is returned by agent.stream()
const stream = await agent.stream('Hello world')

Pour la configuration et l'utilisation de base, consultez la documentation de la méthode .stream().

Propriétés de streaming

Ces propriétés donnent accès aux sorties du modèle en temps réel, à mesure de leur génération :

fullStream:

ReadableStream<ChunkType<OUTPUT>>

Stream complet de tous les types de fragments, notamment le texte, les appels de Tool, le raisonnement, les métadonnées et les fragments de contrôle. Fournit un accès précis à chaque aspect de la réponse du modèle.

ReadableStream

ChunkType:

ChunkType<OUTPUT>

Tous les types de fragments pouvant être émis pendant le streaming

textStream:

ReadableStream<string>

Stream contenant uniquement le texte incrémentiel. Filtre toutes les métadonnées, les appels de Tool et les fragments de contrôle afin de fournir seulement le texte en cours de génération.

objectStream:

ReadableStream<Partial<OUTPUT>>

Stream de mises à jour progressives de l'objet structuré lors de l'utilisation de schémas de sortie. Émet des objets partiels à mesure de leur construction, ce qui permet de visualiser en temps réel la génération des données structurées.

ReadableStream

PartialSchemaOutput:

Partial<OUTPUT>

Objet partiellement terminé correspondant au schéma défini

elementStream:

ReadableStream<OUTPUT extends (infer T)[] ? T : never>

Stream des différents éléments du tableau lorsque le schéma de sortie définit un type tableau. Chaque élément est émis dès qu'il est terminé, sans attendre le tableau complet.

Propriétés fondées sur des Promises

Ces propriétés sont résolues avec les valeurs finales une fois le stream terminé :

text:

Promise<string>

Réponse textuelle complète et concaténée du modèle. Résolue une fois la génération du texte terminée.

object:

Promise<OUTPUT>

Réponse complète sous forme d'objet structuré lors de l'utilisation de schémas de sortie. Validée par rapport au schéma avant sa résolution. Rejetée si la validation échoue.

Promise

InferSchemaOutput:

OUTPUT

Objet entièrement typé correspondant exactement à la définition du schéma

reasoning:

Promise<string>

Texte de raisonnement complet pour les modèles prenant en charge le raisonnement, tels que la série o1 d'OpenAI. Renvoie une chaîne vide pour les modèles dépourvus de cette fonctionnalité.

reasoningText:

Promise<string | undefined>

Autre moyen d'accéder au contenu du raisonnement. Peut être undefined pour les modèles qui ne prennent pas en charge le raisonnement, tandis que 'reasoning' renvoie une chaîne vide.

toolCalls:

Promise<ToolCallChunk[]>

Tableau de tous les fragments d'appel de Tool créés pendant l'exécution. Chaque fragment contient les métadonnées du Tool et les détails de l'exécution.

ToolCallChunk

type:

'tool-call'

Identifiant du type de fragment

runId:

string

Identifiant de l'exécution

from:

ChunkFrom

Source du fragment (AGENT, WORKFLOW, etc.)

payload:

ToolCallPayload

Données de l'appel de Tool, notamment toolCallId, toolName, args et les détails de l'exécution

toolResults:

Promise<ToolResultChunk[]>

Tableau de tous les fragments de résultat de Tool correspondant aux appels de Tool. Contient les résultats d'exécution et les informations sur les erreurs.

ToolResultChunk

type:

'tool-result'

Identifiant du type de fragment

runId:

string

Identifiant de l'exécution

from:

ChunkFrom

Source du fragment (AGENT, WORKFLOW, etc.)

payload:

ToolResultPayload

Données du résultat du Tool, notamment toolCallId, toolName, result et l'état d'erreur

usage:

Promise<LanguageModelUsage>

Statistiques d'utilisation des tokens, notamment les tokens d'entrée, de sortie, totaux et de raisonnement pour les modèles de raisonnement.

Record

inputTokens:

number

Tokens consommés par le prompt d'entrée

outputTokens:

number

Tokens générés dans la réponse

totalTokens:

number

Somme des tokens d'entrée et de sortie

reasoningTokens?:

number

Tokens de raisonnement masqués pour les modèles de raisonnement

cachedInputTokens?:

number

Nombre de tokens d'entrée trouvés dans le cache

finishReason:

Promise<string | undefined>

Raison de l'arrêt de la génération (par exemple, 'stop', 'length', 'tool_calls', 'content_filter'). Undefined si le stream n'est pas terminé.

enum

stop:

'stop'

Le modèle a terminé naturellement

length:

'length'

La limite maximale de tokens a été atteinte

tool_calls:

'tool_calls'

Le modèle a appelé des Tools

content_filter:

'content_filter'

Le contenu a été filtré

response:

Promise<Response>

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

Response

id?:

string

Identifiant de réponse du Provider de modèle

timestamp?:

Date

Horodatage de la réponse

modelId?:

string

Identifiant du modèle utilisé pour cette réponse

headers?:

Record<string, string>

En-têtes de réponse du Provider de modèle

messages?:

ResponseMessage[]

Messages de réponse au format du modèle

uiMessages?:

UIMessage[]

Messages de réponse au format de l’interface utilisateur, avec toutes les métadonnées ajoutées par les Processors de sortie

Propriétés d'erreur

error:

string | Error | { message: string; stack: string; } | undefined

Informations sur l'erreur si le stream en a rencontré une. Undefined si aucune erreur ne s'est produite. Il peut s'agir d'un message sous forme de chaîne, d'un objet Error ou d'une erreur sérialisée avec sa stack trace.

Méthodes

getFullOutput:

() => Promise<FullOutput>

Renvoie un objet de sortie complet contenant tous les résultats : texte, objet structuré, appels de Tool, statistiques d'utilisation, raisonnement et métadonnées. Cette méthode unique permet d'accéder facilement à tous les résultats du stream.

FullOutput

text:

string

Réponse textuelle complète

object?:

OUTPUT

Sortie structurée si un schéma a été fourni

toolCalls:

ToolCallChunk[]

Tous les fragments d'appel de Tool créés

toolResults:

ToolResultChunk[]

Tous les fragments de résultat de Tool

usage:

Record<string, number>

Statistiques d'utilisation des tokens

reasoning?:

string

Texte de raisonnement, si disponible

finishReason?:

string

Raison de l'arrêt de la génération

response:

Response

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

consumeStream:

(options?: ConsumeStreamOptions) => Promise<void>

Consomme manuellement l'intégralité du stream sans traiter les fragments. Utile lorsque vous avez seulement besoin des résultats finaux fondés sur des Promises et souhaitez déclencher la consommation du stream.

ConsumeStreamOptions

onError?:

(error: Error) => void

Callback permettant de gérer les erreurs du stream

Exemples d'utilisation

Streaming de texte simple

const stream = await agent.stream('Write a haiku')

// Stream text as it's generated
for await (const text of stream.textStream) {
  process.stdout.write(text)
}

// Or get the complete text
const fullText = await stream.text
console.log(fullText)

Streaming de sortie structurée

const stream = await agent.stream('Generate user data', {
  structuredOutput: {
    schema: z.object({
      name: z.string(),
      age: z.number(),
      email: z.string(),
    }),
  },
})

// Stream partial objects
for await (const partial of stream.objectStream) {
  console.log('Progress:', partial) // { name: "John" }, { name: "John", age: 30 }, ...
}

// Get final validated object
const user = await stream.object
console.log('Final:', user) // { name: "John", age: 30, email: "john@example.com" }

### Tool Calls and Results

```typescript
const stream = await agent.stream("What's the weather in NYC?", {
  tools: { weather: weatherTool }
});

// Monitor tool calls
const toolCalls = await stream.toolCalls;
const toolResults = await stream.toolResults;

console.log("Tools called:", toolCalls);
console.log("Results:", toolResults);

Accès à la sortie complète

const stream = await agent.stream('Analyze this data')

const output = await stream.getFullOutput()
console.log({
  text: output.text,
  usage: output.usage,
  reasoning: output.reasoning,
  finishReason: output.finishReason,
})

Traitement du stream complet

const stream = await agent.stream('Complex task')

for await (const chunk of stream.fullStream) {
  switch (chunk.type) {
    case 'text-delta':
      process.stdout.write(chunk.payload.text)
      break
    case 'tool-call':
      console.log(`Calling ${chunk.payload.toolName}...`)
      break
    case 'reasoning-delta':
      console.log(`Reasoning: ${chunk.payload.text}`)
      break
    case 'finish':
      console.log(`Done! Reason: ${chunk.payload.stepResult.reason}`)
      // Access response messages with any metadata added by output processors
      const uiMessages = chunk.payload.response?.uiMessages
      if (uiMessages) {
        console.log('Response messages:', uiMessages)
      }
      break
  }
}

Gestion des erreurs

const stream = await agent.stream('Analyze this data')

try {
  // Option 1: Handle errors in consumeStream
  await stream.consumeStream({
    onError: error => {
      console.error('Stream error:', error)
    },
  })

  const result = await stream.text
} catch (error) {
  console.error('Failed to get result:', error)
}

// Option 2: Check error property
const result = await stream.getFullOutput()
if (stream.error) {
  console.error('Stream had errors:', stream.error)
}

Types associés

• .stream() : méthode qui renvoie MastraModelOutput
• ChunkType : tous les types de fragments possibles dans le stream complet