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

# 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

```typescript
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`): Modèle vocal Grok à utiliser. (Default: `'grok-voice-think-fast-1.0'`)

**speaker** (`XAIVoice`): 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. (Default: `'eve'`)

**instructions** (`string`): Instructions système envoyées dans session.update.

**turnDetection** (`XAITurnDetection`): Configuration de la détection d’activité vocale. (Default: `{ type: 'server_vad' }`)

**audio** (`XAIAudioConfig`): Configuration des formats audio d’entrée et de sortie. (Default: `Entrée et sortie audio/pcm à 24 kHz`)

**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`): Remplace l’URL WebSocket xAI Realtime. (Default: `'wss://api.x.ai/v1/realtime'`)

**debug** (`boolean`): 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. (Default: `false`)

### Modèle VoiceConfig

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

```typescript
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`): Indique s’il faut envoyer input\_audio\_buffer.commit après l’élément audio. (Default: `true`)

**options.createResponse** (`boolean`): Indique s’il faut envoyer response.create après l’élément audio. (Default: `true`)

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

```typescript
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 :

```typescript
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 :

```typescript
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.