Vai alla navigazione
RisorseSDK

SDK Python

SDK ElevenAgents: distribuisci in pochi minuti agenti vocali interattivi e personalizzati.

Consulta anche la panoramica di ElevenAgents

Installazione

Installa il pacchetto Python elevenlabs nel tuo progetto:

pip install elevenlabs
# or
poetry add elevenlabs

Se vuoi usare l’implementazione predefinita dell’input/output audio, ti servirà anche l’extra pyaudio:

pip install "elevenlabs[pyaudio]"
# or
poetry add "elevenlabs[pyaudio]"

L’installazione del pacchetto pyaudio potrebbe richiedere dipendenze di sistema aggiuntive.

Per ulteriori informazioni, consulta il README del pacchetto PyAudio.

Sui sistemi basati su Debian puoi installare le dipendenze con:

sudo apt-get update
sudo apt-get install libportaudio2 libportaudiocpp0 portaudio19-dev libasound-dev libsndfile1-dev -y

Utilizzo

In questo esempio creeremo un semplice script che esegue una conversazione con l’agente ElevenLabs Agents.

Per prima cosa, importa le dipendenze necessarie:

import os
import signal
from elevenlabs.client import ElevenLabs
from elevenlabs.conversational_ai.conversation import Conversation
from elevenlabs.conversational_ai.default_audio_interface import DefaultAudioInterface

Poi carica l’ID dell’agente e la chiave API dalle variabili di ambiente:

agent_id = os.getenv("AGENT_ID")
api_key = os.getenv("ELEVENLABS_API_KEY")

La chiave API è richiesta solo per gli agenti non pubblici con autenticazione abilitata. Non devi impostarla per gli agenti pubblici e il codice funzionerà correttamente anche senza.

Quindi crea l’istanza del client ElevenLabs:

elevenlabs = ElevenLabs(api_key=api_key)

Ora inizializziamo l’istanza Conversation:

conversation = Conversation(
    # API client and agent ID.
    elevenlabs,
    agent_id,
    # Assume auth is required when API_KEY is set.
    requires_auth=bool(api_key),
    # Use the default audio interface.
    audio_interface=DefaultAudioInterface(),
    # Simple callbacks that print the conversation to the console.
    callback_agent_response=lambda response: print(f"Agent: {response}"),
    callback_agent_response_correction=lambda original, corrected: print(f"Agent: {original} -> {corrected}"),
    callback_user_transcript=lambda transcript: print(f"User: {transcript}"),
    # Uncomment if you want to see latency measurements.
    # callback_latency_measurement=lambda latency: print(f"Latency: {latency}ms"),
    # Uncomment if you want to receive audio alignment data with character-level timing.
    # callback_audio_alignment=lambda alignment: print(f"Alignment: {alignment.chars}"),
)

Stiamo usando DefaultAudioInterface, che utilizza i dispositivi di input/output audio di sistema predefiniti per la conversazione. Puoi anche implementare la tua interfaccia audio creando una sottoclasse di elevenlabs.conversational_ai.conversation.AudioInterface.

Ora possiamo avviare la conversazione. Facoltativamente, ti consigliamo di passare i tuoi ID utente finali per associare le conversazioni ai tuoi utenti.

conversation.start_session(
    user_id=user_id # optional field
)

Per un arresto pulito quando l’utente preme Ctrl+C, possiamo aggiungere un signal handler che chiamerà end_session():

signal.signal(signal.SIGINT, lambda sig, frame: conversation.end_session())

Infine, aspettiamo che la conversazione termini e stampiamo l’ID della conversazione, che può essere usato per rivedere la cronologia della conversazione ed eseguire il debug:

conversation_id = conversation.wait_for_session_end()
print(f"Conversation ID: {conversation_id}")

Non resta che eseguire lo script e iniziare a parlare con l’agente:

# For public agents:
AGENT_ID=youragentid python demo.py
# For private agents:
AGENT_ID=youragentid ELEVENLABS_API_KEY=yourapikey python demo.py