Agente telefónico de LiveKit Voice AI: SIP, interrupciones, derivación y registros

Los agentes LiveKit pueden poner reconocimiento de voz, LLM, síntesis de voz e invocación de herramientas en una sesión en tiempo real y luego conectarse a la red telefónica ordinaria a través de SIP. El voice ai agents de Google Trends ha aumentado un 350% en Estados Unidos. Sin embargo, la falla del robot telefónico para conectarse generalmente no se debe a que el modelo no sea lo suficientemente inteligente, sino a que el enrutamiento SIP, la interrupción, la transferencia manual y los enlaces de registro no se verifican juntos. Este artículo utiliza llamadas entrantes de servicio al cliente como ejemplo. Primero se rutea al agente que está en la sala, luego se contesta el número de teléfono y finalmente se maneja la ruta de falla que debe tener la llamada de producción.

¿Por qué componentes pasa una llamada telefónica?

La persona que llama marca el número de teléfono. El operador telefónico o los números de teléfono de LiveKit enrutan la llamada a la troncal SIP. La troncal entrante determina qué números y fuentes pueden entrar. La regla de envío coloca al participante SIP en la sala LiveKit. El trabajador agente acepta el trabajo y crea AgentSession. STT convierte el audio en texto, LLM decide la respuesta o llama a la herramienta y TTS envía la respuesta al teléfono. Al transferir a un humano, el sistema crea un nuevo participante SIP o transfiere la llamada a un número externo. Cada capa tiene registros independientes y estados de falla.

Primero verifique el Agente

en la sala del navegador Las redes telefónicas agregan variables de configuración de operador, número y SIP. Primero verifique el agente de voz usando LiveKit Playground o una sala de audio local. Debería poder completarse:

• Escuche la voz del usuario.
• Responda dentro de un plazo razonable.
• Detenga el TTS actual cuando el usuario interrumpa.
• Llame a una herramienta libre de efectos secundarios.
• Los recursos se liberan cuando finaliza la sesión.

Si este paso falla, no verifiques el número de teléfono primero.

Crear proyecto y entorno local

Prepare un proyecto LiveKit Cloud o autohospede LiveKit Server según la documentación oficial. Entorno local de Python:

1
2
3

python3 -m venv .venv-livekit
source .venv-livekit/bin/activate
python -m pip install --upgrade pip

Windows PowerShell:

1
2
3

python -m venv .venv-livekit
.\.venv-livekit\Scripts\Activate.ps1
python -m pip install --upgrade pip

Instale agentes y complementos necesarios según el inicio rápido actual, sin fijar versiones desactualizadas de blogs antiguos.

Las variables de entorno solo se colocan en el lado del servidor

1
2
3

LIVEKIT_URL=wss://example.livekit.cloud
LIVEKIT_API_KEY=replace-me
LIVEKIT_API_SECRET=replace-me

Los proveedores de STT, LLM y TTS también tendrán sus propias claves. Agregue .env.local a la lista de ignorados:

1

git check-ignore .env.local

Los secretos de API no se pueden ingresar en navegadores ni dispositivos móviles. El cliente solo obtiene el token de sala a corto plazo emitido por el servidor.

AgentSession es el coordinador del canal de voz

AgentSession es responsable de la entrada del usuario, modelos, herramientas, resultados y eventos. El nombre y los parámetros específicos del complemento cambian con la versión. La estructura se muestra a continuación en lugar de comprometerse con un proveedor fijo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

from livekit.agents import Agent, AgentSession

class SupportAgent(Agent):
    def __init__(self):
        super().__init__(
            instructions=(
                "You are a concise phone support agent. "
                "Confirm identity before reading private account data. "
                "Offer a human handoff when the caller asks."
            )
        )

async def entrypoint(ctx):
    session = AgentSession(
        stt=build_stt(),
        llm=build_llm(),
        tts=build_tts(),
    )
    await session.start(
        room=ctx.room,
        agent=SupportAgent(),
    )

Funciones como build_stt() deben reemplazarse con instancias de complementos compatibles oficialmente.

Las palabras de las indicaciones del teléfono deben adaptarse a escenarios sin pantalla

