Open in
Utiliser ThunderPhone depuis LiveKit Agents
Exécutez un agent vocal ThunderPhone comme modèle temps réel (de parole à parole) d’une session LiveKit Agents, avec des salles LiveKit, le protocole SIP et la téléphonie autour.
LiveKit Agents est un framework open source pour les agents vocaux en temps réel reposant sur des salles LiveKit. ThunderPhone s’intègre comme le modèle temps réel : le framework envoie l’audio du participant, ThunderPhone renvoie la voix de l’agent, les transcriptions et les appels de fonction, et les salles LiveKit, les trunks SIP et la téléphonie transportent l’audio. La reconnaissance vocale, le modèle de langage, la voix, la prise de tour de parole, 62 langues et les outils s’exécutent tous sur ThunderPhone.
Les appels effectués de cette manière apparaissent dans l'historique des appels et sont facturés comme tout autre appel en temps réel (tarification). Aucun abonnement ni numéro de téléphone ThunderPhone n'est nécessaire.
Installer
pip install livekit-plugins-thunderphone
export THUNDERPHONE_API_KEY=sk_live_... # a secret API keyAvec uv, uv add "livekit-agents[thunderphone]~=1.8" installe le même
plugin. Il se trouve dans le dépôt livekit/agents
et est publié avec livekit-agents lui-même ; conservez donc les deux à la
même version. LiveKit le documente dans son propre
guide du plugin ThunderPhone.
Le plugin encapsule le modèle OpenAI Realtime de LiveKit, car le
WebSocket Realtime de ThunderPhone utilise le même protocole. Il
nécessite livekit-agents 1.8 ou une version plus récente.
Exécuter un agent enregistré
Tout ce que fait l’agent (prompt, voix, moteur, langues, outils, message d’accueil, vérifications en cas de silence) est configuré sur ThunderPhone. La session ne transporte que l’audio. Créez l’agent dans le dashboard, ou demandez à Zeus (l’agent IA qui crée, teste et optimise les agents ThunderPhone) de le configurer, puis transmettez son ID ici. Les modifications que vous déployez sur ThunderPhone s’appliquent au prochain appel sans modifier votre code LiveKit.
from livekit.agents import Agent, AgentSession, JobContext, WorkerOptions, cli
from livekit.plugins import thunderphone
async def entrypoint(ctx: JobContext):
session = AgentSession(llm=thunderphone.RealtimeModel(agent_id=12))
await session.start(agent=Agent(instructions=""), room=ctx.room)
if __name__ == "__main__":
cli.run_app(WorkerOptions(entrypoint_fnc=entrypoint))Un agent enregistré accueille les appelants et exécute ses propres outils sur ThunderPhone ; les
instructions et outils de l'Agent LiveKit ne sont pas envoyés. L'appel se termine lorsque
l'agent ThunderPhone raccroche, et la session se ferme avec lui.
Configurer la session en ligne
Sans agent_id, les instructions et les outils proviennent de l’Agent LiveKit, comme pour OpenAI. model sélectionne le moteur et voice sélectionne la voix ThunderPhone.
from livekit.agents import Agent, AgentSession, RunContext, function_tool
from livekit.plugins import thunderphone
class Receptionist(Agent):
def __init__(self):
super().__init__(instructions="You are Acme Dental's receptionist. Be brief.")
@function_tool
async def check_availability(self, context: RunContext, date: str) -> dict:
"""Free appointment slots on a date."""
return {"slots": await calendar.free_slots(date)}
async def entrypoint(ctx: JobContext):
session = AgentSession(
llm=thunderphone.RealtimeModel(model="bolt", voice="olivia", language="es"),
)
await session.start(agent=Receptionist(), room=ctx.room)
await session.generate_reply() # the agent speaks firstThunderPhone fige les instructions et les outils au démarrage de l'appel ; ainsi,
update_instructions, update_tools et les transferts d'agent qui les modifient ne sont
pas pris en charge pendant l'appel. Les sessions en ligne sont pilotées par le client : l'agent parle
lorsque vous appelez generate_reply() ou lorsque le participant termine un tour de parole.
Options
| Argument | Signification |
|---|---|
api_key | Clé secrète (sk_live_...). Par défaut : THUNDERPHONE_API_KEY. |
agent_id | Exécute un agent enregistré. Mutuellement exclusif avec model et voice. |
model | Moteur pour les sessions en ligne : bolt (les anciens spark et storm sont toujours acceptés). |
voice | Nom de voix ThunderPhone pour les sessions en ligne. |
language | Indication de langue principale pour les sessions en ligne, par exemple es. |
caller_number, callee_number | Numéros de téléphone de l'appel lorsque la salle est associée à une ligne téléphonique. Ils apparaissent comme numéros source et destination dans l'historique des appels. |
live_transcripts | Diffuse des fragments de transcription de l'appelant en cours d'énoncé (facturé en supplément). |
base_url | Remplacement de point de terminaison, par défaut wss://api.thunderphone.com/v1/realtime. |
Événements
ThunderPhone ajoute des événements de plateforme au protocole temps réel. La session les émet :
@session.llm.session.on("thunderphone_call_ended") # or on the RealtimeSession you hold
def on_call_ended(event):
print("call ended:", event["reason"])La RealtimeSession expose call_id une fois la session active. Utilisez-le avec
GET /v1/calls/{call_id} pour récupérer l’enregistrement,
la transcription et l’évaluation après l’appel. Tout autre événement call.* (transfert,
clavier, parole ignorée) arrive sous la forme de thunderphone_call_event.
Limites
- La détection des tours de parole est côté serveur et toujours active ; la détection des tours de parole côté framework
(
turn_detectionsur l’AgentSession) est ignorée. - Les instructions et les outils ne peuvent pas être modifiés une fois l’appel commencé.
- L’audio est au format PCM mono 16 bits à 24 kHz dans les deux sens.
- Les images vidéo sont ignorées.