API Grok Voice Agent : Une approche pour développer des assistants vocaux en temps réel

Les agents vocaux basés sur l'intelligence artificielle connaissent actuellement un grand succès. Les utilisateurs préfèrent interagir avec leurs applications par la voix plutôt que par la saisie, et la technologie est désormais suffisamment avancée pour rendre ces conversations naturelles.

Si vous souhaitez en créer un, l'API Grok Voice Agent de xAI constitue un excellent point de départ. Il offre des temps de réponse inférieurs à la seconde et des coûts inférieurs à la plupart des alternatives, ainsi qu'une compatibilité immédiate avec le code OpenAI existant.

Ce tutoriel vous montre comment créer un agent vocal fonctionnel à partir de zéro. Vous pourrez configurer l'authentification, personnaliser les options vocales, ajouter des outils d'appel et déployer en production avec LiveKit cloud. L'API fonctionne sur Grok 3, que xAI a adapté pour les conversations vocales en temps réel au lieu du flux de travail habituel de saisie et de sortie de texte.

Qu'est-ce que l'API Grok Voice Agent ?

L'API Grok Voice Agent est la plateforme de conversation vocale en temps réel de xAI, lancée en décembre 2025. Il traite directement le son sans passer par la conversion habituelle de la parole en texte et vice versa, ce qui réduit le temps de réponse tout en conservant le naturel des conversations.

Les systèmes traditionnels d'intelligence artificielle vocale combinent trois étapes distinctes : la transcription de la parole en texte, le traitement de ce texte à l'aide d'un modèle linguistique, puis la synthèse de la réponse en audio. Cette approche est efficace, mais chaque transfert entre les composants entraîne un retard. Une fois que vous avez pris en compte la transcription, le traitement et la synthèse, il faut compter entre 500 et 1 000 ms avant que l'utilisateur obtienne une réponse. Ces pauses s'accumulent et rendent les conversations peu naturelles.

Grok Voice Agent élimine complètement les conversions. Le système traite les données audio, effectue des raisonnements dans le domaine audio et génère des données audio à l'aide d'un modèle unique formé à la parole conversationnelle. Cette architecture offre un temps de réponse audio moyen de 0,78 seconde tout en prenant en charge la communication en duplex intégral (communication audio bidirectionnelle simultanée permettant à l'agent d'écouter et de parler en même temps), ce qui permet à l'agent de répondre sans attendre son tour.

Configuration de votre environnement Grok Voice Agent

Pour créer un agent vocal avec Grok, il est nécessaire de l'associer à LiveKit, une plateforme WebRTC open source. Grok fournit le modèle d'IA conversationnelle, tandis que LiveKit gère l'infrastructure audio en temps réel qui relie les utilisateurs à votre agent. Cette section traite de la configuration des deux services.

Configuration de Grok

Veuillez consulter console.x.ai et créez un compte en utilisant l'authentification X, e-mail, Google ou Apple. La console xAI nécessite des crédits prépayés avant de pouvoir effectuer des appels API. Veuillez acquérir des crédits via la section Facturation.

Une fois les crédits disponibles sur votre compte, veuillez vous rendre dans la section Clés API et générer une nouvelle clé. La console affiche la clé une seule fois, veuillez donc la copier immédiatement et la conserver en lieu sûr. En cas de perte, il sera nécessaire de générer un nouveau document et de mettre à jour vos applications. Pour une présentation plus approfondie de l'écosystème API de xAI, veuillez consulter le tutoriel sur l'API Grok 3.

Configuration de LiveKit

LiveKit est une infrastructure WebRTC pour l'audio et la vidéo en temps réel. Il gère la couche de transport audio dont Grok a besoin pour se connecter aux utilisateurs. Lors de la création d'un agent vocal, LiveKit gère les salles où se déroulent les conversations, achemine les flux audio entre les participants et fournit l'infrastructure de déploiement. Le framework LiveKit Agents gère cette complexité, vous permettant de vous concentrer sur le comportement de l'agent tandis qu'il s'occupe de la gestion des connexions, de l'encodage audio et de la détection des tours de parole.

Le cadre prend en charge plusieurs fournisseurs d'IA, y compris xAI. Il comprend un environnement de test accessible via une interface Web, que vous utiliserez pour valider votre agent avant de le déployer.

