Agentes

Un agente es la unidad central en VOCALS. Define cómo se comporta un asistente de voz con IA en una llamada -- qué dice, cómo suena y qué proveedores lo alimentan. Cada número de teléfono se asigna a un agente.

Crear un Agente

1. Navega a Agentes en el panel de control.
2. Haz clic en Crear Agente.
3. Dale al agente un nombre descriptivo (ej., "Ventas Entrantes - Español" o "Soporte Nivel 1").
4. Configura los ajustes descritos a continuación.
5. Haz clic en Guardar.

Ajustes del Agente

Prompt del Sistema

El prompt del sistema define la personalidad, instrucciones y restricciones del agente. Este es el ajuste más importante -- determina todo sobre cómo se comporta el agente en la conversación.

You are a friendly customer support agent for Acme Corp. Your name is Sarah.

Your responsibilities:
- Answer questions about our products and pricing
- Help customers troubleshoot common issues
- Escalate complex technical problems to a human agent

Rules:
- Never discuss competitor products
- Always confirm the customer's name before making account changes
- Keep responses concise -- aim for 1-2 sentences per turn

Mejores prácticas para prompts del sistema:

• Sé específico sobre la longitud de las respuestas. Las conversaciones telefónicas necesitan respuestas cortas. Instruye al agente para que responda en 1-2 frases a menos que el llamante pida más detalle.
• Define una persona. Dale al agente un nombre, tono y personalidad. Los llamantes interactúan mejor con un personaje consistente.
• Establece límites. Indica explícitamente qué debe y qué no debe discutir el agente. Lista los temas que deben escalarse a un humano.
• Incluye frases de ejemplo. Si quieres que el agente use saludos, confirmaciones o despedidas específicas, inclúyelas en el prompt.
• Maneja casos extremos. Indica al agente qué hacer cuando no sabe la respuesta, cuando el llamante está molesto o cuando la conversación se desvía del tema.
• Mantenlo estructurado. Usa secciones con encabezados, viñetas y pasos numerados. Los LLMs siguen prompts estructurados de manera más fiable.

precaución

Evita prompts del sistema excesivamente largos. Cada token en el prompt del sistema añade latencia y coste a cada llamada al LLM. Apunta a 200-500 palabras. Si necesitas más, considera si parte de la información podría obtenerse dinámicamente mediante function calling.

Mensaje de Bienvenida

Lo primero que dice el agente cuando se conecta una llamada. Se reproduce como audio TTS antes de que el agente comience a escuchar.

Ejemplos:

• "Hello, thank you for calling Acme Corp. How can I help you today?"
• "Hi there! This is Sarah from Acme support. What can I do for you?"

Déjalo en blanco si quieres que el agente espere a que el llamante hable primero (útil para llamadas salientes donde el destinatario responde con "¿Hola?").

Variables Dinámicas

Los prompts del sistema y los mensajes de bienvenida pueden incluir marcadores {{variable}} que se rellenan con valores reales en el momento en que comienza cada llamada. Esto permite que un mismo agente se adapte al contexto de la llamada -- la fecha de hoy, el número del llamante, el nombre de un cliente -- sin que tengas que editar el prompt para cada llamada.

Un marcador se escribe con dobles llaves alrededor de un nombre en minúsculas, por ejemplo {{date}} o {{customer_name}}. Los nombres pueden contener letras minúsculas, dígitos y guiones bajos. Cada marcador se resuelve una sola vez, al inicio de la llamada, antes de que el prompt del sistema llegue a la IA y antes de que se hable el mensaje de bienvenida. Si un nombre de marcador no se reconoce en el momento de la llamada, se resuelve como una cadena vacía, de modo que un {{...}} suelto nunca se lee en voz alta ni se envía al modelo.

Hay dos tipos de variable: las variables integradas que el sistema siempre proporciona, y las variables personalizadas que defines por agente.

Variables integradas

Están disponibles en cada agente sin configuración. Se resuelven al valor vigente al inicio de la llamada.

