Apprendre

Créer un agent vocal avec Pipecat et Cartesia

Rene 
Créer un agent vocal avec Pipecat et Cartesia

Pipecat est un framework Python open source pour agents vocaux en temps réel. Cartesia lui fournit des services vocaux intégrés : Sonic pour la synthèse vocale en streaming et Ink pour la transcription. Dans ce guide, vous exécuterez un agent vocal dans votre navigateur avec les deux services, puis utiliserez les prédictions de fin de tour anticipées d’Ink pour retirer environ une demi-seconde à chaque réponse.

L’ensemble demande de cloner le dépôt et de définir deux variables d’environnement. L’agent obtenu écoute, détermine quand vous avez fini de parler, réfléchit et répond à voix haute.

Vue d’ensemble

Un agent vocal Pipecat est une chaîne de processeurs. L’audio arrive par un transport, est transcrit, passe par un LLM et ressort sous forme de parole :

transport.input() → STT → LLM → TTS → transport.output()

Deux étapes déterminent si une conversation paraît humaine ou ressemble à un talkie-walkie : savoir quand l’utilisateur a vraiment fini de parler et prononcer rapidement la réponse. C’est là qu’interviennent les services Cartesia. CartesiaTurnsSTTService utilise Ink 2, le modèle STT en streaming de Cartesia, et laisse le serveur décider de la fin du tour au lieu de l’estimer localement. CartesiaTTSService diffuse l’audio Sonic pendant sa génération, avec des horodatages par mot si nécessaire.

La documentation de Pipecat situe l’aller-retour typique entre 500 et 800 millisecondes. Les étapes suivantes visent à consacrer ce budget au modèle plutôt qu’aux silences.

Prérequis

  1. Python 3.11 ou version ultérieure. Le README du dépôt Pipecat précise la version minimale actuelle.
  2. Une clé API Cartesia, à créer dans le tableau de bord.
  3. Une clé API pour le LLM qui prend les décisions. L’exemple utilise OpenAI (OPENAI_API_KEY) ; Pipecat fournit aussi des services pour Anthropic, Gemini, Groq, Ollama et d’autres modèles.

Une limite de périmètre : Ink 2 ne prend actuellement en charge que l’anglais. Cet agent écoute donc en anglais. Sonic parle plus de 40 langues ; la langue de réponse n’est pas la contrainte.

1. Installer les extras importés par l’exemple

Le dépôt Pipecat contient un agent Cartesia prêt à l’emploi dans examples/voice/voice-cartesia-turns.py :

git clone https://github.com/pipecat-ai/pipecat.git
cd pipecat
uv sync --extra cartesia --extra daily --extra websocket --extra runner --extra webrtc

Un simple uv sync installe le framework, mais pas les extras importés par cet exemple. Le fichier importe les transports Daily et FastAPI WebSocket ainsi que le runner Pipecat dès le début, même avec -t webrtc. Ces extras doivent donc être présents, sinon l’import échoue avec No module named 'daily'. cartesia et webrtc sont les éléments effectivement utilisés.

Si vous créez votre propre projet plutôt que de travailler dans le dépôt Pipecat, installez le même ensemble :

pip install "pipecat-ai[cartesia,daily,websocket,runner,webrtc]"

Copiez ensuite examples/voice/voice-cartesia-turns.py du dépôt dans votre projet. L’exemple exige CARTESIA_API_KEY et OPENAI_API_KEY ; placez-les dans un fichier .env à côté du script :

CARTESIA_API_KEY=your-key-here
OPENAI_API_KEY=your-key-here

2. Exécuter l’agent

uv run examples/voice/voice-cartesia-turns.py -t webrtc

Le runner démarre un serveur local et affiche une URL, par défaut http://localhost:7860. Ouvrez-la, autorisez le microphone et parlez. Voici le fonctionnement interne :

  1. Le navigateur envoie votre audio par WebRTC.
  2. CartesiaTurnsSTTService le transcrit avec Ink 2. Le serveur surveille les limites de tours et émet les événements turn.start, turn.update, turn.eager_end et turn.end.
  3. Le LLM rédige une réponse.
  4. CartesiaTTSService diffuse la réponse avec Sonic ; le transport la lit à mesure qu’elle arrive.

Le point intéressant est l’étape 2. Les anciennes configurations ajoutent un détecteur d’activité vocale à l’audio pour estimer la fin d’une phrase. La détection de tours d’Ink 2 s’exécute sur le serveur, ce qui permet l’étape suivante.

3. Choisir la voix et le LLM

L’exemple fournit un identifiant vocal et un prompt système simple. Vous pouvez modifier les deux :

tts = CartesiaTTSService(
    api_key=os.environ["CARTESIA_API_KEY"],
    settings=CartesiaTTSService.Settings(
        voice="86e30c1d-714b-4074-a1f2-1cb6b552fb49",
    ),
)