Veuillez vous inscrire sur cloud.livekit.io. Le niveau gratuit fournit suffisamment de ressources pour le développement et les tests. Veuillez créer un projet via le tableau de bord. Veuillez vous rendre dans Paramètres, puis Clés API. Veuillez copier les trois informations d'identification suivantes : LIVEKIT_URL (le point de terminaison WebSocket de votre projet), LIVEKIT_API_KEY (l'identifiant public) et LIVEKIT_API_SECRET (la clé d'authentification privée). Ces informations d'identification permettent d'authentifier votre code agent auprès de votre projet LiveKit cloud.

Installation des dépendances et configuration

Veuillez installer les paquets requis :

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

Cela installe le framework LiveKit agents avec le plugin xAI et les dépendances OpenAI (le plugin xAI s'appuie sur la compatibilité avec l'API Realtime d'OpenAI), ainsi que python-dotenv pour la gestion des variables d'environnement.

Veuillez créer un fichier .env à la racine de votre projet :

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

Veuillez remplacer les valeurs par défaut par vos informations d'identification réelles. Veuillez charger ces informations d'identification dans votre code Python :

from dotenv import load_dotenv
 load_dotenv()

Cela rend les informations d'identification accessibles aux bibliothèques xAI et LiveKit. Veuillez ajouter .env à votre fichier.gitignore afin d'éviter toute fuite d'informations d'identification dans le contrôle de version.

Création de votre premier agent vocal Grok

Une fois votre environnement configuré, vous pouvez créer un agent vocal fonctionnel. Commencez par les importations et la classe agent dans un nouveau fichier nommé 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.",
 	)

Votre sous-classe d'Agent s contient uniquement les instructions qui déterminent la manière dont l'agent répond. Ces éléments fonctionnent comme une invite système, indiquant à l'agent le rôle qu'il doit jouer. La configuration réelle du modèle se trouve ailleurs.

Ensuite, veuillez configurer le serveur et le gestionnaire de connexion :

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

Le décorateur ` @server.rtc_session() ` indique à LiveKit d'exécuter votre fonction d'entrée de ligne de commande chaque fois qu'un utilisateur se connecte. À l'intérieur, AgentSession gère la configuration du modèle, y compris le choix de l'une des sept voix de Grok à utiliser (Ara, Eve, Leo, Sal, Rex, Mika ou Valentin). Lorsque session.start() est exécuté, il connecte votre agent à la salle LiveKit où se déroule la conversation.

Les conversations vocales impliquent d'attendre l'entrée et la sortie audio sans bloquer le programme. Par conséquent, la fonction utilise async def et await pour gérer ces opérations simultanément.

Enfin, veuillez ajouter le point d'entrée :

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

Veuillez exécuter votre agent en mode développement :

uv run agent.py dev

Le terminal affiche la séquence de démarrage : initialisation des workers, écoute du serveur HTTP sur un port local et enregistrement auprès de votre projet LiveKit cloud.

Pour tester l'agent, veuillez vous rendre sur votre tableau de bord LiveKit Cloud à l'adresse cloud.livekit.io. Veuillez sélectionner votre projet, puis cliquer sur l'onglet Sandbox dans la barre latérale. Veuillez sélectionner l'agent vocal Web parmi les modèles.

La page du modèle affiche un aperçu de l'interface vocale ainsi que des informations détaillées sur son contenu. Veuillez cliquer sur le bouton Créer un bac à sable.

Dans la fenêtre modale qui s'affiche, vous pouvez configurer une URL personnalisée, activer des fonctionnalités telles que le partage de caméra et d'écran, et ajuster les paramètres d'apparence. Les paramètres par défaut conviennent parfaitement pour les tests. Veuillez cliquer sur Créer, puis sur Terminé.

De retour sur la page Sandbox, votre nouvelle sandbox apparaît sous Applications Sandbox. Veuillez cliquer sur « Lancer » pour l'ouvrir.

Veuillez cliquer sur « Démarrer l'appel » et accorder les autorisations pour le microphone lorsque vous y êtes invité. Veuillez surveiller le terminal pour ce message de journal, qui indique que l'agent est prêt à recevoir l'audio :

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

Une fois ce message affiché, les réponses ne tardent pas à arriver.

Lorsque vous posez une question à laquelle l'agent ne peut pas répondre (comme la météo actuelle dans une ville spécifique), il explique ses limites plutôt que d'inventer des informations.

Comment ajouter des outils à vos agents vocaux Grok

L'agent de base est capable de tenir une conversation, mais ne dispose d'aucun moyen pour effectuer des recherches. L'appel d'outils permet à Grok d'exécuter des fonctions au cours d'une conversation et de communiquer les résultats. Vous pouvez utiliser les outils intégrés de xAI ou définir les vôtres.

Utilisation des outils intégrés

Le plugin xAI comprend WebSearch pour les requêtes web générales et XSearch pour la recherche de publications sur X. Veuillez les importer et les transmettre à 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)

Le paramètre « tools » accepte une liste d'objets outils. Veuillez exécuter l'agent et le tester avec des questions telles que « Quelles sont les dernières actualités concernant l'IA ? » ou « Que pensent les utilisateurs de Grok sur X ? » Les journaux du terminal peuvent afficher des avertissements concernant des fonctions AI inconnues telles que web_search_with_snippets ou x_semantic_search, mais les outils renvoient néanmoins les informations actuelles.

