xAI 실시간 음성
그만큼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?:
ephemeralToken?:
model?:
speaker?:
instructions?:
turnDetection?:
audio?:
serverTools?:
session?:
url?:
debug?:
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 임시 토큰을 발급하고 있다면 ephemeralToken으로 전달할 수 있습니다. 이 경우 Provider는 인증 헤더 대신 xai-client-secret.<token> WebSocket 프로토콜을 사용합니다. apiKey와 ephemeralToken을 모두 구성하면 Provider는 임시 토큰을 사용합니다.
행동 양식행동 양식에 대한 직접 링크
connect()connect에 대한 직접 링크
WebSocket 연결을 설정하고 초기 정보를 보냅니다.session.update.
requestContext?:
보고:Promise<void>
close()close에 대한 직접 링크
WebSocket 연결을 닫고 활성 speaker 스트림을 종료하며 대기 중인 이벤트, 보류 중인 함수 호출 상태 및 요청 컨텍스트를 지웁니다. disconnect()는 close()의 별칭입니다.
보고:void
addInstructions()addinstructions에 대한 직접 링크
세션 지침을 설정합니다. WebSocket이 열려 있으면 Provider가 session.update를 전송합니다. undefined를 전달하면 빈 문자열을 저장하고 현재 세션이나 다음 연결에서 활성 지침을 지웁니다.
instructions?:
보고:void
addTools()addtools에 대한 직접 링크
Mastra 기능 Tool을 등록하고 연결되면 다음으로 세션 Tool을 새로 고칩니다.session.update.
tools?:
보고:void
updateConfig()updateconfig에 대한 직접 링크
추가 xAI 세션 필드와 함께 session.update 이벤트를 전송합니다.
sessionConfig:
보고:void
speak()speak에 대한 직접 링크
conversation.item.create를 사용해 텍스트 차례를 보낸 다음 응답을 요청합니다.
input:
options.speaker?:
options.response?:
보고:Promise<void>
send()send에 대한 직접 링크
실시간 오디오 청크를 스트리밍합니다.input_audio_buffer.append.
send()에는 열린 연결이 필요합니다. connect()가 완료된 후 라이브 마이크 오디오에 사용하세요. 읽기 가능한 스트림 청크는 바이너리 오디오 청크(Buffer, ArrayBuffer 또는 형식화 배열)여야 합니다.
audioData:
eventId?:
보고:Promise<void>
listen()listen에 대한 직접 링크
input_audio_buffer.append를 사용해 유한한 오디오 스트림을 전송합니다. 기본적으로 입력 버퍼를 커밋하고 응답을 요청합니다.
audioData:
options.commit?:
options.createResponse?:
보고:Promise<void>
answer()answer에 대한 직접 링크
xAI에 대화를 계속하도록 요청하기 위해 response.create를 전송합니다.
보고:Promise<void>
commitAudioBuffer()그리고clearAudioBuffer()commitaudiobuffer-and-clearaudiobuffer에 대한 직접 링크
수동 회전 제어를 위해 일치하는 xAI 실시간 클라이언트 이벤트를 보냅니다.
보고:Promise<void>
cancelResponse()cancelresponse에 대한 직접 링크
진행 중인 응답을 중단하기 위해 response.cancel을 전송합니다.
responseId?:
eventId?:
보고:Promise<void>
이벤트이벤트에 대한 직접 링크
XAIRealtimeVoicexAI 실시간 서버 이벤트를 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과 같은 이벤트를 구독할 수 있습니다.
ToolTool에 대한 직접 링크
마스트라 기능 Tool마스트라 기능 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 서버 측 ToolxAI 서버 측 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'],
},
],
})
오디오 형식오디오 형식에 대한 직접 링크
기본 입력 및 출력 형식은 24kHz 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은 문서화된 8kHz~48kHz 샘플링 속도를 지원합니다. audio/pcmu와 audio/pcma는 G.711 전화 통신 코덱이며 8kHz를 사용합니다.