ThunderPhone v3 est disponible.En libre-service, à partir de 2 ¢/min.Découvrir l’annonce

Connect tools & data

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 key

Avec 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 first

ThunderPhone 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

ArgumentSignification
api_keyClé secrète (sk_live_...). Par défaut : THUNDERPHONE_API_KEY.
agent_idExécute un agent enregistré. Mutuellement exclusif avec model et voice.
modelMoteur pour les sessions en ligne : bolt (les anciens spark et storm sont toujours acceptés).
voiceNom de voix ThunderPhone pour les sessions en ligne.
languageIndication de langue principale pour les sessions en ligne, par exemple es.
caller_number, callee_numberNumé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_transcriptsDiffuse des fragments de transcription de l'appelant en cours d'énoncé (facturé en supplément).
base_urlRemplacement 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_detection sur 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.