> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/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 protocol 傳送的短期 xAI token，用來取代 authorization header。

**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 protocol，而非 authorization header。若同時設定 `apiKey` 與 `ephemeralToken`，Provider 會使用臨時 token。

## 方法

### `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`): 語音覆寫。此選項會更新目前 xAI 工作階段的語音，並套用於後續輪次。

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

回傳：`Promise<void>`

### `send()`

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

`send()` 需要已開啟的連線。請在 `connect()` resolve 後，用它處理麥克風即時音訊。可讀取串流的區塊必須是二進位音訊區塊（`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 取樣率或電話語音 codec：

```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 電話語音 codec，並使用 8 kHz。