Grok Voice Agent API: een manier om realtime spraakassistenten te bouwen

Spraak-AI-agents zijn hot. Gebruikers willen met hun apps praten in plaats van typen, en de techniek is eindelijk goed genoeg om die gesprekken natuurlijk te laten aanvoelen.

Als je er zelf een wilt bouwen, is xAI's Grok Voice Agent API een uitstekend startpunt. Het biedt responstijden onder de seconde en lagere kosten dan de meeste alternatieven, plus drop-in compatibiliteit met bestaande OpenAI-code.

Deze tutorial laat zien hoe je vanaf nul een werkende spraakagent bouwt. Je regelt authenticatie, stelt persoonlijkheid en stemopties in, voegt tool-calling toe en zet alles in productie met LiveKit Cloud. De API draait op Grok 3, dat door xAI is aangepast voor realtime spraakconversatie in plaats van de gebruikelijke text-in, text-out workflow.

Wat is de Grok Voice Agent API?

De Grok Voice Agent API is xAI's platform voor realtime spraakgesprekken, uitgebracht in december 2025. Het verwerkt audio rechtstreeks zonder de gebruikelijke omzetting van spraak-naar-tekst en weer terug, waardoor de responstijd daalt en gesprekken natuurlijk blijven klinken.

Traditionele spraak-AI-systemen schakelen drie afzonderlijke stappen achter elkaar: spraak naar tekst transcriberen, die tekst door een taalmodel halen en vervolgens het antwoord weer synthetiseren naar audio. Dat werkt, maar elke overdracht tussen componenten voegt vertraging toe. Als je transcriptie, verwerking en synthese meerekent, zit je op 500 ms tot 1.000 ms voordat de gebruiker antwoord krijgt. Die pauzes stapelen op en maken gesprekken mechanisch.

Grok Voice Agent slaat die conversies helemaal over. Het systeem neemt audio in, redeneert in het audiodomein en produceert audio met één enkel model dat is getraind op conversatiespraak. Deze architectuur levert gemiddeld een time-to-first-audio van 0,78 seconden en ondersteunt full-duplex communicatie (tweerichtingsaudio waarbij de agent tegelijk kan luisteren en spreken), zodat de agent kan reageren zonder strikt beurt te hoeven nemen.

Je Grok Voice Agent-omgeving instellen

Een spraakagent met Grok bouwen vereist een koppeling met LiveKit, een open-source WebRTC-platform. Grok levert het conversatie-AI-model, terwijl LiveKit de realtime audio-infrastructuur beheert die gebruikers met je agent verbindt. In deze sectie stel je beide services in.

Grok instellen

Bezoek console.x.ai en maak een account aan met X-, e-mail-, Google- of Apple-authenticatie. De xAI-console vereist vooraf betaalde credits voordat je API-calls kunt doen. Koop credits via het onderdeel Billing.

Met credits op je account ga je naar API Keys en genereer je een nieuwe key. De console toont de key één keer, dus kopieer hem direct en bewaar hem veilig. Ben je hem kwijt, dan moet je een vervangende key genereren en je applicaties bijwerken. Voor een uitgebreidere rondleiding door xAI's API-ecosysteem zie de Grok 3 API-tutorial.

LiveKit instellen

LiveKit is WebRTC-infrastructuur voor realtime audio en video. Het verzorgt de audiotransportlaag die Grok nodig heeft om met gebruikers te verbinden. Bij het bouwen van een spraakagent beheert LiveKit kamers waar gesprekken plaatsvinden, routeert het audiostreams tussen deelnemers en biedt het deployment-infrastructuur. Het LiveKit Agents-framework wikkelt deze complexiteit in, zodat jij je kunt richten op het gedrag van de agent terwijl het de connectiebeheer, audio-encoding en turn-detectie afhandelt.

Het framework ondersteunt meerdere AI-providers, waaronder xAI. Het bevat een test-playground toegankelijk via een webinterface, die je gebruikt om je agent te valideren voordat je deze uitrolt.

Meld je aan op cloud.livekit.io. De gratis laag biedt voldoende resources voor ontwikkeling en testen. Maak via het dashboard een project. Ga naar Settings en vervolgens naar API Keys. Kopieer drie inloggegevens: LIVEKIT_URL (de WebSocket-endpoint van je project), LIVEKIT_API_KEY (de publieke identifier) en LIVEKIT_API_SECRET (de private authenticatiesleutel). Deze gegevens authenticeren je agentcode bij je LiveKit Cloud-project.

Afhankelijkheden installeren en configureren

