> Discover all available pages from the documentation index: https://mastra.zisheng.pro/fr/llms.txt

# 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](https://mastra.zisheng.pro/fr/docs/server/custom-api-routes) de Mastra.

`handleChatStream()` renvoie un `ReadableStream` que vous pouvez encapsuler avec [`createUIMessageStreamResponse()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/create-ui-message-stream-response).

`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()`](https://mastra.zisheng.pro/fr/reference/ai-sdk/chat-route) 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 :

```json
{
  "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 :

```typescript
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'`): 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. (Default: `'v5'`)

**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`): Indique si les événements de début doivent être envoyés dans le flux. (Default: `true`)

**sendFinish** (`boolean`): Indique si les événements de fin doivent être envoyés dans le flux. (Default: `true`)

**sendReasoning** (`boolean`): Indique si les étapes de raisonnement doivent être incluses dans le flux. (Default: `false`)

**sendSources** (`boolean`): Indique si les citations des sources doivent être incluses dans le flux. (Default: `false`)

**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.