handleChatStream()

Gestionnaire indépendant de tout framework permettant de diffuser en streaming les conversations d'un Agent dans un format compatible avec AI SDK. Utilisez cette fonction directement lorsque vous devez gérer le streaming d'une conversation en dehors de Hono ou de la fonctionnalité apiRoutes de Mastra.

handleChatStream() renvoie un ReadableStream que vous pouvez encapsuler avec createUIMessageStreamResponse().

handleChatStream() conserve le comportement existant par défaut d'AI SDK v5. Si votre application est typée pour AI SDK v6, transmettez version: 'v6'.

Utilisez chatRoute() si vous souhaitez créer une route de conversation dans un serveur Mastra.

Sortie structurée dans les flux d'interface utilisateur

Lorsque vous transmettez structuredOutput à l'exécution sous-jacente de l'Agent, l'objet de sortie structurée final est émis dans le flux d'interface utilisateur compatible avec AI SDK sous la forme d'une partie de données personnalisée :

{
  "type": "data-structured-output",
  "data": {
    "object": {}
  }
}

Le champ object contient la valeur complète de votre sortie structurée. Mastra émet cet événement uniquement pour l'objet de sortie structurée final. Les segments partiels de la sortie structurée ne sont pas exposés dans le flux d'interface utilisateur.

Lisez cet événement au moyen de la gestion des données personnalisées d'AI SDK UI, par exemple avec onData, ou affichez-le à partir des parties de données du message.

Exemple d'utilisation

Exemple avec l'App Router de Next.js :

app/api/chat/route.ts

import { handleChatStream } from '@mastra/ai-sdk'
import { createUIMessageStreamResponse } from 'ai'
import { mastra } from '@/src/mastra'

export async function POST(req: Request) {
  const params = await req.json()
  const stream = await handleChatStream({
    mastra,
    agentId: 'weatherAgent',
    params,
    messageMetadata: () => ({ createdAt: new Date().toISOString() }),
  })
  return createUIMessageStreamResponse({ stream })
}

Paramètres

version?:

'v5' | 'v6'

= 'v5'

Sélectionne le contrat de flux AI SDK à émettre. Omettez cette option ou transmettez 'v5' pour conserver le comportement par défaut existant. Transmettez 'v6' lorsque votre application est typée pour les fonctions utilitaires de réponse d'AI SDK v6.

mastra:

Mastra

Instance Mastra contenant les Agents enregistrés.

agentId:

string

Identifiant de l'Agent à utiliser pour la conversation.

agentVersion?:

{ versionId: string } | { status?: 'draft' | 'published' }

Sélectionne une version précise de l'Agent. Transmettez { versionId: '<id>' } pour cibler une version exacte, ou { status: 'draft' } / { status: 'published' } pour effectuer la résolution selon le statut. Nécessite la configuration de l'Editor.

params:

ChatStreamHandlerParams

Paramètres du flux de conversation, notamment les messages et les données de reprise facultatives.

params.messages:

UIMessage[]

Tableau des messages de la conversation.

params.resumeData?:

Record<string, any>

Données permettant de reprendre l'exécution suspendue d'un Agent. Nécessite la définition de runId.

params.runId?:

string

Identifiant de l'exécution. Obligatoire lorsque resumeData est fourni.

params.providerOptions?:

Record<string, Record<string, unknown>>

Options propres au Provider transmises au modèle de langage (par exemple, { openai: { reasoningEffort: "high" } }). Elles sont fusionnées avec defaultOptions.providerOptions, les valeurs de params étant prioritaires.

params.requestContext?:

RequestContext

Contexte de requête à transmettre à l'exécution de l'Agent.

defaultOptions?:

AgentExecutionOptions

Options par défaut transmises à l'exécution de l'Agent. Elles sont fusionnées avec params, les valeurs de params étant prioritaires.

sendStart?:

boolean

= true

Indique si les événements de début doivent être envoyés dans le flux.

sendFinish?:

boolean

= true

Indique si les événements de fin doivent être envoyés dans le flux.

sendReasoning?:

boolean

= false

Indique si les étapes de raisonnement doivent être incluses dans le flux.

sendSources?:

boolean

= false

Indique si les citations des sources doivent être incluses dans le flux.

onError?:

(error: unknown) => string

Appelée lorsque le flux rencontre une erreur. Renvoyez la chaîne qui sera envoyée au client comme message d'erreur. Utilisez cette fonction pour nettoyer les erreurs avant qu'elles n'atteignent le client, par exemple pour empêcher la divulgation de détails sur l'infrastructure interne aux utilisateurs finaux.

messageMetadata?:

(options: { part: UIMessageStreamPart }) => Record<string, unknown> | undefined

Fonction qui reçoit la partie actuelle du flux et renvoie les métadonnées à joindre aux segments de début et de fin. Pour en savoir plus, consultez la documentation d'AI SDK sur les métadonnées des messages.