---
title: "Usa ThunderPhone da Pipecat"
description: "Esegui un agente vocale ThunderPhone come servizio speech-to-speech all'interno di una pipeline Pipecat, con il tuo trasporto e la tua telefonia."
---

[Pipecat](https://github.com/pipecat-ai/pipecat) è un framework open source
per creare agenti vocali con servizi componibili. ThunderPhone si integra come
**servizio LLM speech-to-speech**: Pipecat invia l'audio del chiamante, ThunderPhone
restituisce la voce dell'agente, le trascrizioni e le chiamate di funzione, e il
trasporto di Pipecat (Daily, LiveKit, Twilio, WebRTC, un microfono locale) trasporta
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
fatturate come qualsiasi altra chiamata in tempo reale ([prezzi](/it/guides/pricing)). Non sono coinvolti né un abbonamento né un numero di telefono ThunderPhone.

## Installa

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

Il pacchetto avvolge il servizio OpenAI Realtime di Pipecat, perché il
[WebSocket Realtime](/api-reference/realtime) di ThunderPhone utilizza lo stesso protocollo. Richiede
`pipecat-ai` 1.8 o una versione successiva.

## Esegui un agente salvato

Tutto ciò che fa l’agente (prompt, voce, motore, lingue, strumenti, saluto,
controlli del silenzio) viene configurato su ThunderPhone. La pipeline sposta solo l’audio.
Crea l’agente nella dashboard, oppure chiedi a Zeus (l’agente IA 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 toccare la pipeline.

```python
from pipecat.pipeline.pipeline import Pipeline
from pipecat.pipeline.worker import PipelineParams, PipelineWorker
from pipecat.processors.aggregators.llm_context import LLMContext
from pipecat.processors.aggregators.llm_response_universal import LLMContextAggregatorPair
from pipecat_thunderphone import ThunderPhoneRealtimeLLMService

llm = ThunderPhoneRealtimeLLMService(agent_id=12)

context = LLMContext()
aggregators = LLMContextAggregatorPair(context)
pipeline = Pipeline([
    transport.input(),
    aggregators.user(),
    llm,
    aggregators.assistant(),
    transport.output(),
])
worker = PipelineWorker(pipeline, params=PipelineParams(allow_interruptions=True))
```

Un agente salvato avvia la chiamata secondo la propria pianificazione, quindi il servizio non
richiede una risposta iniziale a Pipecat. Passa `greet_on_connect=True` se
la desideri comunque.

## Configura la sessione inline

Senza `agent_id`, le istruzioni e gli strumenti provengono dal contesto Pipecat,
come avviene per OpenAI. `product` seleziona il motore e `voice` seleziona la
voce ThunderPhone.

```python
from pipecat.adapters.schemas.function_schema import FunctionSchema
from pipecat.adapters.schemas.tools_schema import ToolsSchema
from pipecat.services.llm_service import FunctionCallParams

llm = ThunderPhoneRealtimeLLMService(product="bolt", voice="olivia", language="es")

async def check_availability(params: FunctionCallParams):
    slots = await calendar.free_slots(params.arguments["date"])
    await params.result_callback({"slots": slots})

llm.register_function("check_availability", check_availability)

context = LLMContext(
    messages=[{"role": "system", "content": "You are Acme Dental's receptionist."}],
    tools=ToolsSchema(standard_tools=[
        FunctionSchema(
            name="check_availability",
            description="Free appointment slots on a date",
            properties={"date": {"type": "string"}},
            required=["date"],
        )
    ]),
)
```

Le sessioni inline sono guidate dal client: l'agente parla per primo perché Pipecat
richiede una risposta quando arriva il contesto e rimane in silenzio durante le pause,
a meno che tu non aggiunga un messaggio o richieda un'altra risposta.

## 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 `product` e `voice`. |
| `product` | Motore per sessioni inline: `bolt` (i precedenti `spark` e `storm` sono ancora supportati). |
| `voice` | Nome della voce ThunderPhone per le sessioni inline. |
| `language` | Indicazione della lingua principale per le sessioni inline, ad esempio `es`. |
| `from_number`, `to_number` | Numeri da registrare nella chiamata quando la pipeline gestisce una linea telefonica. |
| `live_transcripts` | Trasmetti in streaming frammenti della trascrizione del chiamante durante l'enunciato (fatturati separatamente). |
| `greet_on_connect` | Richiedi una prima risposta non appena la sessione è pronta. |
| `end_task_on_call_ended` | Invia `EndWorkerFrame` quando ThunderPhone termina la chiamata (attivo per impostazione predefinita). |

## Eventi

ThunderPhone aggiunge eventi della piattaforma al protocollo in tempo reale. Il servizio
li invia ai gestori:

```python
@llm.event_handler("on_call_ended")
async def on_call_ended(service, event):
    print("call ended:", event["reason"], "call id:", service.call_id)
```

`service.call_id` viene impostato quando 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.

## Limiti

- Il rilevamento dei turni è lato server ed è sempre attivo; i turni gestiti da Pipecat
  (`turn_detection=False`) non sono supportati.
- Le funzioni registrate nel servizio vengono eseguite solo per le sessioni inline. Un agente
  salvato esegue i propri strumenti su ThunderPhone.
- L'audio è PCM mono a 16 bit e 24 kHz in entrambe le direzioni.
- I fotogrammi video vengono ignorati.

<Note>
Stai invece creando con LiveKit Agents? Consulta
[Usa ThunderPhone da LiveKit Agents](/it/guides/use-with-livekit).
</Note>
