---
title: "Usa ThunderPhone da LiveKit Agents"
description: "Esegui un agente vocale ThunderPhone come modello in tempo reale (da voce a voce) di una sessione LiveKit Agents, con stanze LiveKit, SIP e telefonia attorno ad esso."
---

[LiveKit Agents](https://github.com/livekit/agents) è un framework open source
per agenti vocali in tempo reale basato sulle stanze LiveKit. ThunderPhone si integra come
**modello in tempo reale**: il framework invia l'audio del partecipante, ThunderPhone
restituisce la voce dell'agente, le trascrizioni e le chiamate di funzione, mentre le stanze,
i trunk SIP e la telefonia di LiveKit trasportano l'audio. Il riconoscimento vocale, il modello
linguistico, la voce, la gestione dei turni, 62 lingue e gli strumenti vengono tutti eseguiti su ThunderPhone.

Le chiamate effettuate in questo modo vengono visualizzate nella [cronologia delle chiamate](/api-reference/calls) e sono fatturate come qualsiasi altra chiamata in tempo reale ([prezzi](/it/guides/pricing)). Non sono previsti abbonamenti né è coinvolto alcun numero di telefono ThunderPhone.

## Installa

```bash
pip install livekit-plugins-thunderphone
export THUNDERPHONE_API_KEY=sk_live_...   # a secret API key
```

Con uv, `uv add "livekit-agents[thunderphone]~=1.8"` installa lo stesso
plugin. È incluso nel repository [livekit/agents](https://github.com/livekit/agents)
e viene rilasciato insieme a `livekit-agents`, quindi mantieni entrambi alla
stessa versione. LiveKit lo documenta nella propria
[guida al plugin ThunderPhone](https://docs.livekit.io/agents/models/realtime/thunderphone/).

Il plugin include il modello OpenAI Realtime di LiveKit, poiché il
[WebSocket Realtime](/api-reference/realtime) di ThunderPhone utilizza lo stesso protocollo. Richiede
`livekit-agents` 1.8 o una versione successiva.

## Esegui un agente salvato

Tutto ciò che fa l'agente (prompt, voce, motore, lingue, strumenti, saluto,
verifiche del silenzio) è configurato su ThunderPhone. La sessione trasferisce solo l'audio.
Crea l'agente nel dashboard, oppure chiedi a Zeus (l'agente AI che crea, testa
e ottimizza gli agenti ThunderPhone) di configurarlo, quindi passa qui il suo ID. Le modifiche che
distribuisci su ThunderPhone si applicano alla chiamata successiva senza modificare il tuo codice 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 agente salvato saluta ed esegue i propri strumenti su ThunderPhone; le istruzioni e gli strumenti dell'`Agent`
di LiveKit non vengono inviati. La chiamata termina quando l'agente ThunderPhone riaggancia e la sessione si chiude con esso.

## Configura la sessione inline

Senza `agent_id`, le istruzioni e gli strumenti provengono dall'`Agent` di LiveKit, nello stesso modo in cui avviene per OpenAI. `model` seleziona il motore e `voice` seleziona la voce 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 blocca istruzioni e strumenti all'avvio della chiamata, quindi
`update_instructions`, `update_tools` e i passaggi ad altri agenti che li modificano non sono
supportati durante la chiamata. Le sessioni inline sono controllate dal client: l'agente parla
quando chiami `generate_reply()` o quando il partecipante conclude un turno.

## Opzioni

| Argomento | Significato |
|---|---|
| `api_key` | Chiave segreta (`sk_live_...`). Il valore predefinito è `THUNDERPHONE_API_KEY`. |
| `agent_id` | Esegui un agente salvato. Si esclude a vicenda con `model` e `voice`. |
| `model` | Motore per le sessioni inline: `bolt` (sono ancora accettati i meno recenti `spark` e `storm`). |
| `voice` | Nome della voce ThunderPhone per le sessioni inline. |
| `language` | Suggerimento della lingua principale per le sessioni inline, ad esempio `es`. |
| `caller_number`, `callee_number` | Numeri di telefono della chiamata quando la stanza gestisce una linea telefonica. Vengono visualizzati come numeri di provenienza e destinazione nella cronologia chiamate. |
| `live_transcripts` | Trasmetti frammenti della trascrizione del chiamante durante l'enunciato (fatturazione aggiuntiva). |
| `base_url` | Override dell'endpoint, valore predefinito `wss://api.thunderphone.com/v1/realtime`. |

## Eventi

ThunderPhone aggiunge eventi della piattaforma al protocollo realtime. La sessione
li emette:

```python
@session.llm.session.on("thunderphone_call_ended")  # or on the RealtimeSession you hold
def on_call_ended(event):
    print("call ended:", event["reason"])
```

`RealtimeSession` espone `call_id` una volta che la sessione è attiva. Usalo con
[`GET /v1/calls/{call_id}`](/api-reference/calls) per recuperare la registrazione,
la trascrizione e la valutazione dopo la chiamata. Ogni altro evento `call.*` (trasferimento,
tastierino, parlato ignorato) arriva come `thunderphone_call_event`.

## Limiti

- Il rilevamento dei turni è lato server ed è sempre attivo; il rilevamento dei turni lato framework
  (`turn_detection` su `AgentSession`) viene ignorato.
- Le istruzioni e gli strumenti non possono cambiare dopo l'inizio della chiamata.
- L'audio è PCM mono a 16 bit e 24 kHz in entrambe le direzioni.
- I fotogrammi video vengono ignorati.

<Note>
Stai invece sviluppando con Pipecat? Consulta [Usa ThunderPhone da Pipecat](/it/guides/use-with-pipecat).
</Note>