Installeer de vereiste pakketten:

uv add "livekit-agents[xai,openai]>=1.3.10" python-dotenv

Dit installeert het LiveKit Agents-framework met zowel de xAI-plugin als OpenAI-afhankelijkheden (de xAI-plugin bouwt voort op compatibiliteit met de OpenAI Realtime API), plus python-dotenv voor het beheren van omgevingsvariabelen.

Maak een .env-bestand in de hoofdmap van je project:

XAI_API_KEY=xai-YourActualKeyHere
 LIVEKIT_URL=wss://your-project.livekit.cloud
 LIVEKIT_API_KEY=APIYourKeyHere
 LIVEKIT_API_SECRET=YourSecretHere

Vervang de placeholders door je echte gegevens. Laad deze gegevens in je Python-code:

from dotenv import load_dotenv
 load_dotenv()

Zo komen de credentials beschikbaar voor zowel de xAI- als de LiveKit-bibliotheken. Voeg .env toe aan je .gitignore om te voorkomen dat ze uitlekken via versiebeheer.

Je eerste Grok Voice Agent bouwen

Met je omgeving geconfigureerd kun je een werkende spraakagent bouwen. Begin met de imports en de agentklasse in een nieuw bestand genaamd agent.py:

from livekit.agents import Agent, AgentSession, AgentServer, JobContext, cli
from livekit.plugins.xai import realtime
from dotenv import load_dotenv

load_dotenv()

class ResearchAssistant(Agent):
	def __init__(self):
    	super().__init__(
        	instructions="You are a research assistant who helps users find information.",
 	)

Je Agent-subklasse bevat alleen de instructies die bepalen hoe de agent reageert. Deze werken als een systeemprompt en vertellen de agent welke rol hij speelt. De daadwerkelijke modelconfiguratie staat elders.

Stel vervolgens de server en de connection handler in:

server = AgentServer()


@server.rtc_session()
async def entrypoint(ctx: JobContext):
	await ctx.connect()

 	session = AgentSession(
         llm=realtime.RealtimeModel(voice="ara"),
 	)

 	await session.start(
     	room=ctx.room,
     	agent=ResearchAssistant(),
 	)

De decorator @server.rtc_session() vertelt LiveKit om je entrypointfunctie te draaien wanneer iemand verbinding maakt. Binnenin neemt AgentSession de modelconfiguratie op, inclusief welke van Grok's zeven stemmen je gebruikt (Ara, Eve, Leo, Sal, Rex, Mika of Valentin). Wanneer session.start() draait, verbindt het je agent met de LiveKit-kamer waar het gesprek plaatsvindt.

Spraakgesprekken vereisen wachten op audio-invoer en -uitvoer zonder het programma te blokkeren, dus gebruikt de functie async def en await om deze operaties gelijktijdig af te handelen.

Voeg tot slot het entrypoint toe:

if __name__ == "__main__":
 	cli.run_app(server)

Draai je agent in development-modus:

uv run agent.py dev

De terminal toont de opstartvolgorde: initialisatie van de worker, HTTP-server die luistert op een lokale poort en registratie bij je LiveKit Cloud-project.

Om de agent te testen, ga je naar je LiveKit Cloud-dashboard op cloud.livekit.io. Selecteer je project en klik vervolgens op het tabblad Sandbox in de zijbalk. Kies Web Voice Agent uit de templates.

De templatepagina toont een preview van de spraakinterface met details over wat is inbegrepen. Klik op de knop Create sandbox.

In de weergegeven modal kun je een aangepaste URL configureren, mogelijkheden als camera en schermdeling inschakelen en instellingen voor uiterlijk aanpassen. De standaardinstellingen zijn prima voor testen, dus klik op Create en daarna op Done.

Terug op de Sandbox-pagina verschijnt je nieuwe sandbox onder Sandbox apps. Klik op Launch om deze te openen.

Klik op Start Call en geef microfoonrechten wanneer daarom wordt gevraagd. Let in de terminal op dit logbericht, dat aangeeft dat de agent klaar is om audio te ontvangen:

DEBUG livekit.agents start reading stream {"participant": "...", "source": "SOURCE_MICROPHONE", ...}

Na dit bericht komen reacties snel binnen.

Als je vraagt naar iets waar de agent geen toegang toe heeft (zoals het huidige weer in een specifieke stad), legt hij zijn beperkingen uit in plaats van iets te verzinnen.

Tools toevoegen aan je Grok-spraakagents

