---
title: "Utiliser ThunderPhone depuis LiveKit Agents"
description: "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](https://github.com/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](/api-reference/calls) et sont facturés comme tout autre appel en temps réel ([tarification](/fr/guides/pricing)). Aucun abonnement ni numéro de téléphone ThunderPhone n'est nécessaire.

## Installer

```bash
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](https://github.com/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](https://docs.livekit.io/agents/models/realtime/thunderphone/).

Le plugin encapsule le modèle OpenAI Realtime de LiveKit, car le
[WebSocket Realtime](/api-reference/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.

```python
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.

```python
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

| 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 :

```python
@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}`](/api-reference/calls) 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.

<Note>
Vous utilisez plutôt Pipecat ? Consultez [Utiliser ThunderPhone depuis Pipecat](/fr/guides/use-with-pipecat).
</Note>
