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

# xAI Realtime voice

`XAIRealtimeVoice` 類別使用 xAI Grok Voice Agent API 提供即時語音互動功能。它實作 Mastra 的 `MastraVoice` 即時合約，並支援雙向音訊串流、文字回合、伺服器 VAD、xAI 語音、函數 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 token。

**model** (`XAIRealtimeModel`): 要使用的 Grok 語音模型。 (Default: `'grok-voice-think-fast-1.0'`)

**speaker** (`XAIVoice`): 語音輸出所使用的語音 ID。內置值為 eve、ara、rex、sal 和 leo，亦支援自訂 xAI 語音 ID。 (Default: `'eve'`)

**instructions** (`string`): 在 session.update 中傳送的系統指示。

**turnDetection** (`XAITurnDetection`): 語音活動偵測設定。 (Default: `{ type: 'server_vad' }`)

**audio** (`XAIAudioConfig`): 輸入及輸出音訊格式設定。 (Default: `24 kHz audio/pcm 輸入及輸出`)

**serverTools** (`XAIServerTool[]`): 在 session.update 中傳送的 xAI 伺服器端 Tool。支援 file\_search、web\_search、x\_search 及 mcp。這些 Tool 會與 session.tools 合併。

**session** (`Partial<XAISessionConfig>`): 合併至初始 session.update 事件的其他 xAI 工作階段欄位。

**url** (`string`): 覆寫 xAI 即時 WebSocket URL。 (Default: `'wss://api.x.ai/v1/realtime'`)

**debug** (`boolean`): 啟用所接收 xAI 事件的偵錯記錄。偵錯記錄可能包含轉錄文字及 Tool 呼叫引數。 (Default: `false`)

### VoiceConfig 模式

你亦可使用 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 },
    },
  },
})
```

## 驗證

伺服器端應用程式請使用 `apiKey` 或 `XAI_API_KEY`。此 Provider 專為 Node.js 伺服器端執行環境而設。如果你已在伺服器產生 xAI 臨時 token，可以將其作為 `ephemeralToken` 傳入；Provider 會使用 `xai-client-secret.<token>` WebSocket 協定，而非授權標頭。如果同時設定了 `apiKey` 和 `ephemeralToken`，Provider 會使用臨時 token。

## 方法

### `connect()`

建立 WebSocket 連線，並傳送初始 `session.update`。

**requestContext** (`RequestContext`): 傳遞至函數 Tool 執行的選用 Mastra 請求內容。

傳回：`Promise<void>`

### `close()`

關閉 WebSocket 連線、結束使用中的揚聲器串流，並清除已排隊的事件、待處理的函數呼叫狀態及請求內容。`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`): 語音覆寫。這會更新有效的 xAI 工作階段語音，並用於後續回合。

**options.response** (`Record<string, unknown>`): 其他 xAI response.create 欄位。

傳回：`Promise<void>`

### `send()`

使用 `input_audio_buffer.append` 串流即時音訊區塊。

`send()` 需要已開啟的連線。請在 `connect()` 完成後，使用此方法處理即時咪高峰音訊。可讀取串流區塊必須是二進制音訊區塊（`Buffer`、`ArrayBuffer` 或 typed array）。

**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()` 及 `clearAudioBuffer()`

傳送相應的 xAI 即時用戶端事件，以手動控制回合。

傳回：`Promise<void>`

### `cancelResponse()`

傳送 `response.cancel`，中斷進行中的回應。

**responseId** (`string`): 要取消的選用 xAI 回應 ID。

**eventId** (`string`): 選用的 xAI 事件 ID。

傳回：`Promise<void>`

## 事件

`XAIRealtimeVoice` 將 xAI 即時伺服器事件對應至 Mastra 語音事件：

- `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 為一個回應發出多個函數呼叫，Provider 會等待每個 Tool 結果及該回應的 `response.done` 事件，然後才傳送一個接續的 `response.create`。

### 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。