Variable	Se resuelve a
{{date}}	La fecha en que comienza la llamada, ej. 2026-07-01.
{{time}}	La hora en que comienza la llamada.
{{timezone}}	La zona horaria usada para date y time. Actualmente siempre UTC.
{{caller_number}}	El número de teléfono del llamante.
{{called_number}}	El número que se marcó.
{{call_duration}}	Duración de la llamada en segundos. Siempre 0 al inicio de la llamada (las variables se resuelven solo una vez).
{{agent_id}}	El ID único del agente.
{{conversation_id}}	El ID del registro de llamada de VOCALS para esta conversación.
{{call_id}}	El identificador de llamada del proveedor de telefonía (Call SID).
{{total_turns}}	Total de turnos de conversación hasta ahora. Siempre 0 al inicio de la llamada.
{{agent_turns}}	Turnos tomados por el agente hasta ahora. Siempre 0 al inicio de la llamada.
{{subagent_turns}}	Turnos tomados por sub-agentes hasta ahora. Siempre 0 al inicio de la llamada.
{{is_text_only}}	true para conversaciones solo de texto, false para llamadas de voz.

nota

Las variables se resuelven una única vez, cuando comienza la llamada. Los valores que cambian durante una llamada (como call_duration o total_turns) reflejan su valor al inicio de la llamada y no se actualizan a mitad de la llamada.

Variables personalizadas

Las variables personalizadas te permiten inyectar tus propios valores de negocio -- el nombre de una empresa, el horario de atención, el nombre de un cliente -- en los prompts y mensajes de bienvenida. Defínelas en el editor de Variables Personalizadas junto al prompt del sistema y al mensaje de bienvenida:

1. Añade una variable y dale un nombre (letras minúsculas, dígitos, guiones bajos).
2. Dale un valor predeterminado. El valor predeterminado es obligatorio y no puede estar vacío -- un agente con una variable personalizada que tenga un valor predeterminado en blanco no se puede guardar, y el editor muestra un error que nombra la variable ofensiva.
3. Referénciala en cualquier parte del prompt del sistema o del mensaje de bienvenida como {{tu_nombre}}.

El valor predeterminado garantiza que la variable siempre se resuelva a algo. Puedes sustituir el valor de una variable personalizada para una sola llamada a través de la API de disparo de llamadas -- por ejemplo para pasar el nombre de un llamante concreto al marcar -- sin cambiar el valor predeterminado guardado.

Ayuda de edición y validación

Mientras editas un prompt del sistema o un mensaje de bienvenida:

