Vai alla navigazione

Guida rapida di Speech Engine

Aggiungi la voce al tuo agente chat con l'SDK di ElevenLabs.

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:

npx skills add elevenlabs/skills --skill speech-engine

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

1

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.

.env
ELEVENLABS_API_KEY=<your_api_key_here>
2

Installa le dipendenze

pip install elevenlabs openai python-dotenv
3

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.

ngrok http 3001

Copia l’URL di inoltro (ad esempio https://abc123.ngrok.io).

4

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.

import asyncio
from dotenv import load_dotenv
from elevenlabs import AsyncElevenLabs
load_dotenv()
elevenlabs = AsyncElevenLabs(
api_key=os.getenv("ELEVENLABS_API_KEY"),
)
async def main():
engine = await elevenlabs.speech_engine.create(
name="My Speech Engine",
speech_engine={
# Note we use the wss protocol instead of https
"ws_url": "wss://abc123.ngrok.io/ws",
},
)
print(f"Speech Engine ID: {engine.engine_id}")
if __name__ == "__main__":
asyncio.run(main())

Esegui questo script e copia l’ID di Speech Engine (ad esempio seng_8k3m9xr4hjnfg983brhmhkd98n6) per il passaggio successivo.

5

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.

import asyncio
import os
from dotenv import load_dotenv
from openai import AsyncOpenAI
from elevenlabs import AsyncElevenLabs
load_dotenv()
# Replace with your Speech Engine ID from step 4
SPEECH_ENGINE_ID = "seng_8k3m9xr4hjnfg983brhmhkd98n6"
openai = AsyncOpenAI(
api_key=os.getenv("OPENAI_API_KEY"),
)
elevenlabs = AsyncElevenLabs(
api_key=os.getenv("ELEVENLABS_API_KEY"),
)
def on_init(conversation_id, session):
print(f"Session started: {conversation_id}")
async def on_transcript(transcript, session):
stream = await openai.responses.create(
model="gpt-4o",
instructions="You are a helpful voice assistant. Keep responses concise and conversational.",
input=[
{"role": "assistant" if m.role == "agent" else m.role, "content": m.content}
for m in transcript
],
stream=True,
)
await session.send_response(stream)
def on_close(session):
print(f"Session ended: {session.conversation_id}")
def on_error(err, session):
print(f"Error: {err}")
async def main():
engine = await elevenlabs.speech_engine.get(SPEECH_ENGINE_ID)
await engine.serve(
port=3001,
path="/ws",
debug=True,
on_init=on_init,
on_transcript=on_transcript,
on_close=on_close,
on_error=on_error,
)
if __name__ == "__main__":
asyncio.run(main())

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.

6

Avvia il server

python server.py

Configurazione del client

1

Installa l'SDK client

npm install @elevenlabs/react
2

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.

import os
from dotenv import load_dotenv
from flask import Flask, jsonify
from elevenlabs import ElevenLabs
load_dotenv()
app = Flask(__name__)
elevenlabs = ElevenLabs(
api_key=os.getenv("ELEVENLABS_API_KEY"),
)
@app.route("/api/token")
def get_token():
# Replace with your Speech Engine ID from step 4 of the server setup
speech_engine_id = "seng_8k3m9xr4hjnfg983brhmhkd98n6"
response = elevenlabs.conversational_ai.conversations.get_webrtc_token(
agent_id=speech_engine_id,
)
return jsonify(token=response.token)
if __name__ == "__main__":
app.run(port=3002)
3

Crea l'interfaccia della conversazione

Recupera il token di conversazione dal tuo server e usalo per avviare una sessione.

App.tsx
import { useConversation } from "@elevenlabs/react";
import { useCallback } from "react";
async function getToken(): Promise<string> {
const response = await fetch("/api/token");
if (!response.ok) {
throw Error("Failed to get conversation token");
}
const data = await response.json();
return data.token;
}
export default function App() {
const conversation = useConversation({
onConnect: () => console.log("Connected"),
onDisconnect: () => console.log("Disconnected"),
onError: (error: Error) => console.error("Error:", error),
});
const startConversation = useCallback(async () => {
await navigator.mediaDevices.getUserMedia({ audio: true });
const token = await getToken();
await conversation.startSession({ conversationToken: token });
}, [conversation]);
const stopConversation = useCallback(async () => {
await conversation.endSession();
}, [conversation]);
return (
<div>
<p>Status: {conversation.status}</p>
<button onClick={startConversation} disabled={conversation.status === "connected"}>
Start conversation
</button>
<button onClick={stopConversation} disabled={conversation.status !== "connected"}>
End conversation
</button>
</div>
);
}
4

Provalo

Assicurati che siano in esecuzione tre processi:

  1. ngrok - inoltro alla porta 3001
  2. Il tuo server Speech Engine - python server.py o npx tsx server.mts
  3. Il server dei token - npx tsx token-server.mts o python 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

EventoCallback TypeScriptCallback PythonDescrizione
user_transcriptonTranscripton_transcriptParlato dell’utente trascritto. Include la cronologia completa della conversazione e un segnale di annullamento.
initonIniton_initSessione inizializzata con un ID conversazione.
closeonCloseon_closeDisconnessione pulita da ElevenLabs.
disconnectedonDisconnecton_disconnectWebSocket interrotto in modo imprevisto.
erroronErroron_errorErrore di protocollo o WebSocket.

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.

1

Per consentire all’agente di parlare per primo, dobbiamo aggiornare la risorsa Speech Engine affinché sia possibile configurarlo dal client.

engine = await elevenlabs.speech_engine.update(
speech_engine_id="seng_8k3m9xr4hjnfg983brhmhkd98n6",
overrides={
"first_message": True,
},
)
2

Quindi configuriamo il primo messaggio nell’SDK client.

conversation.startSession({
conversationToken: token,
overrides: {
agent: {
firstMessage: "Hello! How can I help you today?",
},
},
});

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:

engine = await elevenlabs.speech_engine.update(
speech_engine_id="seng_8k3m9xr4hjnfg983brhmhkd98n6",
conversation={
"max_duration_seconds": 7200,
},
)

Puoi impostarlo anche nella dashboard: apri Speech Engine, vai alla scheda Avanzate e imposta Durata massima della conversazione in Comportamento conversazionale.

Passaggi successivi