De basisagent kan een gesprek voeren maar kan niets opzoeken. Met tool-calling kan Grok functies aanroepen tijdens het gesprek en over de resultaten praten. Je kunt de ingebouwde tools van xAI gebruiken of je eigen tools definiëren.

Ingebouwde tools gebruiken

De xAI-plugin bevat WebSearch voor algemene webqueries en XSearch voor het zoeken naar posts op X. Importeer ze en geef ze door aan AgentSession:

from livekit.agents import Agent, AgentSession, AgentServer, JobContext, cli
from livekit.plugins.xai import realtime
from livekit.plugins.xai.realtime import WebSearch, XSearch
from dotenv import load_dotenv

load_dotenv()


class ResearchAssistant(Agent):
 	def __init__(self):
     	super().__init__(
             instructions="""You are a research assistant with access to web search and X search.

- Use web search for general queries and current information
- Use X search when users ask about posts or what people are saying on X/Twitter

Always mention your sources when providing information.""",
     	)


server = AgentServer()


@server.rtc_session()
async def entrypoint(ctx: JobContext):
	await ctx.connect()

	session = AgentSession(
         llm=realtime.RealtimeModel(voice="ara"),
     	tools=[
         	WebSearch(),
         	XSearch(),
     	],
 	)

 	await session.start(
     	room=ctx.room,
     	agent=ResearchAssistant(),
 	)


if __name__ == "__main__":
 	cli.run_app(server)

De parameter tools accepteert een lijst met toolobjecten. Start de agent en test met vragen als "Wat is het laatste nieuws over AI?" of "Wat zeggen mensen over Grok op X?" De terminallogs kunnen waarschuwingen tonen over onbekende AI-functies zoals web_search_with_snippets of x_semantic_search, maar de tools leveren desondanks actuele informatie op.

Grok's full-duplex audio valt ook op bij het gebruik van tools. Je kunt de agent onderbreken terwijl hij spreekt; hij stopt, luistert en past zijn antwoord aan. Dit maakt gesprekken minder robotachtig dan systemen waarbij je moet wachten tot de agent klaar is met praten.

Aangepaste tools toevoegen

Ingebouwde tools dekken veelvoorkomende use-cases, maar je eigen tools definiëren geeft je controle over parameters, foutafhandeling en welke API's je aanroept. Deze sectie demonstreert het maken van een aangepaste tool met behulp van Firecrawl's search-endpoint, dat filteropties biedt zoals limit, lang en country die de ingebouwde webzoekfunctie niet biedt.

Meld je aan op firecrawl.dev. De gratis laag bevat 500 credits en vereist geen creditcard. Installeer de SDK en voeg je key toe aan .env:

uv add firecrawl-py

FIRECRAWL_API_KEY=fc-your-key-here

Aangepaste tools zijn methodes die zijn gedecoreerd met @function_tool(). Werk de imports bij in search_agent.py:

from livekit.agents import (
 	Agent,
 	AgentSession,
 	AgentServer,
 	JobContext,
 	cli,
 	function_tool,
 	RunContext,
 )

from livekit.plugins.xai import realtime
from livekit.plugins.xai.realtime import XSearch
from firecrawl import FirecrawlApp
from dotenv import load_dotenv

import os 
load_dotenv()

De toevoegingen zijn function_tool voor de decorator, RunContext die wordt doorgegeven aan toolfuncties, en FirecrawlApp voor de Firecrawl-client. WebSearch is verwijderd omdat de aangepaste tool deze vervangt.

Definieer de tool als een methode op je agentklasse:

class ResearchAssistant(Agent):
 	def __init__(self):
     	super().__init__(
             instructions="""You are a research assistant with access to web search and X search.

 - Use Firecrawl search for general queries and current information
 - Use X search when users ask about posts or what people are saying on X/Twitter

 Always mention your sources when providing information.""",
     	)
     	self.firecrawl = FirecrawlApp(api_key=os.getenv("FIRECRAWL_API_KEY"))

 	@function_tool()
     async def search_web(
     	self,
     	context: RunContext,
     	query: str,
 	) -> dict:
     	"""Search the web for current information using Firecrawl.

     	Args:
         	query: The search query
     	"""
     	result = self.firecrawl.search(query, limit=3)
     	return {
         	"results": [
             	{
                 	"title": item.title,
                 	"url": item.url,
                     "description": item.description,
             	}
             	for item in result.web
         	]
     	}

Grok leest de docstring om te begrijpen wat de tool doet. Als je vraagt: "Wat is de huidige USD-naar-EURO wisselkoers?", extraheert Grok de query, roept je functie aan en verwerkt de resultaten in het antwoord.

