Universal.Operative.Sdk.Realtime.xAI 2.0.0

About

Universal.Operative.Sdk.Realtime.xAI adapts xAI's Grok Voice Agent API to Universal.Operative.Sdk.Realtime's provider-neutral IModel/IRealtimeSession/SessionEvent model. The wire protocol itself comes from Universal.xAI.Realtime.Client.

How to Use

Installation

dotnet add package Universal.Operative.Sdk
dotnet add package Universal.Operative.Sdk.Realtime
dotnet add package Universal.Operative.Sdk.Realtime.xAI

Quick start

using Universal.Operative.Sdk.Realtime;
using Universal.Operative.Sdk.Realtime.xAI;

var model = new Model(apiKey, modelId: Models.GrokVoiceLatest);

IRealtimeSession session = await model.ConnectAsync(new RealtimeSessionOptions
{
    SystemPrompt = [new TextBlock("You are a helpful voice assistant.")],
    Tools = [myTool],
});

await foreach (SessionOutputEvent e in session.Output)
{
    switch (e)
    {
        case SessionReadyEvent: Console.WriteLine("connected"); break;
        case TranscriptDeltaEvent t: Console.WriteLine($"{t.Role}: {t.Text}"); break;
        case AudioOutputDeltaEvent a: /* play a.Audio (24kHz PCM16 by default) */ break;
        case InterruptedEvent: /* stop playback */ break;
    }
}

await session.SendAsync(new AppendAudioInputEvent { Audio = micChunk });

Provider-specific options

GrokRealtimeSessionOptions is a RealtimeSessionOptions subclass carrying the xAI-specific settings:

var options = new GrokRealtimeSessionOptions
{
    SystemPrompt = [new TextBlock("You are a helpful voice assistant.")],
    Voice = Voices.Eve,
    OutputAudioFormat = RealtimeAudioFormat.Pcm(RealtimeAudioSampleRates.Hz16000),
    OutputSpeed = 1.1,
    TurnDetection = new TurnDetection(TurnDetectionTypes.ServerVad) { IdleTimeoutMilliseconds = 8000 },
    InputTranscription = new RealtimeAudioTranscription { LanguageHint = LanguageHints.English, Keyterms = ["Grok"] },
    ReasoningEffort = ReasoningEfforts.None,
    Replace = new Dictionary<string, string> { ["Acme Mobile"] = "Acme Mobull" },
};

Setting InputAudioTransport/OutputAudioTransport to AudioTransports.Binary carries audio in WebSocket binary frames instead of base64 JSON. AppendAudioInputEvent and AudioOutputDeltaEvent are unchanged either way.

Behaviour notes

• Capabilities: AudioInProcess | ToolCalling | Transcripts.
• Turn detection: server_vad is the default. A null TurnDetection drives turns with CommitAudioInputEvent.
• Transcripts: user transcripts arrive cumulatively as non-final TranscriptDeltaEvents, each superseding the last, then once as final. Assistant transcripts arrive once per turn, as final.
• Message roles: SendTextInputEvent accepts user and assistant. MessageRoles.System throws; the system prompt belongs in RealtimeSessionOptions.SystemPrompt.
• Tools: RealtimeSessionOptions.Tools maps to xAI function tools. xAI's server-side tools (web_search, x_search, file_search, mcp) are reachable through RawSendEvent with a constructed SessionUpdateEvent.
• Tool results: ToolResult content is flattened into xAI's single-string function_call_output.
• RawSendEvent: resolves its RawJson against every client event this adapter can send by matching the "type" field, or sends a constructed RealtimeClientEvent passed as Payload as-is.
• Unmodelled server events: surface as RawPassthroughEvent with their payload intact.