---
title: "Usa ThunderPhone desde LiveKit Agents"
description: "Ejecuta un agente de voz de ThunderPhone como el modelo en tiempo real (de voz a voz) de una sesión de LiveKit Agents, con salas de LiveKit, SIP y telefonía a su alrededor."
---

[LiveKit Agents](https://github.com/livekit/agents) es un framework de código abierto
para agentes de voz en tiempo real sobre las salas de LiveKit. ThunderPhone se integra como el
**modelo en tiempo real**: el framework envía el audio del participante, ThunderPhone
devuelve la voz del agente, las transcripciones y las llamadas a funciones, y las salas de LiveKit,
los trunks SIP y la telefonía transportan 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 manera 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 interviene ningún número telefónico de ThunderPhone.

## Instalar

```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"` instala el mismo
plugin. Se distribuye en el repositorio de [livekit/agents](https://github.com/livekit/agents)
y se publica junto con `livekit-agents`, así que mantén ambos en la
misma versión. LiveKit lo documenta en su propia
[guía del plugin de ThunderPhone](https://docs.livekit.io/agents/models/realtime/thunderphone/).

El plugin encapsula el modelo OpenAI Realtime de LiveKit, porque el
[WebSocket Realtime](/api-reference/realtime) de ThunderPhone habla el mismo protocolo. Requiere
`livekit-agents` 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 sesión solo transmite audio.
Crea el agente en el panel o haz 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 aplicarán a la siguiente llamada sin modificar tu código de 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 guardado saluda y ejecuta sus propias herramientas en ThunderPhone; las
instrucciones y herramientas del `Agent` de LiveKit no se envían. La llamada termina cuando el
agente de ThunderPhone cuelga y la sesión se cierra con él.

## Configurar la sesión en línea

Sin `agent_id`, las instrucciones y las herramientas provienen del `Agent` de LiveKit, de la misma forma que con OpenAI. `model` selecciona el motor y `voice` selecciona la voz de 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 fija las instrucciones y herramientas cuando inicia la llamada, por lo que
`update_instructions`, `update_tools` y las transferencias de agentes que las cambian no son
compatibles durante la llamada. Las sesiones en línea son controladas por el cliente: el agente habla
cuando llamas a `generate_reply()` o cuando el participante termina un turno.

## 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 `model` y `voice`. |
| `model` | Motor para sesiones en línea: `bolt` (también se aceptan los anteriores `spark` y `storm`). |
| `voice` | Nombre de la voz de ThunderPhone para sesiones en línea. |
| `language` | Indicación del idioma principal para sesiones en línea; por ejemplo, `es`. |
| `caller_number`, `callee_number` | Números de teléfono de la llamada cuando la sala funciona con una línea telefónica. Aparecen como los números de origen y destino en el historial de llamadas. |
| `live_transcripts` | Transmite fragmentos de la transcripción de quienes llaman durante la intervención (se factura por separado). |
| `base_url` | Anulación del endpoint; el valor predeterminado es `wss://api.thunderphone.com/v1/realtime`. |

## Eventos

ThunderPhone agrega eventos de plataforma al protocolo en tiempo real. La sesión
los emite:

```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` expone `call_id` una vez que 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. Cualquier otro evento `call.*` (transferencia,
teclado, voz ignorada) llega como `thunderphone_call_event`.

## Límites

- La detección de turnos se realiza en el servidor y siempre está activada; se ignora
  la detección de turnos del framework (`turn_detection` en `AgentSession`).
- Las instrucciones y las herramientas no pueden cambiar una vez que inicia la llamada.
- El audio es PCM mono de 16 bits a 24 kHz en ambas direcciones.
- Los fotogramas de video se ignoran.

<Note>
¿Prefieres usar Pipecat? Consulta [Usa ThunderPhone desde Pipecat](/es/guides/use-with-pipecat).
</Note>
