跳至主要內容

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 protocol 傳送的短期 xAI token，用來取代 authorization header。

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

方法
「方法」的直接連結

connect()
「connect」的直接連結

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

requestContext?:

RequestContext
傳遞給函式 Tool 執行作業的選用 Mastra 請求脈絡。

回傳：Promise<void>

close()
「close」的直接連結

關閉 WebSocket 連線、結束使用中的 speaker 串流，並清除已排入佇列的事件、待處理的函式呼叫狀態與請求脈絡。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() resolve 後，用它處理麥克風即時音訊。可讀取串流的區塊必須是二進位音訊區塊（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 取樣率或電話語音 codec：

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。

On this page