chatRoute()

Crée un gestionnaire de route de chat pour diffuser les conversations des Agents au format AI SDK. Cette fonction enregistre un endpoint HTTP POST qui accepte des messages, exécute un Agent et diffuse la réponse au client dans un format compatible avec AI SDK. Vous devez l’utiliser dans une route d’API personnalisée.

Utilisez handleChatStream() si vous avez besoin d’un gestionnaire indépendant du framework.

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

Comportement en cas de déconnexion

chatRoute() transmet l’AbortSignal de la requête entrante à agent.stream(). Si le client se déconnecte, Mastra interrompt la génération en cours.

Si vous souhaitez que le serveur poursuive la génération et conserve la réponse finale après la déconnexion, créez une route d’API personnalisée autour de agent.stream(), puis appelez consumeStream() sur le MastraModelOutput renvoyé.

Exemple d’utilisation

Cet exemple montre comment configurer, sur l’endpoint /chat, une route de chat qui utilise l’Agent dont l’ID est weatherAgent.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { chatRoute } from '@mastra/ai-sdk'

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      chatRoute({
        path: '/chat',
        agent: 'weatherAgent',
      }),
    ],
  },
})

Vous pouvez également définir au moment de l’exécution le routage des Agents à partir d’un agentId. L’URL /chat/weatherAgent sera associée à l’Agent dont l’ID est weatherAgent.

src/mastra/index.ts

import { Mastra } from '@mastra/core'
import { chatRoute } from '@mastra/ai-sdk'

export const mastra = new Mastra({
  server: {
    apiRoutes: [
      chatRoute({
        path: '/chat/:agentId',
      }),
    ],
  },
})

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 existant par défaut. Transmettez 'v6' lorsque votre application est typée pour les utilitaires de réponse d’AI SDK v6.

path:

string

= '/chat/:agentId'

Chemin de la route (par exemple, /chat ou /chat/:agentId). Incluez :agentId pour router les Agents dynamiquement.

agent?:

string

ID de l’Agent à utiliser pour cette route de chat. Obligatoire si le chemin n’inclut pas :agentId.

agentVersion?:

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

Sélectionne une version particulière de l’Agent. Transmettez { versionId: '<id>' } pour cibler une version précise, ou { status: 'draft' } / { status: 'published' } pour la sélectionner d’après son statut. Lorsque la route est appelée, les paramètres de requête ?versionId=<id> ou ?status=draft|published ont priorité sur cette valeur statique. Nécessite la configuration de l’Editor.

defaultOptions?:

AgentExecutionOptions

Options par défaut transmises à l’exécution de l’Agent. Elles peuvent inclure des instructions, la configuration de la mémoire, maxSteps et d’autres paramètres d’exécution.

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.

heartbeatMs?:

number

Intervalle, en millisecondes, entre les signaux d’activité SSE qui maintiennent les connexions actives sur les infrastructures appliquant des délais d’expiration en cas d’inactivité.

Configuration supplémentaire

Vous pouvez utiliser prepareSendMessagesRequest pour personnaliser la requête envoyée à la route de chat, par exemple afin de transmettre une configuration supplémentaire à l’Agent :

const { error, status, sendMessage, messages, regenerate, stop } = useChat({
  transport: new DefaultChatTransport({
    api: 'http://localhost:4111/chat',
    prepareSendMessagesRequest({ messages }) {
      return {
        body: {
          messages,
          // Pass memory config
          memory: {
            thread: 'user-1',
            resource: 'user-1',
          },
        },
      }
    },
  }),
})