Agentes

Los agentes son la entidad principal en VOCALS. Cada agente define una persona de IA conversacional con su propia configuracion de proveedores STT, LLM y TTS, system prompt, ajustes de voz y asignaciones de numeros de telefono.

Listar Agentes

GET /agents

Devuelve todos los agentes del tenant actual, ordenados por nombre.

Respuesta

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Support Agent",
    "active_stt_provider_id": "...",
    "active_llm_provider_id": "...",
    "active_tts_provider_id": "...",
    "is_active": true,
    "phone_count": 2,
    "has_webhook": true,
    "created_at": "2026-01-15T10:30:00Z",
    "updated_at": "2026-02-20T14:00:00Z"
  }
]

Campos de Respuesta (Lista)

Campo	Tipo	Descripcion
id	uuid	ID del agente
name	string	Nombre visible del agente
active_stt_provider_id	uuid | null	Proveedor STT asignado
active_llm_provider_id	uuid | null	Proveedor LLM asignado
active_tts_provider_id	uuid | null	Proveedor TTS asignado
is_active	boolean	Si el agente esta activo
phone_count	integer	Cantidad de numeros de telefono asignados
has_webhook	boolean	Si tiene una URL de webhook configurada
created_at	datetime	Marca de tiempo de creacion
updated_at	datetime	Marca de tiempo de ultima actualizacion

Obtener Agente

GET /agents/{agent_id}

Devuelve el detalle completo del agente incluyendo las asignaciones de numeros de telefono.

Respuesta

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Support Agent",
  "active_stt_provider_id": "...",
  "active_llm_provider_id": "...",
  "active_tts_provider_id": "...",
  "system_prompt": "You are a helpful support agent...",
  "welcome_message": "Hello! How can I help you today?",
  "voice_id": "rachel",
  "language": "en",
  "silence_threshold": 0.5,
  "max_call_duration": 300,
  "barge_in_sensitivity": "medium",
  "stt_endpointing_sensitivity": "medium",
  "interruptible": true,
  "welcome_interruptible": false,
  "amd_enabled": false,
  "tts_config": { "speed": 1.0 },
  "custom_variables": [
    { "name": "company_name", "default": "Acme Corp" },
    { "name": "support_hours", "default": "9am-5pm" }
  ],
  "webhook_url": "https://example.com/webhook",
  "webhook_secret": "whsec_...",
  "is_active": true,
  "phone_numbers": [
    {
      "id": "...",
      "phone_number": "+15551234567",
      "sip_config_id": "..."
    }
  ],
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-02-20T14:00:00Z"
}

Campos de Respuesta (Detalle)

Campo	Tipo	Descripcion
id	uuid	ID del agente
name	string	Nombre visible del agente
active_stt_provider_id	uuid | null	Proveedor STT asignado
active_llm_provider_id	uuid | null	Proveedor LLM asignado
active_tts_provider_id	uuid | null	Proveedor TTS asignado
system_prompt	string | null	System prompt enviado al LLM
welcome_message	string | null	Mensaje hablado al inicio de la llamada
voice_id	string | null	Identificador de voz del TTS
language	string	Codigo de idioma (ej. en, es)
silence_threshold	float	Obsoleto e ignorado. Se almacena y se devuelve solo por compatibilidad; no tiene ningun efecto en la llamada. Usa stt_endpointing_sensitivity en su lugar.
max_call_duration	integer	Duracion maxima de llamada en segundos (0 = ilimitado)
barge_in_sensitivity	string	very_low, low, medium, high, o very_high
stt_endpointing_sensitivity	string	very_low, low, medium, high, o very_high. Con que rapidez el agente decide que quien llama ha terminado de hablar (ver Velocidad de Respuesta).
interruptible	boolean	Si el agente puede ser interrumpido mientras habla
welcome_interruptible	boolean	Si el mensaje de bienvenida puede ser interrumpido
amd_enabled	boolean	Deteccion de contestador automatico para llamadas salientes
tts_config	object | null	Configuracion especifica del proveedor TTS
custom_variables	array | null	Definiciones de variables personalizadas por agente, cada una { "name": ..., "default": ... }. Se usan para rellenar marcadores {{name}} en el system prompt y el mensaje de bienvenida. Consulta Variables Dinámicas.
webhook_url	string | null	URL para webhooks de eventos de llamada
webhook_secret	string | null	Secreto para verificacion de firma de webhook
is_active	boolean	Si el agente esta activo
phone_numbers	array	Numeros de telefono asignados con referencias a configuracion SIP
created_at	datetime	Marca de tiempo de creacion
updated_at	datetime	Marca de tiempo de ultima actualizacion

