Open in
Usa ThunderPhone desde LiveKit Agents
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 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 y se facturan como cualquier otra llamada en tiempo real (precios). No hay suscripción ni interviene ningún número telefónico de ThunderPhone.
Instalar
pip install livekit-plugins-thunderphone
export THUNDERPHONE_API_KEY=sk_live_... # a secret API keyCon uv, uv add "livekit-agents[thunderphone]~=1.8" instala el mismo
plugin. Se distribuye en el repositorio de 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.
El plugin encapsula el modelo OpenAI Realtime de LiveKit, porque el
WebSocket 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.
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.
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 firstThunderPhone 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:
@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} 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_detectionenAgentSession). - 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.