xAI Realtime voice

XAIRealtimeVoice 類別使用 xAI Grok Voice Agent API 提供即時語音互動功能。它實作 Mastra 的 MastraVoice 即時合約，並支援雙向音訊串流、文字回合、伺服器 VAD、xAI 語音、函數 Tool，以及 xAI 伺服器端 Tool。

使用範例
使用範例的直接連結

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-voice-think-fast-1.0'

要使用的 Grok 語音模型。

speaker?:

XAIVoice

= 'eve'

語音輸出所使用的語音 ID。內置值為 eve、ara、rex、sal 和 leo，亦支援自訂 xAI 語音 ID。

instructions?:

string

在 session.update 中傳送的系統指示。

turnDetection?:

XAITurnDetection

= { type: 'server_vad' }

語音活動偵測設定。

audio?:

XAIAudioConfig

= 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

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

覆寫 xAI 即時 WebSocket URL。

debug?:

boolean

= false

啟用所接收 xAI 事件的偵錯記錄。偵錯記錄可能包含轉錄文字及 Tool 呼叫引數。

VoiceConfig 模式
VoiceConfig 模式的直接連結

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

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

方法
方法的直接連結

`connect()`
connect 的直接連結

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

requestContext?:

RequestContext

傳遞至函數 Tool 執行的選用 Mastra 請求內容。

傳回：Promise<void>

`close()`
close 的直接連結

關閉 WebSocket 連線、結束使用中的揚聲器串流，並清除已排隊的事件、待處理的函數呼叫狀態及請求內容。disconnect() 是 close() 的別名。

傳回：void

`addInstructions()`
addinstructions 的直接連結

設定工作階段指示。如果 WebSocket 已開啟，Provider 會傳送 session.update。傳入 undefined 會儲存空字串，並清除目前工作階段或下次連線的有效指示。

instructions?:

string

要傳送至 xAI 的系統指示。

傳回：void

`addTools()`
addtools 的直接連結

註冊 Mastra 函數 Tool，並在連線後使用 session.update 重新整理工作階段 Tool。

tools?:

ToolsInput

要作為 xAI 函數 Tool 公開的 Mastra Tool。

傳回：void

`updateConfig()`
updateconfig 的直接連結

傳送包含其他 xAI 工作階段欄位的 session.update 事件。

sessionConfig:

Partial<XAISessionConfig>

要更新的工作階段欄位。

傳回：void

`speak()`
speak 的直接連結

使用 conversation.item.create 傳送文字回合，然後要求回應。

input:

string | NodeJS.ReadableStream

要作為使用者輸入傳送的文字或可讀取文字串流。

options.speaker?:

XAIVoice

語音覆寫。這會更新有效的 xAI 工作階段語音，並用於後續回合。

options.response?:

Record<string, unknown>

其他 xAI response.create 欄位。

傳回：Promise<void>

`send()`
send 的直接連結

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

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

audioData:

NodeJS.ReadableStream | Int16Array

PCM 音訊串流或 Int16Array 音訊資料。

eventId?:

string

選用的 xAI 事件 ID。

傳回：Promise<void>

`listen()`
listen 的直接連結

使用 input_audio_buffer.append 傳送有限長度的音訊串流。預設會提交輸入緩衝區並要求回應。

audioData:

NodeJS.ReadableStream

要傳送的音訊串流。

options.commit?:

boolean

= true

是否在音訊項目後傳送 input_audio_buffer.commit。

options.createResponse?:

boolean

= true

是否在音訊項目後傳送 response.create。

傳回：Promise<void>

`answer()`
answer 的直接連結

傳送 response.create，要求 xAI 繼續對話。

傳回：Promise<void>

`commitAudioBuffer()` 及 `clearAudioBuffer()`
commitaudiobuffer-and-clearaudiobuffer 的直接連結

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

傳回：Promise<void>

`cancelResponse()`
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
Tool 的直接連結

Mastra 函數 Tool
Mastra 函數 Tool 的直接連結

透過 addTools() 加入的 Tool 會轉換為 xAI 函數 Tool，並包含在 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 })

當 xAI 發出 response.function_call_arguments.done 時，Provider 會執行相應的 Mastra Tool，並傳送 function_call_output 項目。如果 xAI 為一個回應發出多個函數呼叫，Provider 會等待每個 Tool 結果及該回應的 response.done 事件，然後才傳送一個接續的 response.create。

xAI 伺服器端 Tool
xAI 伺服器端 Tool 的直接連結

xAI 伺服器端 Tool 會透過工作階段設定直接傳遞，並由 xAI 執行。在 session.tools 及 serverTools 傳入的 Tool 會合併：

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 取樣率或電話語音編解碼器：

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。

使用範例使用範例 的直接連結

設定設定 的直接連結

建構函數選項建構函數選項 的直接連結

apiKey?:

ephemeralToken?:

model?:

speaker?:

instructions?:

turnDetection?:

audio?:

serverTools?:

session?:

url?:

debug?:

VoiceConfig 模式VoiceConfig 模式 的直接連結

驗證驗證 的直接連結

方法方法 的直接連結

connect()connect 的直接連結

requestContext?:

close()close 的直接連結

addInstructions()addinstructions 的直接連結

instructions?:

addTools()addtools 的直接連結

tools?:

updateConfig()updateconfig 的直接連結

sessionConfig:

speak()speak 的直接連結

input:

options.speaker?:

options.response?:

send()send 的直接連結

audioData:

eventId?:

listen()listen 的直接連結

audioData:

options.commit?:

options.createResponse?:

answer()answer 的直接連結

commitAudioBuffer() 及 clearAudioBuffer()commitaudiobuffer-and-clearaudiobuffer 的直接連結

cancelResponse()cancelresponse 的直接連結

responseId?:

eventId?:

事件事件 的直接連結

ToolTool 的直接連結

Mastra 函數 ToolMastra 函數 Tool 的直接連結

xAI 伺服器端 ToolxAI 伺服器端 Tool 的直接連結

音訊格式音訊格式 的直接連結

使用範例
使用範例的直接連結

設定
設定的直接連結

建構函數選項
建構函數選項的直接連結

VoiceConfig 模式
VoiceConfig 模式的直接連結

驗證
驗證的直接連結

方法
方法的直接連結

`connect()`
connect 的直接連結

`close()`
close 的直接連結

`addInstructions()`
addinstructions 的直接連結

`addTools()`
addtools 的直接連結

`updateConfig()`
updateconfig 的直接連結

`speak()`
speak 的直接連結

`send()`
send 的直接連結

`listen()`
listen 的直接連結

`answer()`
answer 的直接連結

`commitAudioBuffer()` 及 `clearAudioBuffer()`
commitaudiobuffer-and-clearaudiobuffer 的直接連結

`cancelResponse()`
cancelresponse 的直接連結

事件
事件的直接連結

Tool
Tool 的直接連結

Mastra 函數 Tool
Mastra 函數 Tool 的直接連結

xAI 伺服器端 Tool
xAI 伺服器端 Tool 的直接連結

音訊格式
音訊格式的直接連結