Crear Agente

POST /agents

Cuerpo de la Solicitud

{
  "name": "Sales Agent",
  "active_stt_provider_id": "uuid-of-stt-provider",
  "active_llm_provider_id": "uuid-of-llm-provider",
  "active_tts_provider_id": "uuid-of-tts-provider",
  "system_prompt": "You are a sales representative...",
  "welcome_message": "Hi there! Thanks for calling.",
  "voice_id": "rachel",
  "language": "en",
  "max_call_duration": 600,
  "barge_in_sensitivity": "medium",
  "stt_endpointing_sensitivity": "medium",
  "interruptible": true,
  "welcome_interruptible": false,
  "amd_enabled": false,
  "tts_config": { "speed": 1.0 },
  "custom_variables": [
    { "name": "company_name", "default": "Acme Corp" }
  ],
  "webhook_url": "https://example.com/webhook",
  "is_active": true,
  "phone_numbers": [
    {
      "phone_number": "+15551234567",
      "sip_config_id": "uuid-of-sip-config"
    }
  ]
}

Campos de la Solicitud

Campo	Tipo	Requerido	Por defecto	Descripcion
name	string	Si	--	Nombre visible del agente
active_stt_provider_id	uuid	No	null	Proveedor STT a usar
active_llm_provider_id	uuid	No	null	Proveedor LLM a usar
active_tts_provider_id	uuid	No	null	Proveedor TTS a usar
system_prompt	string	No	null	System prompt para el LLM
welcome_message	string	No	null	Mensaje hablado al iniciar la llamada
voice_id	string	No	null	Identificador de voz del TTS
language	string	No	"en"	Codigo de idioma
silence_threshold	float	No	0.5	Obsoleto e ignorado. Se sigue aceptando para que los clientes existentes sigan funcionando, pero no tiene ningun efecto en la llamada. Usa stt_endpointing_sensitivity en su lugar.
max_call_duration	integer	No	0	Duracion maxima de llamada (0 = ilimitado)
barge_in_sensitivity	string	No	"medium"	Nivel de sensibilidad de barge-in
stt_endpointing_sensitivity	string	No	"medium"	Con que rapidez el agente decide que quien llama ha terminado de hablar (ver Velocidad de Respuesta)
interruptible	boolean	No	true	Permitir interrupcion mientras habla
welcome_interruptible	boolean	No	false	Permitir interrupcion del mensaje de bienvenida
amd_enabled	boolean	No	false	Activar deteccion de contestador automatico
tts_config	object	No	null	Configuracion extra del proveedor TTS
custom_variables	array	No	null	Definiciones de variables personalizadas por agente (ver abajo)
webhook_url	string	No	null	URL del endpoint de webhook
webhook_secret	string	No	null	Secreto de firma del webhook
is_active	boolean	No	true	Si el agente esta activo
phone_numbers	array	No	null	Asignaciones de numeros de telefono. Cada phone_number debe estar en E.164 con el prefijo del pais (+34930485412); los separadores se eliminan y un valor sin + y prefijo de pais devuelve 422.

Variables Personalizadas

custom_variables define los marcadores de variables dinámicas del agente. Cada entrada es un objeto con un name y un default:

"custom_variables": [
  { "name": "company_name", "default": "Acme Corp" },
  { "name": "support_hours", "default": "9am-5pm" }
]

Campo	Tipo	Descripcion
name	string	Nombre de la variable. Solo letras minúsculas, dígitos y guiones bajos. Debe ser único dentro del agente y no debe coincidir con el nombre de una variable integrada.
default	string	Valor predeterminado obligatorio y no vacío, usado siempre que la variable no se sustituya para una llamada.

Referencia una variable personalizada como {{name}} en el system_prompt o welcome_message; se resuelve al inicio de la llamada. Los valores predeterminados pueden sustituirse por llamada mediante la API de disparo de llamadas. Para la lista completa de variables integradas y el comportamiento de edición, consulta Variables Dinámicas.

La API devuelve 422 Unprocessable Entity cuando un default está vacío o ausente (el mensaje nombra la variable ofensiva), cuando un name está mal formado, cuando los nombres están duplicados, cuando un nombre coincide con una variable integrada, o cuando la lista supera el límite por agente.

Respuesta