Methodes die zijn gedecoreerd met @function_tool() worden automatisch geregistreerd, dus verwijder WebSearch() uit de tools-lijst:

session = AgentSession(
     llm=realtime.RealtimeModel(voice="ara"),
 	tools=[
     	XSearch(),
 	],
 )

Draai de bijgewerkte agent:

uv run search_agent.py dev

De terminal toont toolexecutie:

DEBUG livekit.agents executing tool {
 	"function": "search_web",
 	"arguments": "{\"query\":\"current USD to EURO exchange rate\"}",
 	...
 }
DEBUG livekit.agents tools execution completed {...}

In mijn tests gaf Firecrawl binnen ongeveer twee seconden resultaten. Je kunt meerdere aangepaste tools combineren met ingebouwde tools binnen dezelfde agent. Een klantenserviceagent kan bijvoorbeeld XSearch gebruiken naast aangepaste tools lookup_order() en check_inventory() die verbinden met interne databases.

Turn-detectie aanpassen

De standaardinstellingen voor turn-detectie werken goed voor typische gesprekken. Aanpassingen worden nodig als de omgeving of het gebruikersgedrag afwijkt van de norm. In een rumoerige ruimte kan de agent reageren op achtergrondgeluiden, terwijl een gebruiker die pauzeert om na te denken misschien wordt onderbroken voordat hij klaar is.

from livekit.plugins.xai import realtime
from openai.types.beta.realtime.session import TurnDetection

session = AgentSession(
 	llm=realtime.RealtimeModel(
     	voice="ara",
     	turn_detection=TurnDetection(
         	type="server_vad",
         	threshold=0.5,
         	prefix_padding_ms=300,
         	silence_duration_ms=200,
     	),
 	),
 )

De parameter threshold bepaalt hoe hard audio moet zijn voordat het als spraak telt, van 0,0 tot 1,0. Het verhogen van deze waarde naar 0,7 of hoger helpt in rumoerige omgevingen waar achtergrondgeluiden anders reacties kunnen triggeren.

De parameter prefix_padding_ms bepaalt hoeveel audio wordt vastgelegd vóór het gedetecteerde begin van spraak. De standaard 300 ms voorkomt dat de eerste lettergreep wordt afgeknipt. Verhoog dit als gebruikers melden dat hun openingswoorden worden weggesneden.

De parameter silence_duration_ms regelt hoe lang de agent wacht nadat je stopt met spreken voordat hij reageert. Op 200 ms voelen gesprekken responsief aan. Verhoog dit naar 400 of 500 ms voor gebruikers die midden in een zin pauzeren of langzamer spreken.

Voor push-to-talk-interfaces of telefoniesystemen waar je expliciete controle over de gespreksflow nodig hebt, schakel je automatische turn-detectie uit:

session = AgentSession(
 	llm=realtime.RealtimeModel(
     	voice="ara",
     	turn_detection=None,
 	),
 )

De agent wacht dan op een programmatisch signaal voordat hij reageert, in plaats van te luisteren naar stilte.

Grok Voice Agent in productie deployen

De development-modus koppelt de agent aan je lokale machine. Voor een productiedeployment die 24/7 draait en met de vraag schaalt, host LiveKit Cloud je agent op hun infrastructuur.

Voorbereiden op deployment

De LiveKit CLI detecteert je projecttype via dependency-bestanden. Maak een requirements.txt in je agentmap:

livekit-agents[xai,openai]>=1.3.10
python-dotenv>=1.2.1
firecrawl-py>=4.12.0

Maak een apart bestand voor productiegeheimen. LiveKit Cloud levert automatisch LIVEKIT_URL, LIVEKIT_API_KEY en LIVEKIT_API_SECRET, dus je hoeft alleen je andere API-keys op te nemen:

XAI_API_KEY=xai-your-key-here
FIRECRAWL_API_KEY=fc-your-key-here

Sla dit op als .env.production en voeg het toe aan .gitignore.

De agent deployen

Authenticeer de CLI met je LiveKit Cloud-account:

lk cloud auth

Dit opent een browser om je CLI aan je project te koppelen. Eenmaal geauthenticeerd, deploy je de agent:

lk agent create --secrets-file .env.production

De CLI registreert je agent, genereert een Dockerfile, bouwt de containerimage en deployt deze naar LiveKit Cloud. De logs stromen naar je terminal terwijl de agent start:

{"message": "registered worker", "level": "INFO", "name": "livekit.agents", "url": "https://your-project.livekit.cloud", "region": "Germany 2", ...}