Los enlaces, tablas y códigos son invisibles para los usuarios. Mantenga sus respuestas breves y solo haga una pregunta a la vez. Es necesario repetir los números, fechas y correos electrónicos para confirmarlos. No lea diez elementos del menú en voz alta a la vez. Debe haber instrucciones claras para pasar al manual, repetir, volver al paso anterior y finalizar la llamada. La autenticación se realiza antes de que se realicen operaciones de la cuenta, en lugar de una confianza automática basada en los números de las personas que llaman.

Asignar permisos de lectura y escritura a las herramientas

Consultar el horario comercial es una herramienta de solo lectura. Las órdenes de consulta podrán leer datos personales. La cancelación de pedidos, reembolsos y cambios de dirección son operaciones por escrito. La herramienta de escritura requiere una segunda confirmación y repite los parámetros finales al usuario.

1
2
3
4

async def cancel_order(order_id: str, confirmed: bool) -> str:
    if not confirmed:
        return "confirmation_required"
    return await order_service.cancel(order_id)

No permita que LLM forje confirmed=True por sí solo basándose en el lenguaje natural. El estado de confirmación debe gestionarse mediante la lógica de la sesión.

La capacidad de interrumpir determina la experiencia del teléfono

Cuando el usuario comienza a hablar, el Agente debe detener o atenuar el TTS actual. La hipersensibilidad interpretará la tos, la televisión de fondo y los ecos como interrupciones. La lentitud excesiva impide que los usuarios corrijan errores. Registro durante la depuración:

• Hora de inicio de la voz del usuario.
• Tiempo de detección del VAD.
• Hora de parada TTS.
• Tiempo del resultado final STT.
• Nueva respuesta primera vez en audio.

Sólo una línea de tiempo de un extremo a otro puede determinar de dónde proviene el retraso.

Detección de giro y ruido del teléfono

El ancho de banda, la compresión y el ruido del audio del teléfono son diferentes a los de los micrófonos web. Una breve pausa no significa necesariamente que el usuario haya terminado de hablar. Puede haber pausas naturales entre la dirección, el número de pedido y el nombre. Utilice la detección de giro y la configuración de VAD que proporciona LiveKit actualmente para realizar pruebas a partir de grabaciones telefónicas reales. No utilice simplemente el micrófono de su navegador para ajustar parámetros en una oficina tranquila.

Comprar o acceder al número de teléfono

Puede utilizar números de teléfono de LiveKit o configurar un proveedor SIP externo compatible. Confirme el país, la región, las capacidades de mensajería de texto, las restricciones de llamadas de emergencia y los requisitos de identidad al seleccionar un número. La compra exitosa del número no significa que se haya completado la ruta entrante. También se necesitan reglas de troncales y de despacho para enviar llamadas a la sala. La consola del operador y la consola LiveKit mantienen cada una una identificación verificable.

La troncal entrante limita los números permitidos

La troncal entrante define qué números de teléfono y fuentes SIP se reciben. Utilice diferentes números o troncales para producción y pruebas. No acepte todas las fuentes SIP y luego confíe en el rechazo del Agente. Si el operador admite autenticación de credenciales o IP, habilítela según las recomendaciones oficiales. Después de modificar la troncal, realice una llamada de prueba para confirmar que se aplica la nueva configuración en lugar del caché de reglas anterior.

La regla de despacho determina el nombre de la sala y el agente

Genera una sala única para cada llamada para evitar que dos llamadas desconocidas entren en la misma conversación. El nombre de la habitación puede contener el ID de llamada interna, pero no el número de teléfono completo. Sólo los campos necesarios para el enrutamiento se colocan en los metadatos. El trabajador agente selecciona el agente de servicio al cliente, ventas o reservas en función de los metadatos del trabajo. Cuando no hay ningún Agente coincidente, debe haber un mensaje de error audible o una ruta de transferencia, y no puede permanecer en silencio.

Aceptación mínima de llamadas entrantes

Marque desde un teléfono real que no esté conectado al Wi-Fi de la empresa. Registro:

1
2
3
4
5

carrier_call_id
sip_participant_id
room_name
agent_job_id
session_id

