Voix xAI Realtime

La classe XAIRealtimeVoice fournit des fonctionnalités d’interaction vocale en temps réel à l’aide de l’API xAI Grok Voice Agent. Elle implémente le contrat temps réel MastraVoice de Mastra et prend en charge le streaming audio bidirectionnel, les tours de texte, la VAD côté serveur, les voix xAI, les Tools de fonction et les Tools xAI côté serveur.

Exemple d’utilisation

import { Agent } from '@mastra/core/agent'
import { getMicrophoneStream, playAudio } from '@mastra/node-audio'
import { XAIRealtimeVoice } from '@mastra/voice-xai-realtime'

const voice = new XAIRealtimeVoice({
  apiKey: process.env.XAI_API_KEY,
  model: 'grok-voice-think-fast-1.0',
  speaker: 'eve',
  instructions: 'You are a concise voice assistant.',
  turnDetection: { type: 'server_vad' },
})

const agent = new Agent({
  id: 'voice-agent',
  name: 'Voice Agent',
  instructions: 'You are a helpful voice assistant.',
  model: 'xai/grok-4.3',
  voice,
})

await agent.voice.connect()

agent.voice.on('speaker', audioStream => {
  playAudio(audioStream)
})

agent.voice.on('writing', ({ text, role }) => {
  console.log(`${role}: ${text}`)
})

await agent.voice.speak('How can I help you today?')

const microphoneStream = getMicrophoneStream()
await agent.voice.send(microphoneStream)

agent.voice.close()

Configuration

Options du constructeur

apiKey?:

string

Clé d’API xAI. Utilise la variable d’environnement XAI_API_KEY comme valeur de repli.

ephemeralToken?:

string

Token xAI de courte durée envoyé avec le protocole WebSocket au lieu d’un en-tête d’autorisation.

model?:

XAIRealtimeModel

= 'grok-voice-think-fast-1.0'

Modèle vocal Grok à utiliser.

speaker?:

XAIVoice

= 'eve'

ID de voix à utiliser pour la sortie vocale. Les valeurs intégrées sont eve, ara, rex, sal et leo. Les ID de voix xAI personnalisés sont également pris en charge.

instructions?:

string

Instructions système envoyées dans session.update.

turnDetection?:

XAITurnDetection

= { type: 'server_vad' }

Configuration de la détection d’activité vocale.

audio?:

XAIAudioConfig

= Entrée et sortie audio/pcm à 24 kHz

Configuration des formats audio d’entrée et de sortie.

serverTools?:

XAIServerTool[]

Tools xAI côté serveur à envoyer dans session.update. Prend en charge file_search, web_search, x_search et mcp. Ils sont fusionnés avec session.tools.

session?:

Partial<XAISessionConfig>

Champs de session xAI supplémentaires à fusionner dans l’événement session.update initial.

url?:

string

= 'wss://api.x.ai/v1/realtime'

Remplace l’URL WebSocket xAI Realtime.

debug?:

boolean

= false

Active les logs de débogage pour les événements xAI reçus. Ces logs peuvent inclure les transcriptions et les arguments des appels de Tools.

Modèle VoiceConfig

Vous pouvez également utiliser la structure de configuration vocale partagée de Mastra :

const voice = new XAIRealtimeVoice({
  speaker: 'ara',
  realtimeConfig: {
    model: 'grok-voice-think-fast-1.0',
    apiKey: process.env.XAI_API_KEY,
    options: {
      instructions: 'Answer briefly.',
      turnDetection: { type: 'server_vad', threshold: 0.85 },
    },
  },
})

Authentification

Utilisez apiKey ou XAI_API_KEY pour les applications côté serveur. Ce Provider est conçu pour les environnements d’exécution Node.js côté serveur. Si vous générez déjà des tokens éphémères xAI sur votre serveur, vous pouvez en transmettre un comme ephemeralToken ; le Provider utilise alors le protocole WebSocket xai-client-secret.<token> au lieu d’un en-tête d’autorisation. Si apiKey et ephemeralToken sont tous deux configurés, le Provider utilise le token éphémère.

Méthodes

connect()

Établit la connexion WebSocket et envoie le session.update initial.

requestContext?:

RequestContext

Contexte de requête Mastra facultatif transmis aux exécutions de Tools de fonction.

Renvoie : Promise<void>

close()

Ferme la connexion WebSocket, termine les flux de locuteur actifs et efface les événements en file d’attente, l’état des appels de fonction en attente et le contexte de requête. disconnect() est un alias de close().

Renvoie : void

addInstructions()

Définit les instructions de la session. Si la connexion WebSocket est ouverte, le Provider envoie un session.update. La transmission de undefined stocke une chaîne vide et efface les instructions actives de la session actuelle ou de la connexion suivante.

instructions?:

string

Instructions système à envoyer à xAI.

Renvoie : void

addTools()

Enregistre les Tools de fonction Mastra et, lorsque la connexion est établie, actualise les Tools de la session avec session.update.

tools?:

ToolsInput

Tools Mastra à exposer comme Tools de fonction xAI.

Renvoie : void

updateConfig()

Envoie un événement session.update contenant des champs de session xAI supplémentaires.

sessionConfig:

Partial<XAISessionConfig>

Champs de session à mettre à jour.

Renvoie : void

speak()

