---
title: "Usa ThunderPhone desde Pipecat"
description: "Ejecuta un agente de voz de ThunderPhone como el servicio de voz a voz dentro de una canalización de Pipecat, con tu propio transporte y telefonía."
---

[Pipecat](https://github.com/pipecat-ai/pipecat) es un framework de código abierto
para crear agentes de voz a partir de servicios componibles. ThunderPhone se integra como
un **servicio LLM de voz a voz**: Pipecat envía el audio de quien llama, ThunderPhone
devuelve la voz del agente, las transcripciones y las llamadas a funciones, y el
transporte de Pipecat (Daily, LiveKit, Twilio, WebRTC, un micrófono local) lleva el
audio. El reconocimiento de voz, el modelo de lenguaje, la voz, los turnos de conversación, 62
idiomas y las herramientas se ejecutan en ThunderPhone.

Las llamadas realizadas de esta forma aparecen en el [historial de llamadas](/api-reference/calls) y se
facturan como cualquier otra llamada en tiempo real ([precios](/es/guides/pricing)). No
hay suscripción ni número telefónico de ThunderPhone involucrado.

## Instalar

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

El paquete encapsula el servicio OpenAI Realtime de Pipecat, porque el
[WebSocket Realtime](/api-reference/realtime) de ThunderPhone utiliza el mismo protocolo. Requiere
`pipecat-ai` 1.8 o una versión posterior.

## Ejecutar un agente guardado

Todo lo que hace el agente (prompt, voz, motor, idiomas, herramientas, saludo,
verificaciones de silencio) se configura en ThunderPhone. La plataforma solo transmite audio.
Crea el agente en el panel o deja que Zeus (el agente de IA que crea, prueba y ajusta agentes de ThunderPhone) lo configure; luego, pasa su ID aquí. Los cambios que implementes en ThunderPhone se aplican a la siguiente llamada sin modificar tu plataforma.

```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 guardado inicia la llamada según su propia programación, por lo que el servicio no
solicita una respuesta inicial a Pipecat. Pasa `greet_on_connect=True` si aun así
quieres una.

## Configurar la sesión en línea

Sin `agent_id`, las instrucciones y las herramientas provienen del contexto de Pipecat,
igual que con OpenAI. `product` selecciona el motor y `voice` selecciona la voz de
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"],
        )
    ]),
)
```

Las sesiones en línea son controladas por el cliente: el agente habla primero porque Pipecat
solicita una respuesta cuando llega el contexto y permanece en silencio durante los períodos
de silencio, salvo que agregues un mensaje o solicites otra respuesta.

## Opciones

| Argumento | Significado |
|---|---|
| `api_key` | Clave secreta (`sk_live_...`). El valor predeterminado es `THUNDERPHONE_API_KEY`. |
| `agent_id` | Ejecuta un agente guardado. Es mutuamente excluyente con `product` y `voice`. |
| `product` | Motor para sesiones en línea: `bolt` (también se aceptan los anteriores `spark` y `storm`). |
| `voice` | Nombre de voz de ThunderPhone para sesiones en línea. |
| `language` | Indicación del idioma principal para sesiones en línea, por ejemplo, `es`. |
| `from_number`, `to_number` | Números que se registrarán en la llamada cuando la plataforma esté al frente de una línea telefónica. |
| `live_transcripts` | Transmite fragmentos de la transcripción de quien llama durante una intervención (se factura aparte). |
| `greet_on_connect` | Solicita una primera respuesta en cuanto la sesión esté lista. |
| `end_task_on_call_ended` | Envía `EndWorkerFrame` cuando ThunderPhone finaliza la llamada (activado de forma predeterminada). |

## Eventos

ThunderPhone agrega eventos de plataforma al protocolo en tiempo real. El servicio
los entrega a los controladores:

```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` se establece cuando la sesión está activa. Úsalo con
[`GET /v1/calls/{call_id}`](/api-reference/calls) para obtener la grabación,
la transcripción y la calificación después de la llamada.

## Límites

- La detección de turnos se realiza del lado del servidor y siempre está activada; los turnos controlados por Pipecat
  (`turn_detection=False`) no son compatibles.
- Las funciones registradas en el servicio se ejecutan solo para sesiones en línea. Un agente guardado
  ejecuta sus propias herramientas en ThunderPhone.
- El audio es PCM mono de 16 bits a 24 kHz en ambas direcciones.
- Los fotogramas de video se ignoran.

<Note>
¿Estás desarrollando con LiveKit Agents? Consulta
[Usa ThunderPhone desde LiveKit Agents](/es/guides/use-with-livekit).
</Note>