Choisissez une voix dans le Playground et collez son identifiant ici, ou créez-en une à partir d’un court échantillon avec le clonage vocal. Le modèle prononce le texte : rédigez donc le prompt pour l’oral. L’exemple d’origine demande au LLM d’éviter emojis, listes à puces et autres mises en forme inaudibles.

Pour utiliser une version précise de Sonic, passez-la dans le même objet de réglages. Le service utilise actuellement sonic-3.6 par défaut.

4. Gagner une demi-seconde avec les fins de tour anticipées

À la fin d’une phrase, Ink prédit que vous avez terminé avant la fin technique et émet turn.eager_end. Pipecat expose cette prédiction via l’événement on_turn_eager_end(service, transcript). Vous pouvez ainsi lancer immédiatement la génération de réponse, puis reprendre l’écoute si l’utilisateur continue :

stt = CartesiaTurnsSTTService(
    api_key=os.environ["CARTESIA_API_KEY"],
    enable_eager_end_of_turn=True,
)

@stt.event_handler("on_turn_eager_end")
async def on_turn_eager_end(service, transcript):
    # Ink predicted the user's turn is ending. Start the LLM now.
    ...

L’option enable_eager_end_of_turn=True est nécessaire : elle demande à Pipecat d’agir sur la prédiction anticipée du serveur plutôt que d’attendre la fin de tour confirmée. Pipecat publie un exemple d’agrégateur utilisateur spéculatif qui gère le cycle complet : il lance le LLM sur la prédiction et continue d’écouter au cas où vous reprendriez. La documentation Cartesia estime le gain à environ une demi-seconde, la différence entre un agent qui répond et un agent qui attend son tour.

Si l’agent intervient pendant que vous réfléchissez, ajustez les seuils plutôt que de désactiver les fins anticipées. Les quatre paramètres et leurs valeurs Cartesia par défaut sont turn_start_threshold (0.8), turn_eager_end_threshold (0.4), turn_end_threshold (0.2) et turn_end_timeout_ms (5600). Un agent patient attend davantage avant de miser sur la fin de votre intervention : il exige plus de certitude avant d’interrompre. Abaissez le seuil de fin anticipée vers 0.3 et augmentez le délai vers 8000.

Placez les noms réellement utilisés par vos utilisateurs, comme les produits et le vocabulaire d’entreprise, dans Settings(keyterm=["Pipecat", "Ink 2"]), pour aider la transcription à les reconnaître.

Étapes suivantes

  1. Reliez l’agent à un numéro de téléphone : relancez le même exemple avec -t twilio et un proxy public. Le pipeline fonctionne sans changement sur les appels.
  2. Si vous préférez ne pas gérer le pipeline, créez le même agent sur Managed Agents, qui gère téléphonie, outils et connaissances.
  3. Besoin de fichiers audio plutôt que d’une conversation en direct ? La synthèse par lots utilise CartesiaHttpTTSService, dans le même paquet.

Documentation associée

FAQ

Pipecat prend-il en charge Cartesia ?

Oui. Cartesia est un service intégré au dépôt Pipecat, avec un service TTS en streaming (CartesiaTTSService) et deux services STT, dont CartesiaTurnsSTTService. Ce dernier utilise Ink 2 et laisse le serveur Cartesia déterminer les limites des tours. Installez pipecat-ai avec l'extra cartesia, ainsi que les extras de transport et de runner importés par votre point d'entrée, puis définissez CARTESIA_API_KEY.

Quels modèles l'intégration Cartesia utilise-t-elle ?

Le service TTS diffuse Sonic, le modèle vocal temps réel de Cartesia, et utilise sonic-3.6 par défaut dans les versions actuelles de Pipecat. Le service STT de tours utilise Ink 2 (ink-2), qui détecte les tours sur le serveur et émet des prédictions turn.eager_end. Passez model= dans Settings pour choisir une autre version de Sonic.

Quel est le temps de réponse d'un agent vocal Pipecat ?

La documentation de Pipecat indique un aller-retour typique de 500 à 800 millisecondes. Vous pouvez raccourcir deux étapes : la détection de tours et la synthèse vocale. La prédiction anticipée d'Ink peut réduire le délai d'environ une demi-seconde en lançant la réponse avant la fin formelle du tour de l'utilisateur.

L'agent peut-il prendre des appels téléphoniques ?

Oui. Pipecat fournit des transports téléphoniques pour Twilio, Exotel et Plivo. Le même pipeline fonctionne au téléphone avec -t twilio et un proxy public. Si vous préférez ne pas gérer le pipeline, Cartesia Managed Agents permet de créer sans code des agents pour appels entrants et sortants.

Dois-je utiliser OpenAI pour le LLM ?

Non. L'exemple utilise OpenAILLMService pour sa concision, mais Pipecat fournit des services pour de nombreux fournisseurs, dont Anthropic, Gemini, Groq et Ollama en local. Remplacez le service dans le pipeline et conservez les services STT et TTS Cartesia.