201 Created -- Devuelve el objeto AgentResponse completo.

Los IDs de proveedor se validan contra los proveedores configurados de tu tenant. Si un ID de proveedor es invalido o pertenece al tipo incorrecto (ej. pasar un ID de proveedor LLM como proveedor STT), la API devuelve 400 Bad Request.

tts_config se almacena tal cual se envia

Nunca se sustituye un modelo por el que tu configuras. tts_config se guarda literalmente tanto al crear como al actualizar: si no envias model_id, no se almacena ninguno y la llamada usa el modelo de la fila del proveedor TTS del agente.

Una version anterior sembraba brevemente "model_id": "eleven_flash_v2_5" en los agentes nuevos de ElevenLabs. Eso se ha eliminado. Los agentes creados mientras estaba activo conservan ese valor en su tts_config almacenado y lo seguiran usando hasta que envies otro model_id o los vuelvas a crear.

Cuando el agente usa cualquiera de los dos proveedores TTS de Google (google o google_gemini) junto con un voice_id, al guardar se ejecuta una sintesis de prueba de esa voz exacta antes de almacenar el agente. Si la sintesis falla - por ejemplo una voz que el proyecto de la credencial no puede alcanzar, una credencial invalida, o una clave de Cloud Text-to-Speech pegada en un proveedor google_gemini - la API devuelve 400 Bad Request con el error subyacente incluido, y el agente no se guarda. Si tts_config.google_style_prompt supera su longitud maxima de 500 caracteres, la API devuelve 422 Unprocessable Entity antes de realizar cualquier cambio. Ambas comprobaciones aplican a crear y actualizar.

tts_config.google_style_prompt

Una instruccion de interpretacion opcional, de hasta 500 caracteres, aplicada a cada respuesta que pronuncia el agente:

{
  "active_tts_provider_id": "550e8400-e29b-41d4-a716-446655440000",
  "voice_id": "Zephyr",
  "tts_config": { "google_style_prompt": "Habla con calidez y despacio" }
}

Solo tiene efecto cuando el proveedor TTS activo del agente es google_gemini, cuyas voces aceptan direccion de interpretacion. Todos los demas proveedores TTS lo ignoran - incluido google (Google Cloud TTS), que no tiene capacidad de estilo en su superficie: el valor se almacena pero no afecta a la sintesis. Ten en cuenta que los ids de voz de google_gemini son nombres preconstruidos simples como Zephyr, no los ids con prefijo de locale que usa Google Cloud TTS.

Velocidad de Respuesta

stt_endpointing_sensitivity controla con que rapidez el agente decide que quien llama ha terminado de hablar y empieza a responder. Usa la misma escala de cinco niveles que barge_in_sensitivity, y su valor por defecto es "medium":

Valor	Comportamiento
very_low	Espera mas tiempo antes de responder. Ideal para quienes hacen pausas a mitad de frase o dictan numeros largos.
low	Espera algo mas que el valor por defecto.
medium	Valor por defecto equilibrado.
high	Responde antes, a costa de interrumpir alguna pausa.
very_high	Respuesta mas rapida. Ideal para intercambios cortos y rapidos en una linea limpia.

Cualquier otro valor devuelve 422 Unprocessable Entity con los valores permitidos. El ajuste no tiene efecto en agentes de voz a voz (modo live), donde el modelo detecta por si mismo el fin del habla.

Actualizar Agente

PUT /agents/{agent_id}

Se soportan actualizaciones parciales. Solo incluye los campos que deseas cambiar.

Cuerpo de la Solicitud

{
  "name": "Updated Agent Name",
  "system_prompt": "New system prompt...",
  "is_active": false
}

Todos los campos del esquema de creacion son aceptados, pero ninguno es obligatorio.

Respuesta

200 OK -- Devuelve el objeto AgentResponse actualizado.

Eliminar Agente

DELETE /agents/{agent_id}

Elimina permanentemente un agente y sus asignaciones de numeros de telefono.

Respuesta

204 No Content -- Sin cuerpo de respuesta.

Obtener Agente por Numero de Telefono

GET /agents/by-phone/{phone}

Busca el agente asignado a un numero de telefono especifico. Util para logica de enrutamiento.

Parametros de Ruta

Parametro	Tipo	Descripcion
phone	string	Numero de telefono en formato E.164 (ej. +15551234567)

Respuesta

Devuelve el objeto AgentResponse completo, o 404 si ningun agente esta asignado a ese numero.