Debe haber al menos un saludo o un mensaje de espera dentro de los 3 a 5 segundos posteriores a la confirmación de una llamada entrante. Si la llamada se conecta pero no hay sonido, verifique el seguimiento del participante SIP, si el Agente se ha unido y si se ha liberado el TTS.

403 y 404 No se limite a mirar el registro del agente

La capa SIP 403 puede provenir de autenticación, restricciones de fuente, número no verificado o política del operador. 404 Puede ser que el número de ruta o troncal no coincida. La sala LiveKit ha sido creada pero no tiene un Agente. Centrarse en el despacho y la disponibilidad de los trabajadores. El Agente se ha iniciado pero no hay ningún participante que llame. Centrarse en el acceso SIP. Guarde el ID de llamada tanto en el lado del operador como en el de LiveKit.

DTMF como entrada alternativa para reconocimiento de voz

Los teclados telefónicos son adecuados para confirmar menús, opciones numéricas y operaciones sensibles. Por ejemplo, presione 1 para cambiar a manual, presione 2 para repetir y presione 9 para finalizar. No permita que DTMF y los comandos de voz activen la misma acción dos veces. Asigne un ID de evento a cada entrada y utilice una máquina de estado para deduplicarla. Los datos confidenciales, como tarjetas bancarias y contraseñas, no deben registrarse en registros ordinarios en secuencias completas de pulsaciones de teclas.

La transferencia manual no significa pedirle al Agente que diga “Transferido”

La verdadera transferencia incluye al menos colas de destino, resúmenes de contexto y enrutamiento de llamadas. La transferencia del agente LiveKit es adecuada para cambiar roles entre diferentes agentes de IA. El cambio al servicio al cliente en vivo generalmente requiere un nuevo participante saliente SIP o la integración de un centro de llamadas externo. Reproduzca un mensaje durante la cola y permita que el usuario cancele. Si la transferencia falla, regrese con el Agente original o devuélvale la llamada en lugar de colgar directamente.

El contexto pasado al humano debe minimizarse

Puede contener:

• Identificación de cliente verificada.
• Objetivo actual del usuario.
• Consulta de solo lectura ejecutada.
• Operaciones inacabadas.
• Si el usuario está de acuerdo con la grabación.

No le brinde al servicio de atención al cliente todo el proceso de pensamiento del modelo, su historial irrelevante o todo el texto de su llamada. El resumen debe marcar lo que expresa explícitamente el usuario y lo que infiere el agente.

Las llamadas salientes requieren una autorización más estricta

El SIP saliente se puede utilizar para devoluciones de llamadas, recordatorios y encuestas. Pero también es propenso a provocar llamadas no deseadas, zonas horarias y problemas de consentimiento. La lista de números debe proceder de un sistema empresarial con base legal. Verifique la hora local, el estado de cancelación de suscripción y el límite de frecuencia antes de llamar. Está prohibido permitir que LLM elija cualquier número para marcar. Cada llamada saliente requiere un ID de tarea empresarial explícito.

Gestión separada de grabación y transcripción de llamadas

Las grabaciones, las transcripciones en vivo, los resúmenes y los campos comerciales son objetos de datos diferentes. El consentimiento del usuario para la grabación no significa necesariamente que esté de acuerdo con la conservación a largo plazo de la transcripción completa. Establezca los permisos de acceso y los períodos de retención por separado. La URL de grabación utiliza una firma a corto plazo y no se incluye en los registros de aplicaciones normales. Las solicitudes de eliminación anulan las políticas de almacenamiento, indexación, resumen y copia de seguridad de objetos.

El registro de eventos no registra la clave original

Registro recomendado:

1
2
3
4
5
6
7
8

{
  "session_id": "sess_example",
  "call_id": "call_example",
  "event": "human_handoff_requested",
  "timestamp": "2026-07-28T12:00:00Z",
  "target_queue": "support_cn",
  "result": "queued"
}

Los números de teléfono solo conservan máscaras o identificaciones internas. El texto STT no ingresa al registro de depuración de la infraestructura de forma predeterminada.

El presupuesto de retraso debe medirse en segmentos