Controleer de deploymentstatus:

lk agent status

┌─────────────────┬─────────────────┬────────────┬─────────┬────────┬─────────┬───────────┐
 │ ID          	│ Version     	│ Region 	│ Status  │ CPU	│ Mem 	│ Replicas  │
 ├─────────────────┼─────────────────┼────────────┼─────────┼────────┼─────────┼───────────┤
 │ CA_AAVy5WbUYpmA │ v20260109102531 │ eu-central │ Running │ 0m / 2 │ 0 / 4GB │ 0 / 1 / 1 │
 └─────────────────┴─────────────────┴────────────┴─────────┴────────┴─────────┴───────────┘

Hoe gebruikers toegang krijgen tot je agent

De URL in de deploymentlogs (https://your-project.livekit.cloud) is de WebSocket-backend, geen gebruikersinterface. Gebruikers communiceren met je agent via een frontend die op deze backend aansluit.

De sandbox die je eerder hebt aangemaakt, dient dit doel. Ga naar je LiveKit-dashboard, open het onderdeel Sandbox en kopieer je sandbox-URL. Deze URL is publiek toegankelijk en werkt zonder enige authenticatie. Deel hem met gebruikers en ze kunnen meteen met je agent praten.

Voor een branded ervaring kun je het uiterlijk van de sandbox aanpassen in het dashboard (logo, kleuren, knoptekst) of je eigen frontend bouwen met LiveKit's JavaScript SDK.

Deployments beheren

Bekijk realtime logs van je gedeployde agent:

lk agent logs

Deploy updates nadat je je code hebt aangepast:

lk agent deploy --secrets-file .env.production

LiveKit gebruikt rolling deployments. Nieuwe instanties behandelen nieuwe sessies terwijl bestaande instanties hun actieve gesprekken afronden, dus updates veroorzaken geen downtime.

Ga terug naar een vorige versie als er iets stukgaat:

lk agent rollback

De gedeployde agent draait los van je lokale machine. Sluit je terminal, zet je computer uit: de agent blijft gebruikers beantwoorden. LiveKit Cloud verzorgt het schalen, dus piekverkeer start automatisch extra instanties op.

Kosten van deployment

Een Grok-spraakagent in productie draaien brengt twee kostenposten met zich mee: xAI's API en LiveKit's hosting.

xAI rekent $0,05 per minuut spraakgesprek. LiveKit Cloud rekent $0,01 per minuut agent-sessietijd. Samen kom je uit op ongeveer $0,06 per minuut wanneer je agent actief gebruikers bedient.

De gratis laag van LiveKit (Build-plan) bevat 1.000 agent-sessieminuten per maand, zonder creditcard. Dit dekt zo'n 16 uur aan gesprekken, genoeg voor testen en toepassingen met weinig verkeer. Betaalde plannen beginnen bij $50/maand met 5.000 inbegrepen minuten en hogere gelijktijdigheidslimieten.

De agent kost niets wanneer hij idle is. Er worden alleen kosten in rekening gebracht tijdens actieve gesprekken, dus een deployment die 's nachts ongebruikt blijft, levert geen LiveKit-kosten op. xAI-billing volgt hetzelfde patroon en rekent alleen daadwerkelijke API-gebruik af. Tijdens mijn experimenten voor dit artikel gaf ik in totaal 78 cent uit aan xAI, met LiveKit gedekt door de gratis laag.

Conclusie

Je hebt nu een spraakagent die luistert, nadenkt en terugpraat. De agent verbindt met live data via tools, past zijn luistergedrag aan verschillende omgevingen aan en draait op infrastructuur die schaalt zonder handmatig ingrijpen.

De hier behandelde codepatronen zijn toepasbaar op andere use-cases. Vervang de instructies voor de onderzoeksassistent door richtlijnen voor klantenondersteuning en voeg tools toe die je bestellingsdatabase bevragen. Bouw een taaldocent die zoekt naar voorbeeldzinnen. Maak een spraakinterface voor je bestaande API.

xAI is van plan om zelfstandige text-to-speech- en speech-to-text-endpoints uit te brengen, wat hybride architecturen mogelijk maakt waarbij je Grok's spraakmogelijkheden mengt met andere taalmodellen. Voor nu handelt de voice agent API de volledige pijplijn af.

De documentatie van LiveKit Agents behandelt extra functies zoals overdragen tussen meerdere agents en sessiepersistentie. De xAI-docs gaan dieper in op audioformaten en enterprise-functies.