Envoie un tour de texte à l’aide de conversation.item.create, puis demande une réponse.

input:

string | NodeJS.ReadableStream

Texte ou flux de texte lisible à envoyer comme entrée utilisateur.

options.speaker?:

XAIVoice

Remplacement de la voix. Met à jour la voix de la session xAI active, qui sera utilisée pour les tours suivants.

options.response?:

Record<string, unknown>

Champs xAI response.create supplémentaires.

Renvoie : Promise<void>

send()

Envoie des fragments audio en streaming et en temps réel avec input_audio_buffer.append.

send() nécessite une connexion ouverte. Utilisez-la pour l’audio en direct d’un microphone après la résolution de connect(). Les fragments du flux lisible doivent être des fragments audio binaires (Buffer, ArrayBuffer ou un tableau typé).

audioData:

NodeJS.ReadableStream | Int16Array

Flux audio PCM ou données audio Int16Array.

eventId?:

string

ID facultatif de l’événement xAI.

Renvoie : Promise<void>

listen()

Envoie un flux audio fini avec input_audio_buffer.append. Par défaut, valide le tampon d’entrée et demande une réponse.

audioData:

NodeJS.ReadableStream

Flux audio à envoyer.

options.commit?:

boolean

= true

Indique s’il faut envoyer input_audio_buffer.commit après l’élément audio.

options.createResponse?:

boolean

= true

Indique s’il faut envoyer response.create après l’élément audio.

Renvoie : Promise<void>

answer()

Envoie response.create pour demander à xAI de poursuivre la conversation.

Renvoie : Promise<void>

commitAudioBuffer() and clearAudioBuffer()

Envoient les événements client xAI Realtime correspondants pour permettre un contrôle manuel des tours.

Renvoie : Promise<void>

cancelResponse()

Envoie response.cancel pour interrompre une réponse en cours.

responseId?:

string

ID facultatif de la réponse xAI à annuler.

eventId?:

string

ID facultatif de l’événement xAI.

Renvoie : Promise<void>

Événements

XAIRealtimeVoice associe les événements du serveur xAI Realtime aux événements vocaux Mastra :

• speaker : émet un flux lisible pour l’audio de l’assistant.
• speaking : émet les deltas audio de l’assistant.
• speaking.done : émet un événement lorsque la réponse audio de l’assistant se termine.
• writing : émet les deltas de texte de l’assistant et les transcriptions de l’entrée utilisateur.
• error : émet les erreurs d’exécution xAI et du Provider. Émet également les erreurs d’exécution des Tools et les arguments mal formés des appels de fonction. Les erreurs de Tools incluent details.call_id et details.name.
• close : émet un événement lorsque la connexion WebSocket se ferme.
• tool-call-start : émet un événement avant l’exécution d’un Tool de fonction Mastra.
• tool-call-result : émet un événement après le retour d’un Tool de fonction Mastra.

Les noms d’événements xAI bruts sont également émis ; vous pouvez donc vous abonner à des événements tels que response.output_audio.delta, response.text.delta, response.function_call_arguments.done et response.done.

Tools

Tools de fonction Mastra

Les Tools ajoutés avec addTools() sont convertis en Tools de fonction xAI et inclus dans session.update.

import { createTool } from '@mastra/core/tools'
import { z } from 'zod'

const weatherTool = createTool({
  id: 'getWeather',
  description: 'Get current weather for a location.',
  inputSchema: z.object({
    location: z.string(),
  }),
  execute: async ({ location }) => {
    return { location, temperature: 22 }
  },
})

voice.addTools({ getWeather: weatherTool })

Lorsque xAI émet response.function_call_arguments.done, le Provider exécute le Tool Mastra correspondant et envoie un élément function_call_output. Si xAI émet plusieurs appels de fonction pour une même réponse, le Provider attend tous les résultats des Tools ainsi que l’événement response.done de la réponse avant d’envoyer un seul response.create de poursuite.

Tools xAI côté serveur

Les Tools xAI côté serveur sont transmis dans la configuration de la session et exécutés par xAI. Les Tools transmis dans session.tools et serverTools sont fusionnés :

const voice = new XAIRealtimeVoice({
  apiKey: process.env.XAI_API_KEY,
  serverTools: [
    { type: 'web_search' },
    { type: 'x_search', allowed_x_handles: ['xai'] },
    { type: 'file_search', vector_store_ids: ['collection_123'], max_num_results: 10 },
    {
      type: 'mcp',
      server_url: 'https://mcp.example.com/mcp',
      server_label: 'business-tools',
      allowed_tools: ['lookup_order'],
    },
  ],
})

Formats audio

Le format d’entrée et de sortie par défaut est PCM16 à 24 kHz. Vous pouvez également configurer les fréquences d’échantillonnage PCM prises en charge ou les codecs de téléphonie :

const voice = new XAIRealtimeVoice({
  audio: {
    input: { format: { type: 'audio/pcm', rate: 16000 } },
    output: { format: { type: 'audio/pcm', rate: 16000 } },
  },
})

Les types de formats pris en charge sont audio/pcm, audio/pcmu et audio/pcma. PCM prend en charge les fréquences d’échantillonnage documentées de 8 kHz à 48 kHz. audio/pcmu et audio/pcma sont des codecs de téléphonie G.711 qui utilisent 8 kHz.