WebSocket met meerdere contexten
Deze handleiding laat zien hoe je realtime-spraakagenten bouwt met de WebSocket API met meerdere contexten.
Spraakagenten orkestreren met deze WebSocket API met meerdere contexten is een complexe taak die wordt aanbevolen voor gevorderde ontwikkelaars. Bekijk voor een meer beheerde oplossing ons product Agents Platform product, dat veel van deze uitdagingen vereenvoudigt.
Overzicht
Voor het bouwen van responsieve spraakagenten moet je audiostreams dynamisch kunnen beheren, onderbrekingen soepel kunnen afhandelen en natuurlijk klinkende spraak gedurende gespreksbeurten kunnen behouden. Onze WebSocket API met meerdere contexten voor Text to Speech (TTS) is specifiek ontworpen voor deze scenario’s.
Deze API breidt onze standaard TTS WebSocket-functionaliteit uit met het concept van “contexten”. Elke context werkt als een onafhankelijke audiogeneratiestream binnen één WebSocket-verbinding. Hiermee kun je:
- Meerdere spraakregels tegelijkertijd beheren (bijvoorbeeld een agent die spreekt terwijl die een reactie voorbereidt op een onderbreking door een gebruiker).
- Onderbrekingen door gebruikers soepel afhandelen door een bestaande spraakcontext te sluiten en een nieuwe te starten.
- Prosodische consistentie behouden voor uitingen binnen dezelfde logische context.
- Het gebruik van resources optimaliseren door contexten die niet meer nodig zijn selectief te sluiten.
De WebSocket API met meerdere contexten is geoptimaliseerd voor spraaktoepassingen en is niet bedoeld voor het gelijktijdig genereren van meerdere niet-gerelateerde audiostreams. Daarom is elke verbinding beperkt tot 5 gelijktijdige contexten.
Deze handleiding helpt je bij het verbinden met de WebSocket met meerdere contexten, het beheren van contexten en het toepassen van best practices voor het bouwen van aantrekkelijke spraakagenten.
Best practices
Deze best practices zijn essentieel voor het bouwen van responsieve, efficiënte spraakagenten met onze WebSocket API met meerdere contexten.
Gebruik één WebSocket-verbinding
Maak één WebSocket-verbinding voor elke sessie van een eindgebruiker. Dit vermindert overhead en latentie vergeleken met het maken van meerdere verbindingen. Binnen deze ene verbinding kun je meerdere contexten voor verschillende delen van het gesprek beheren.
Stream reacties in chunks, genereer zinnen
Stream bij het genereren van lange reacties de tekst in kleinere chunks en gebruik de vlag flush: true
aan het einde van volledige zinnen. Dit verbetert de kwaliteit van de gegenereerde audio en de
responsiviteit.
Ga soepel om met onderbrekingen
Stream tekst naar één context totdat er een onderbreking plaatsvindt, maak vervolgens een nieuwe context en sluit de bestaande. Deze aanpak zorgt voor vloeiende overgangen wanneer het gespreksverloop verandert.
Beheer de levenscyclus van contexten
Sluit ongebruikte contexten snel. De server kan per verbinding maximaal 5 gelijktijdige contexten behouden, maar sluit contexten wanneer ze niet meer nodig zijn.
Voorkom context-time-outs
Contexten verlopen standaard na 20 seconden en worden automatisch gesloten. De inactiviteits- time-out is een parameter op WebSocket-niveau die op alle contexten van toepassing is en indien nodig maximaal 180 seconden kan zijn. Stuur een leeg tekstbericht naar een context om de time-outklok opnieuw in te stellen.
Onderbrekingen afhandelen
Wanneer een gebruiker je agent onderbreekt, moet je de huidige context sluiten en een nieuwe maken:
Een context actief houden
Contexten verlopen automatisch na standaard 20 seconden inactiviteit. Als je een context actief moet houden zonder tekst te genereren (bijvoorbeeld tijdens een verwerkingsvertraging), kun je een leeg tekstbericht sturen om de time-outklok opnieuw in te stellen.
De WebSocket-verbinding sluiten
Wanneer je gesprek eindigt, kun je alle contexten opruimen door de socket te sluiten:
Volledig voorbeeld van een conversatieagent
Vereisten
- Een ElevenLabs-account met een API-sleutel (lees hoe je je API-sleutel vindt).
- Python of Node.js (of een andere JavaScript-runtime) geïnstalleerd op je computer.
- Kennis van WebSocket-communicatie. We raden aan onze handleiding voor standaard WebSocket-streaming te lezen voor de basisconcepten.
Installatie
Installeer de benodigde dependencies voor de taal van je keuze:
Maak een .env-bestand in de directory van je project om je API-sleutel op te slaan: