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

# xAI Realtime Voice

`XAIRealtimeVoice` クラスは、xAI Grok Voice Agent API を使用したリアルタイム Voice 対話機能を提供します。Mastra の `MastraVoice` リアルタイムコントラクトを実装し、双方向音声ストリーミング、テキストターン、サーバー VAD、xAI Voice、関数 Tool、xAI サーバー側 Tool をサポートします。

## 使用例

```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()
```

## 設定

### コンストラクターオプション

**apiKey** (`string`): xAI API キー。未指定の場合は XAI\_API\_KEY 環境変数を使用します。

**ephemeralToken** (`string`): 認証ヘッダーの代わりに WebSocket プロトコルで送信する短期 xAI トークン。

**model** (`XAIRealtimeModel`): 使用する Grok Voice モデル。 (Default: `'grok-voice-think-fast-1.0'`)

**speaker** (`XAIVoice`): 音声出力に使用する Voice ID。組み込み値は eve、ara、rex、sal、leo です。カスタム xAI Voice ID もサポートします。 (Default: `'eve'`)

**instructions** (`string`): session.update で送信するシステム指示。

**turnDetection** (`XAITurnDetection`): Voice Activity Detection の設定。 (Default: `{ type: 'server_vad' }`)

**audio** (`XAIAudioConfig`): 入出力音声形式の設定。 (Default: `24 kHz audio/pcm input and output`)

**serverTools** (`XAIServerTool[]`): session.update で送信する xAI サーバー側 Tool。file\_search、web\_search、x\_search、mcp をサポートします。session.tools と統合されます。

**session** (`Partial<XAISessionConfig>`): 最初の session.update イベントに統合する追加の xAI セッションフィールド。

**url** (`string`): xAI Realtime WebSocket URL を上書きします。 (Default: `'wss://api.x.ai/v1/realtime'`)

**debug** (`boolean`): 受信した xAI イベントのデバッグログを有効にします。デバッグログには文字起こしや Tool 呼び出しの引数が含まれる場合があります。 (Default: `false`)

### VoiceConfig パターン

Mastra の共通 Voice 設定形式も使用できます。

```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 },
    },
  },
})
```

## 認証

サーバー側アプリケーションでは `apiKey` または `XAI_API_KEY` を使用します。この Provider は Node.js サーバー側ランタイム向けです。サーバーで xAI の一時トークンを発行している場合は、`ephemeralToken` として渡せます。Provider は認証ヘッダーの代わりに `xai-client-secret.<token>` WebSocket プロトコルを使用します。`apiKey` と `ephemeralToken` の両方を設定した場合、Provider は一時トークンを使用します。

## メソッド

### `connect()`

WebSocket 接続を確立し、最初の `session.update` を送信します。

**requestContext** (`RequestContext`): 関数 Tool の実行に渡す省略可能な Mastra リクエストコンテキスト。

戻り値：`Promise<void>`

### `close()`

WebSocket 接続を閉じ、アクティブな Speaker ストリームを終了し、キュー内のイベント、保留中の関数呼び出し状態、リクエストコンテキストを消去します。`disconnect()` は `close()` のエイリアスです。

戻り値：`void`

### `addInstructions()`

セッション指示を設定します。WebSocket が開いている場合、Provider は `session.update` を送信します。`undefined` を渡すと空文字列を保存し、現在のセッションまたは次回の接続でアクティブな指示を消去します。

**instructions** (`string`): xAI に送信するシステム指示。

戻り値： `void`

### `addTools()`

Mastra 関数 Tool を登録し、接続中の場合は `session.update` でセッション Tool を更新します。

**tools** (`ToolsInput`): xAI 関数 Tool として公開する Mastra Tool。

戻り値： `void`

### `updateConfig()`

追加の xAI セッションフィールドを含む `session.update` イベントを送信します。

**sessionConfig** (`Partial<XAISessionConfig>`): 更新するセッションフィールド。

戻り値： `void`

### `speak()`

`conversation.item.create` を使用してテキストターンを送信し、応答を要求します。

**input** (`string | NodeJS.ReadableStream`): ユーザー入力として送信するテキストまたは読み取り可能なテキストストリーム。