L'audio full-duplex de Grok est également perceptible lors de l'utilisation d'outils. Vous pouvez interrompre l'agent pendant qu'il parle, et il s'arrête, écoute et adapte sa réponse. Cela rend les conversations moins robotiques que les systèmes qui nécessitent d'attendre que l'agent ait terminé avant de pouvoir parler.

Ajout d'outils personnalisés

Les outils intégrés couvrent les cas d'utilisation courants, mais la définition de vos propres outils vous permet de contrôler les paramètres, la gestion des erreurs et les API à appeler. Cette section présente la création d'un outil personnalisé à l'aide de point de terminaison de recherche de Firecrawl, qui propose des options de filtrage telles que limit, lang et country que la recherche Web intégrée ne propose pas.

Veuillez vous inscrire sur firecrawl.dev. L'offre gratuite comprend 500 crédits et ne nécessite aucune carte de crédit. Veuillez installer le SDK et ajouter votre clé à l'adresse .env:

uv add firecrawl-py

FIRECRAWL_API_KEY=fc-your-key-here

Les outils personnalisés sont des méthodes décorées avec l'@function_tool(). Veuillez mettre à jour les importations dans 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()

Les ajouts sont function_tool pour le décorateur, RunContext qui est transmis aux fonctions de l'outil, et FirecrawlApp pour le client Firecrawl. WebSearch est supprimé car l'outil personnalisé le remplace.

Définissez l'outil en tant que méthode dans votre classe d'agent :

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 lit la chaîne de documentation pour comprendre le fonctionnement de l'outil. Lorsque vous demandez « Quel est le taux de change actuel entre l'USD et l'EURO ? », Grok extrait la requête, appelle votre fonction et intègre les résultats dans sa réponse.

Les méthodes décorées avec @function_tool() s'enregistrent automatiquement, veuillez donc supprimer WebSearch() de la liste des outils :

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

Veuillez exécuter l'agent mis à jour :

uv run search_agent.py dev

Le terminal affiche l'exécution de l'outil :

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

Lors de mes essais, Firecrawl a fourni des résultats en environ deux secondes. Vous pouvez associer plusieurs outils personnalisés aux outils intégrés dans le même agent. Un agent du service clientèle, par exemple, peut utiliser XSearch en complément d'outils personnalisés tels que lookup_order() et check_inventory() qui se connectent à des bases de données internes.

Personnalisation de la détection des virages

Les paramètres par défaut de détection des tours de parole sont efficaces pour les conversations courantes. Des ajustements sont nécessaires lorsque l'environnement ou le comportement des utilisateurs diffère de la norme. Une pièce bruyante peut amener l'agent à réagir aux bruits de fond, tandis qu'un utilisateur qui fait une pause pour rassembler ses idées peut être interrompu avant d'avoir terminé.

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

Le paramètre « threshold » définit le niveau sonore requis pour que le son soit considéré comme de la parole, sur une échelle comprise entre 0,0 et 1,0. Augmenter cette valeur à 0,7 ou plus est utile dans les environnements bruyants où les sons de fond pourraient autrement déclencher des réponses.

Le paramètreprefix_padding_ms e détermine la quantité d'audio à capturer avant le début détecté de la parole. La valeur par défaut de 300 ms empêche la première syllabe d'être tronquée. Augmentez cette valeur si les utilisateurs signalent que leurs premiers mots sont coupés.

