Guida rapida di Speech Engine
Questa guida ti mostra come creare un agente vocale con Speech Engine. Configurerai un server che collega il tuo LLM a ElevenLabs, quindi un client nel browser per consentire agli utenti di conversare a voce con il tuo agente.
Usa la skill Speech Engine di ElevenLabs per aggiungere la voce al tuo agente chat:
Come funziona Speech Engine
Speech Engine collega il tuo LLM a ElevenLabs, così gli utenti possono parlare con il tuo agente e ascoltarne le risposte. ElevenLabs gestisce Speech to Text e Text to Speech; il tuo server fornisce la logica dell’LLM.
Ogni connessione WebSocket rappresenta una conversazione. Quando l’utente parla, ElevenLabs trascrive l’audio e invia la trascrizione al tuo server. Il tuo server la passa al tuo LLM, quindi trasmette la risposta in streaming. ElevenLabs converte il testo in parlato e lo riproduce nel browser. L’SDK gestisce la connessione, l’alternanza dei turni e il rilevamento delle interruzioni.
Prerequisiti
Questo tutorial usa l’API di OpenAI per l’LLM. Ti serve una chiave API OpenAI impostata nella variabile d’ambiente OPENAI_API_KEY.
Configurazione del server
Crea una chiave API
Crea qui una chiave API nella dashboard, che userai per accedere all’API in modo sicuro.
Archivia la chiave come segreto gestito e passala agli SDK come variabile d’ambiente tramite un file .env oppure direttamente nella configurazione della tua app, in base alle tue preferenze.
Esponi il server
Speech Engine richiede un URL raggiungibile pubblicamente. Usa ngrok per esporre il tuo server locale. Il server non è ancora stato creato, ma ngrok deve essere già in esecuzione per avere l’URL necessario al passaggio successivo.
Copia l’URL di inoltro (ad esempio https://abc123.ngrok.io).
Crea un'istanza di Speech Engine
Usa l’SDK per creare un’istanza di Speech Engine, passando il tuo URL ngrok con il path /ws aggiunto come URL WebSocket.
Esegui questo script e copia l’ID di Speech Engine (ad esempio seng_8k3m9xr4hjnfg983brhmhkd98n6) per il passaggio successivo.
Crea il server
Crea un file denominato server.py o server.mts con il seguente contenuto. Verrà configurato un server, collegato Speech Engine sul path /ws e usato OpenAI per generare le risposte.
Il callback onTranscript / on_transcript riceve la cronologia completa della conversazione e la sessione corrente. L’SDK TypeScript fornisce anche un AbortSignal che si attiva se l’utente interrompe la risposta. Passare signal alla chiamata OpenAI annulla automaticamente la richiesta LLM in caso di interruzione.
sendResponse() / send_response() accetta una stringa, un iterabile asincrono o uno stream di OpenAI, Anthropic o Google Gemini. L’SDK estrae automaticamente il contenuto testuale.
Nell’esempio precedente, la trascrizione completa dell’utente viene passata all’LLM. In un ambiente di produzione dovresti aggiungere guardrail per prevenire tentativi di prompt injection o manipolazione.
Configurazione del client
Crea un endpoint per il token
Aggiungi un endpoint lato server che generi un token di conversazione. In questo modo la tua chiave API non viene esposta nel browser e viene usato WebRTC per la migliore qualità audio.
Crea l'interfaccia della conversazione
Recupera il token di conversazione dal tuo server e usalo per avviare una sessione.
React
JavaScript
Provalo
Assicurati che siano in esecuzione tre processi:
- ngrok - inoltro alla porta 3001
- Il tuo server Speech Engine -
python server.pyonpx tsx server.mts - Il server dei token -
npx tsx token-server.mtsopython token_server.py
Apri l’applicazione client nel browser e fai clic su Avvia conversazione. Quando richiesto, concedi l’accesso al microfono, quindi parla. Dovresti sentire l’agente rispondere dagli altoparlanti.
Se hai abilitato debug: true sul server, vedrai le trascrizioni in arrivo e le risposte in uscita registrate nella console.
Eventi della sessione
Configurare il primo messaggio dell’agente
Per impostazione predefinita, l’agente attende che l’utente parli per primo. Per fare in modo che l’agente saluti l’utente all’avvio della conversazione, imposta un primo messaggio nell’opzione overrides sul client quando avvii la sessione.
Il primo messaggio viene pronunciato dall’agente non appena viene stabilita la connessione. Non attiva il callback onTranscript sul tuo server: viene gestito interamente da ElevenLabs.
Configurare la durata massima della conversazione
Per impostazione predefinita, una conversazione termina dopo 600 secondi (10 minuti). Speech Engine supporta conversazioni fino a 7.200 secondi (2 ore). Per consentire conversazioni più lunghe, aggiorna la risorsa Speech Engine con un valore max_duration_seconds più alto:
Puoi impostarlo anche nella dashboard: apri Speech Engine, vai alla scheda Avanzate e imposta Durata massima della conversazione in Comportamento conversazionale.