**options.speaker** (`XAIVoice`): Voice の上書き。アクティブな xAI セッション Voice を更新し、後続のターンで使用します。

**options.response** (`Record<string, unknown>`): 追加の xAI response.create フィールド。

戻り値： `Promise<void>`

### `send()`

`input_audio_buffer.append` でリアルタイム音声チャンクをストリーミングします。

`send()` には開いている接続が必要です。`connect()` の解決後、ライブマイク音声に使用します。読み取り可能なストリームのチャンクは、バイナリ音声チャンク（`Buffer`、`ArrayBuffer`、型付き配列のいずれか）である必要があります。

**audioData** (`NodeJS.ReadableStream | Int16Array`): PCM 音声ストリームまたは Int16Array 音声データ。

**eventId** (`string`): 省略可能な xAI イベント ID。

戻り値： `Promise<void>`

### `listen()`

`input_audio_buffer.append` で有限の音声ストリームを送信します。デフォルトでは入力バッファをコミットして応答を要求します。

**audioData** (`NodeJS.ReadableStream`): 送信する音声ストリーム。

**options.commit** (`boolean`): 音声項目の後に input\_audio\_buffer.commit を送信するかどうか。 (Default: `true`)

**options.createResponse** (`boolean`): 音声項目の後に response.create を送信するかどうか。 (Default: `true`)

戻り値： `Promise<void>`

### `answer()`

`response.create` を送信し、xAI に会話の続行を求めます。

戻り値： `Promise<void>`

### `commitAudioBuffer()` and `clearAudioBuffer()`

手動のターン制御用に、対応する xAI Realtime クライアントイベントを送信します。

戻り値： `Promise<void>`

### `cancelResponse()`

`response.cancel` を送信し、処理中の応答を中断します。

**responseId** (`string`): キャンセルする省略可能な xAI 応答 ID。

**eventId** (`string`): 省略可能な xAI イベント ID。

戻り値： `Promise<void>`

## イベント

`XAIRealtimeVoice` は xAI Realtime サーバーイベントを Mastra Voice イベントにマッピングします。

- `speaker`：アシスタント音声の読み取り可能なストリームを送出します。
- `speaking`：アシスタント音声の差分を送出します。
- `speaking.done`：アシスタントの音声応答が完了したときに送出します。
- `writing`：アシスタントのテキスト差分とユーザー入力の文字起こしを送出します。
- `error`：xAI と Provider の実行エラーを送出します。Tool 実行エラーや不正な形式の関数呼び出し引数も送出します。Tool エラーには `details.call_id` と `details.name` が含まれます。
- `close`：WebSocket が閉じたときに送出します。
- `tool-call-start`：Mastra 関数 Tool の実行前に送出します。
- `tool-call-result`：Mastra 関数 Tool が結果を返した後に送出します。

xAI の生のイベント名も送出されるため、`response.output_audio.delta`、`response.text.delta`、`response.function_call_arguments.done`、`response.done` などのイベントを購読できます。

## Tool

### Mastra 関数 Tool

`addTools()` で追加した Tool は xAI 関数 Tool に変換され、`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 })
```

xAI が `response.function_call_arguments.done` を送出すると、Provider は対応する Mastra Tool を実行して `function_call_output` 項目を送信します。xAI が1つの応答に対して複数の関数呼び出しを送出した場合、Provider はすべての Tool 結果と応答の `response.done` イベントを待ってから、続行用の `response.create` を1つ送信します。

### xAI サーバー側 Tool

xAI サーバー側 Tool はセッション設定でそのまま渡され、xAI によって実行されます。`session.tools` と `serverTools` で渡された Tool は統合されます。

```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'],
    },
  ],
})
```

## 音声形式

デフォルトの入出力形式は 24 kHz PCM16 です。サポートされる PCM サンプルレートまたはテレフォニーコーデックも設定できます。

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

サポートされる形式タイプは `audio/pcm`、`audio/pcmu`、`audio/pcma` です。PCM は、ドキュメントに記載された 8 kHz～48 kHz のサンプルレートをサポートします。`audio/pcmu` と `audio/pcma` は G.711 テレフォニーコーデックで、8 kHz を使用します。