Le paramètre « silence_duration_ms » (Délai de réponse de l'agent) contrôle le temps d'attente de l'agent après que vous ayez cessé de parler avant qu'il ne réponde. À 200 ms, les conversations semblent réactives. En augmentant cette durée à 400 ou 500 ms, on s'adapte aux utilisateurs qui marquent une pause au milieu d'une phrase ou qui parlent plus lentement.

Pour les interfaces push-to-talk ou les systèmes téléphoniques où un contrôle explicite du flux de conversation est nécessaire, veuillez désactiver la détection automatique des tours de parole :

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

L'agent attend alors un signal programmatique avant de répondre, plutôt que d'écouter le silence.

Déploiement de Grok Voice Agent en production

Le mode développement lie l'agent à votre machine locale. Pour un déploiement de production fonctionnant 24 heures sur 24, 7 jours sur 7, et évoluant en fonction de la demande, LiveKit Cloud héberge votre agent sur son infrastructure.

Préparation au déploiement

L'interface CLI LiveKit identifie le type de votre projet à l'aide des fichiers de dépendance. Veuillez créer un fichier requirements.txt dans votre répertoire agent :

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

Veuillez créer un fichier distinct pour les secrets de production. LiveKit cloud fournit automatiquement LIVEKIT_URL, LIVEKIT_API_KEY et LIVEKIT_API_SECRET. Il vous suffit donc d'inclure vos autres clés API :

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

Veuillez enregistrer ce fichier sous le nom « .env.production » et l'ajouter à l'adresse «.gitignore ».

Déploiement de l'agent

Veuillez authentifier l'interface CLI avec votre compte LiveKit cloud :

lk cloud auth

Cela ouvre un navigateur pour relier votre CLI à votre projet. Une fois authentifié, veuillez déployer l'agent :

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

L'interface CLI enregistre votre agent, génère un fichier Dockerfile, crée l'image du conteneur et la déploie sur LiveKit Cloud. Les journaux sont transmis à votre terminal dès le démarrage de l'agent :

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

Veuillez vérifier l'état du déploiement :

lk agent status

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

Comment les utilisateurs accèdent à votre agent

L'URL figurant dans les journaux de déploiement (https://your-project.livekit.cloud) correspond au backend WebSocket et non à une interface utilisateur. Les utilisateurs interagissent avec votre agent via une interface utilisateur qui se connecte à ce backend.

Le bac à sable que vous avez créé précédemment remplit cette fonction. Veuillez accéder à votre tableau de bord LiveKit, ouvrir la section Sandbox et copier l'URL de votre sandbox. Cette URL est accessible au public et fonctionne sans aucune authentification. Partagez-le avec les utilisateurs et ils pourront immédiatement commencer à communiquer avec votre agent.

Pour une expérience personnalisée, modifiez l'apparence du bac à sable dans le tableau de bord (logo, couleurs, texte des boutons) ou créez votre propre interface à l'aide du SDK JavaScript de LiveKit. SDK JavaScript de LiveKit.

Gestion des déploiements

Consultez les journaux en temps réel de votre agent déployé :

lk agent logs

Veuillez déployer les mises à jour après avoir modifié votre code :

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

LiveKit utilise des déploiements progressifs. Les nouvelles instances gèrent les nouvelles sessions tandis que les instances existantes terminent leurs conversations actives, de sorte que les mises à jour n'entraînent aucun temps d'arrêt.

Revenez à une version précédente si un problème survient :

lk agent rollback

L'agent déployé fonctionne indépendamment de votre machine locale. Veuillez fermer votre terminal, éteindre votre ordinateur, et l'agent continuera à répondre aux utilisateurs. LiveKit Cloud gère la mise à l'échelle, de sorte que les pics de trafic déclenchent automatiquement la création d'instances supplémentaires.

Coûts de déploiement

L'utilisation d'un agent vocal Grok en production implique deux coûts : l'API de xAI et l'hébergement de LiveKit.

xAI facture 0,05 $ par minute de conversation vocale. LiveKit cloud facture 0,01 $ par minute de session d'agent. Au total, prévoyez environ 0,06 $ par minute lorsque votre agent est en service actif auprès des utilisateurs.

L'offre gratuite de LiveKit (formule Build) comprend 1 000 minutes de session par agent et par mois, sans obligation de fournir de numéro de carte de crédit. Cela représente environ 16 heures de conversation, ce qui est suffisant pour les tests et les applications à faible trafic. Les forfaits payants commencent à 50 $ par mois, avec 5 000 minutes incluses et des limites de concurrence plus élevées.

L'agent n'entraîne aucun coût lorsqu'il est inactif. Les frais ne s'appliquent que pendant les conversations actives, de sorte qu'un déploiement inutilisé pendant la nuit n'entraîne aucun frais LiveKit. La facturation xAI suit le même modèle, ne comptabilisant que l'utilisation réelle de l'API. Au cours de mes expériences pendant la rédaction de cet article, j'ai dépensé un total de 78 cents sur xAI, LiveKit étant couvert par son offre gratuite.

Conclusion

Vous disposez désormais d'un assistant vocal qui écoute, réfléchit et répond. L'agent se connecte aux données en temps réel à l'aide d'outils, adapte son comportement d'écoute à différents environnements et fonctionne sur une infrastructure évolutive sans intervention manuelle.

Les modèles de code présentés ici s'appliquent également à d'autres cas d'utilisation. Veuillez remplacer les instructions destinées aux assistants de recherche par les directives relatives au service client et ajouter des outils permettant d'interroger votre base de données de commandes. Développez un tuteur linguistique qui recherche des exemples de phrases. Veuillez créer une interface vocale pour votre API existante.

xAI prévoit de lancer des points de terminaison autonomes de synthèse vocale et de reconnaissance vocale, qui permettront de créer des architectures hybrides où vous pourrez combiner les capacités vocales de Grok avec d'autres modèles linguistiques. Pour le moment, l'API de l'agent vocal gère l'ensemble du pipeline.

La documentation LiveKit Agents traite de fonctionnalités supplémentaires telles que les transferts multi-agents et la persistance des sessions. La documentation xAI fournit des informations détaillées sur les formats audio et les fonctionnalités pour les entreprises.