跳到主要内容

xAI Realtime Voice

XAIRealtimeVoice 类使用 xAI Grok Voice Agent API 提供实时 Voice 交互能力。它实现了 Mastra 的 MastraVoice 实时契约，并支持双向音频流、文本轮次、server VAD、xAI Voice、function Tool 和 xAI server-side 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 key。未提供时使用 XAI_API_KEY 环境变量。

ephemeralToken?:

string
通过 WebSocket protocol 发送的短期 xAI token，用于替代 authorization header。

model?:

XAIRealtimeModel
= 'grok-voice-think-fast-1.0'
要使用的 Grok Voice 模型。

speaker?:

XAIVoice
= 'eve'
用于语音输出的 Voice ID。内置值包括 eve、ara、rex、sal 和 leo，也支持自定义 xAI Voice ID。

instructions?:

string
在 session.update 中发送的系统指令。

turnDetection?:

XAITurnDetection
= { type: 'server_vad' }
语音活动检测配置。

audio?:

XAIAudioConfig
= 24 kHz audio/pcm input and output
输入和输出音频格式配置。

serverTools?:

XAIServerTool[]
在 session.update 中发送的 xAI server-side Tool。支持 file_search、web_search、x_search 和 mcp。这些 Tool 会与 session.tools 合并。

session?:

Partial<XAISessionConfig>
要合并到初始 session.update 事件中的其他 xAI session 字段。

url?:

string
= 'wss://api.x.ai/v1/realtime'
覆盖 xAI Realtime WebSocket URL。

debug?:

boolean
= false
为接收到的 xAI 事件启用 debug 日志。Debug 日志可能包含转录文本和 Tool 调用参数。

VoiceConfig 模式
VoiceConfig 模式的直接链接

还可以使用 Mastra 共享的 Voice 配置结构：

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

身份验证
身份验证的直接链接

server-side 应用请使用 apiKey 或 XAI_API_KEY。此 Provider 面向 Node.js server-side runtime 构建。如果你的服务器已签发 xAI ephemeral token，可以通过 ephemeralToken 传入；Provider 会使用 xai-client-secret.<token> WebSocket protocol，而不是 authorization header。如果同时配置了 apiKey 和 ephemeralToken，Provider 会使用 ephemeral token。

方法
方法的直接链接

connect()
connect的直接链接

建立 WebSocket 连接并发送初始 session.update。

requestContext?:

RequestContext
传给 function Tool 执行过程的可选 Mastra request context。

返回：Promise<void>

close()
close的直接链接

关闭 WebSocket 连接、结束活跃的 speaker 流，并清除排队事件、待处理的 function-call 状态和 request context。disconnect() 是 close() 的别名。

返回：void

addInstructions()
addinstructions的直接链接

设置 session 指令。如果 WebSocket 已打开，Provider 会发送 session.update。传入 undefined 会存储空字符串，并清除当前 session 或下次连接中的活跃指令。

instructions?:

string
要发送给 xAI 的系统指令。

返回：void

addTools()
addtools的直接链接

注册 Mastra function Tool，并在已连接时通过 session.update 刷新 session Tool。

tools?:

ToolsInput
要作为 xAI function Tool 公开的 Mastra Tool。

返回：void

updateConfig()
updateconfig的直接链接

发送包含其他 xAI session 字段的 session.update 事件。

sessionConfig:

Partial<XAISessionConfig>
要更新的 session 字段。

返回：void

speak()
speak的直接链接

使用 conversation.item.create 发送一个文本轮次，然后请求响应。

input:

string | NodeJS.ReadableStream
要作为用户输入发送的文本或文本可读流。

options.speaker?:

XAIVoice
Voice 覆盖项。它会更新活跃 xAI session 的 Voice，并用于后续轮次。

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 event ID。

返回：Promise<void>

listen()
listen的直接链接

使用 input_audio_buffer.append 发送有限音频流。默认情况下，它会提交输入 buffer 并请求响应。

audioData:

NodeJS.ReadableStream
要发送的音频流。

options.commit?:

boolean
= true
是否在音频 item 之后发送 input_audio_buffer.commit。

options.createResponse?:

boolean
= true
是否在音频 item 之后发送 response.create。

返回：Promise<void>

answer()
answer的直接链接

发送 response.create，让 xAI 继续对话。

返回：Promise<void>

commitAudioBuffer() 和 clearAudioBuffer()
commitaudiobuffer-and-clearaudiobuffer的直接链接

发送对应的 xAI Realtime client 事件，以便手动控制轮次。

返回：Promise<void>

cancelResponse()
cancelresponse的直接链接

发送 response.cancel 以中断正在处理的响应。

responseId?:

string
要取消的可选 xAI response ID。

eventId?:

string
可选的 xAI event ID。

返回：Promise<void>

事件
事件的直接链接

XAIRealtimeVoice 将 xAI Realtime server 事件映射到 Mastra Voice 事件：

  • speaker：发出助手音频的可读流。
  • speaking：发出助手音频增量。
  • speaking.done：助手音频响应完成时发出。
  • writing：发出助手文本增量和用户输入转录。
  • error：发出 xAI 和 Provider 执行错误。它也会发出 Tool 执行错误和格式错误的 function-call 参数。Tool 错误包含 details.call_id 和 details.name。
  • close：WebSocket 关闭时发出。
  • tool-call-start：在执行 Mastra function Tool 前发出。
  • tool-call-result：Mastra function 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 function 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 item。如果 xAI 为一个响应发出多个 function call，Provider 会等待所有 Tool 结果和该响应的 response.done 事件，然后再发送一个用于继续的 response.create。

xAI server-side Tool（服务端 Tool）
xAI server-side Tool（服务端 Tool）的直接链接

xAI server-side Tool 会在 session 配置中透传并由 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。

On this page