> Discover all available pages from the documentation index: https://mastra.zisheng.pro/ko/llms.txt

# xAI 실시간 음성

그만큼`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 프로토콜로 전송되는 단기 xAI 토큰입니다.

**model** (`XAIRealtimeModel`): 사용할 Grok 음성 Model입니다. (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를 지원합니다. 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 임시 토큰을 발급하고 있다면 `ephemeralToken`으로 전달할 수 있습니다. 이 경우 Provider는 인증 헤더 대신 `xai-client-secret.<token>` WebSocket 프로토콜을 사용합니다. `apiKey`와 `ephemeralToken`을 모두 구성하면 Provider는 임시 토큰을 사용합니다.

## 행동 양식

### `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을 등록하고 연결되면 다음으로 세션 Tool을 새로 고칩니다.`session.update`.

**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()`가 완료된 후 라이브 마이크 오디오에 사용하세요. 읽기 가능한 스트림 청크는 바이너리 오디오 청크(`Buffer`, `ArrayBuffer` 또는 형식화 배열)여야 합니다.

**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()`

xAI에 대화를 계속하도록 요청하기 위해 `response.create`를 전송합니다. 보고:`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

### 마스트라 기능 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'],
    },
  ],
})
```

## 오디오 형식

기본 입력 및 출력 형식은 24kHz PCM16입니다. 지원되는 PCM 샘플 속도 또는 전화 통신 코덱을 구성할 수도 있습니다.

```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은 문서화된 8kHz\~48kHz 샘플링 속도를 지원합니다. `audio/pcmu`와 `audio/pcma`는 G.711 전화 통신 코덱이며 8kHz를 사용합니다.