• Escribe {{ para abrir un selector que lista todas las variables disponibles para este agente (todas las integradas más tus variables personalizadas). Sigue escribiendo para filtrar la lista; selecciona un elemento para insertar el marcador {{nombre}} completo. Pulsa Escape o haz clic fuera para cerrarlo sin insertar.
• Los marcadores reconocidos y los no reconocidos se resaltan en colores diferentes, de modo que un error como {{ddate}} destaca frente a un {{date}} válido.
• Se permite guardar un agente que todavía contenga un marcador no reconocido. Una advertencia nombra cada marcador no reconocido antes de guardar para que puedas corregir un error tipográfico o mantenerlo intencionadamente.

El panel advierte, la API rechaza

El panel es una superficie de edición para humanos, por lo que solo advierte sobre marcadores no reconocidos y te deja guardar. La API de disparo de llamadas es una superficie de integración para máquinas, por lo que es estricta: pasar una clave variables que no sea una variable personalizada definida (o que coincida con el nombre de una variable integrada) se rechaza con un error HTTP 422. Consulta la referencia de la API de disparo de llamadas para las reglas exactas.

Idioma

El idioma principal de la conversación. Este ajuste se pasa al proveedor STT para mejorar la precisión de la transcripción. Configúralo para que coincida con el idioma que hablarán tus llamantes.

Valores comunes: en-US, en-GB, es-ES, es-MX, pt-BR, fr-FR, de-DE, zh-CN, ja-JP.

Sensibilidad de Interrupción

Controla con qué facilidad el llamante puede interrumpir al agente mientras está hablando. La interrupción (también llamada "barge-in") detiene la reproducción TTS actual y procesa lo que dijo el llamante.

Nivel	Comportamiento
Muy Bajo	Requiere habla sostenida y clara para interrumpir. Mejor para entornos muy ruidosos (centros de llamadas, calles, fábricas).
Bajo	El llamante debe hablar fuerte o durante más tiempo para interrumpir. Reduce las falsas activaciones por ruido de fondo.
Medio	Ajuste equilibrado. Funciona bien para la mayoría de entornos.
Alto	El agente deja de hablar rápidamente cuando se detecta el habla del llamante. Mejor para entornos silenciosos.
Muy Alto	El agente deja de hablar ante la primera señal de habla del llamante. Mejor para entornos muy silenciosos y conversaciones de ritmo rápido.

tip

Si notas que el agente se interrumpe por ruido de fondo, baja la sensibilidad de interrupción. Si los llamantes se quejan de que el agente habla encima de ellos, súbela.

Interrumpible

Un interruptor booleano que habilita o deshabilita la interrupción por completo.

• Habilitado (predeterminado): El llamante puede interrumpir al agente a mitad de frase.
• Deshabilitado: El agente siempre termina su respuesta actual antes de escuchar. Úsalo para mensajes donde el mensaje completo debe ser escuchado (ej., avisos legales, declaraciones de cumplimiento normativo).

Duración Máxima de Llamada

La duración máxima de una llamada en segundos. Cuando se alcanza el límite, el agente dirá un mensaje de cierre configurable y colgará.

• Predeterminado: 600 (10 minutos)
• Establece un valor más bajo para casos de uso simples (confirmaciones de citas, encuestas) para controlar costes.
• Establece un valor más alto para llamadas de soporte complejas que puedan necesitar una conversación extendida.

Umbral de Silencio

Controla la sensibilidad de la Detección de Actividad de Voz (VAD) para la interrupción. Es un valor decimal (predeterminado 0.5) que determina con qué confianza el sistema debe detectar habla antes de activar una interrupción.

• Valores más altos (ej., 0.7 - 0.9) requieren una detección de habla más segura, reduciendo falsas interrupciones por ruido de fondo.
• Valores más bajos (ej., 0.2 - 0.4) hacen la interrupción más sensible, captando habla más silenciosa pero también siendo más susceptible al ruido.

Esto funciona junto con el ajuste de sensibilidad de interrupción para afinar cómo responde el agente a las interrupciones del llamante.

Asignar Proveedores

Cada agente necesita un proveedor para cada etapa del pipeline:

1. En la configuración del agente, busca la sección de Proveedores.
2. Selecciona un Proveedor STT de tus proveedores configurados.
3. Selecciona un Proveedor LLM.
4. Selecciona un Proveedor TTS.

Puedes asignar diferentes proveedores a diferentes agentes. Por ejemplo, tu agente de ventas en inglés podría usar Deepgram + GPT-4o + ElevenLabs, mientras que tu agente de soporte en chino usa Qwen + Kimi + ElevenLabs.

nota

Cambiar proveedores en un agente activo surte efecto en la siguiente llamada. Las llamadas activas continúan usando los proveedores que estaban configurados cuando la llamada comenzó.

Endpoints Personalizados

Los Endpoints Personalizados permiten que un agente llame a tu propia API HTTP durante una llamada en vivo, sin código y sin ayuda de ingeniería. Defines una "herramienta" saliente (por ejemplo, "crear un lead en mi CRM" o "consultar el estado de un pedido"), y el agente decide cuándo usarla según la conversación. Cuando el agente la llama, VOCALS realiza la petición HTTP, espera la respuesta y devuelve el resultado al mismo turno para que el agente pueda actuar sobre él.

Gestionas los Endpoints Personalizados de un agente desde la sección Endpoints personalizados en la página de detalle del agente, junto a Integraciones, para que todas las herramientas invocables de un agente estén en un solo lugar.

Añadir un endpoint

Haz clic en Añadir endpoint y completa el editor:

• Nombre de la herramienta -- un nombre corto en minúsculas (letras, dígitos, guiones bajos) que la IA usa para referirse a esta herramienta, p. ej. create_lead.
• Descripción -- indica a la IA cuándo y por qué llamar a esta herramienta. Una descripción clara es el factor más importante para que la IA elija la herramienta en el momento adecuado.
• Método -- el método HTTP: GET, POST, PUT, PATCH o DELETE.
• URL -- la dirección de destino, p. ej. https://api.ejemplo.com/leads. La URL debe ser una dirección pública http/https.
• Cabeceras -- cabeceras estáticas de la petición, incluida la autenticación (ver más abajo).
• Cuerpo de la petición -- opcional. La carga enviada con la petición, normalmente JSON.
• Parámetros -- valores que la IA recoge de la conversación y proporciona al llamar a la herramienta (ver más abajo).
• Tiempo de espera -- cuánto esperar una respuesta, de 1 a 60 segundos (10 segundos por defecto). Si el endpoint no responde a tiempo, la llamada se trata como un fallo y la conversación continúa.
• Activado -- controla si el agente puede usar el endpoint. Un endpoint desactivado conserva su configuración pero no se ofrece a la IA.

Haz clic en Guardar. Puedes añadir hasta 20 endpoints por agente.

Autenticación y seguridad de las cabeceras

Añade una cabecera de autenticación (por ejemplo Authorization con un valor como Bearer <tu token>) en Cabeceras.

Los valores de las cabeceras se tratan como secretos: se cifran al guardar y nunca se vuelven a mostrar. Tras guardar, un valor de cabecera almacenado aparece como "Valor guardado (oculto)" con un botón Reemplazar -- puedes sobrescribirlo con un valor nuevo, pero nunca puedes volver a leer el anterior. Es el mismo tratamiento de solo escritura usado para las claves de API de los proveedores.

Si un endpoint tiene una cabecera de tipo autenticación (como Authorization o X-API-Key) sin valor almacenado, la lista muestra un aviso Falta autenticación para que detectes la mala configuración antes de que falle en una llamada en vivo.

Uso de variables y parámetros

La URL, cada valor de cabecera y el cuerpo de la petición admiten los mismos marcadores {{variable}} que los prompts del sistema y los mensajes de bienvenida. Escribe {{ en cualquiera de estos campos para abrir un selector que lista todo lo disponible aquí:

• Variables integradas como {{caller_number}} y {{called_number}} (ver Variables Dinámicas).
• Variables personalizadas definidas en este agente.
• Parámetros definidos en este endpoint.

Los parámetros son los valores que la IA reúne durante la conversación y pasa cuando invoca la herramienta. Cada parámetro tiene un nombre, una descripción (para que la IA sepa qué recoger), un tipo (string, number, integer o boolean) y un indicador de obligatorio/opcional. Por ejemplo, define un parámetro customer_name y luego refiérelo en el cuerpo como {"name": "{{customer_name}}"} -- la IA lo rellena con lo que dijo el llamante.

Editar, desactivar y eliminar

• Usa el interruptor de cada endpoint para activarlo o desactivarlo sin perder su configuración.
• Usa el icono de lápiz para editar un endpoint. Los valores de cabecera almacenados permanecen ocultos; déjalos como "Valor guardado (oculto)" para conservarlos, o haz clic en Reemplazar para establecer uno nuevo.
• Usa el icono de papelera para eliminar un endpoint que ya no necesites.

Los cambios surten efecto en la siguiente llamada; las llamadas ya en curso no se ven afectadas.

nota

Si un endpoint personalizado falla, agota el tiempo de espera o devuelve un error durante una llamada, se le informa al agente de que la herramienta no tuvo éxito y continúa la conversación. Un endpoint fallido nunca corta la llamada.

Clonar un Agente

Para crear una variante de un agente existente:

1. Abre el agente que quieres clonar.
2. Haz clic en Clonar Agente.
3. Modifica los ajustes según sea necesario (ej., cambiar el idioma, intercambiar la voz TTS, ajustar el prompt del sistema).
4. Guarda con un nuevo nombre.

Esto es útil cuando necesitas agentes similares para diferentes idiomas o departamentos.

Probar un Agente

Próximamente

La prueba de agentes basada en web es una funcionalidad planificada. Una vez disponible, podrás probar agentes directamente desde el panel de control sin realizar una llamada telefónica real.

Mientras tanto, prueba tus agentes asignándolos a un número de teléfono y realizando una llamada. Revisa la transcripción y reproducción de audio de la llamada en Historial después de que termine la llamada.