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 les 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, trunks SIP et la téléphonie de LiveKit transportent l'audio. La reconnaissance vocale, le modèle de langage, la voix, la gestion des tours de parole, 47 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 au tarif à la minute de votre produit comme tout autre appel en temps réel. 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

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 de silence) est configuré sur ThunderPhone. La session ne transporte que l'audio.

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, de la même manière que pour OpenAI. product 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(product="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#

É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.