El retraso total de respuesta se puede desglosar en:

1

VAD + final STT + LLM first token + TTS first audio + network

Registre P50, P95 y la tasa de falla por separado. El promedio enmascarará pausas ocasionales de diez segundos. Reproduzca un breve mensaje de espera durante la invocación de la herramienta LLM, pero no lo repita cada segundo. El almacenamiento en caché de saludos anclados puede reducir la latencia del primer TTS.

Cómo localizar eco y voz dual

Primero, asegúrese de que la persona que llama solo se suscriba a una pista de audio del Agente. Compruebe si el Agente se une a la misma sala repetidamente. Si la grabación del lado del operador es normal pero el móvil escucha eco, puede ser el eco acústico del terminal. Si la grabación de la sala tiene doble sonido, verifique la publicación de la pista y TTS para envío repetido. No enmascare pistas repetitivas aumentando el umbral VAD.

Mantener una experiencia recuperable cuando un Trabajador se desconecta

Es posible que las llamadas SIP aún se conecten después de que un trabajador del Agente falle. Establezca tiempos de espera de trabajo, controles de salud de los trabajadores y rutas de respaldo. Un breve tiempo de recuperación permite a los nuevos trabajadores leer el estado de la sesión. Si la recuperación no es posible, se explicará el error de reproducción y se proporcionará un número de manual. No haga que los usuarios esperen indefinidamente en líneas silenciosas.

Para las pruebas de estrés, no puede marcar manualmente

desde el mismo número de teléfono móvil. Genere concurrencia utilizando herramientas de prueba oficiales o cuentas de prueba SIP controladas. Aumente gradualmente las cuotas de simultaneidad, sala de observación, trabajadores, STT, LLM, TTS y operadores. Los límites pueden variar según el proveedor. El número de la prueba de estrés está aislado del número de producción. Notifique al operador con anticipación para evitar que se considere una llamada anormal.

Los cargos se calculan en función de la cadena de llamadas completa

El costo incluye número de teléfono, minutos SIP, LiveKit, STT, LLM, TTS, almacenamiento de grabaciones y mano de obra de transferencia. Las llamadas a herramientas también pueden generar costos de API comerciales. Registre los segundos reales y el uso del proveedor de cada llamada. También se facturan las llamadas fallidas y en espera. Calcular los costos unitarios a partir de llamadas resueltas exitosamente tiene más sentido que simplemente mirar el precio por minuto.

Un conjunto de lista de verificación de simulacro de fallas

Detenga al agente trabajador y confirme la degradación audible. Invalide la clave STT y confirme que no responderá repetidamente las preguntas incorrectas al usuario. Deje que LLM se agote y confirme que se puede transferir al trabajo manual. Deje que TTS falle y confirme que el sistema no permanecerá en silencio. Haga que la cola manual no esté disponible y proporcione devoluciones de llamadas o mensajes para confirmación. Presione DTMF dos veces para confirmar que la operación de escritura no se repetirá.

Determinación en línea

• Los agentes en la sala del navegador pasaron de forma independiente.
• Se puede rastrear el troncal SIP y el ID de envío.
• Utilice una sala separada para cada llamada.
• La interrupción del usuario puede detener TTS.
• Separación de permisos para herramientas de lectura y escritura.
• Vaya al manual para completar el enrutamiento telefónico real.
• Las grabaciones, transcripciones y resúmenes se gestionan por separado.
• Se pueden asociar operadores e identificadores de llamadas de LiveKit.
• Las desconexiones, los tiempos de espera y los fallos en las cuotas provocan degradación de la voz.
• Hay controles de consentimiento, zona horaria y frecuencia para las llamadas salientes.

La calidad de la IA de voz del teléfono depende de la cadena de llamadas completa, no del rendimiento de una sola ronda de respuestas. Primero borre la sala del navegador y luego agregue SIP, DTMF, transferencia manual y grabación capa por capa, para que cada falla pueda tener una posición de responsabilidad clara.

Entrada de documentación de LiveKit

• Documentación de telefonía LiveKit
• Sesión del agente LiveKit
• Agentes de LiveKit y transferencia