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",
  "interruptible": true,
  "welcome_interruptible": false,
  "amd_enabled": false,
  "tts_config": { "speed": 1.0 },
  "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	Segundos de silencio antes de la deteccion de fin de turno
max_call_duration	integer	Duracion maxima de llamada en segundos (0 = ilimitado)
barge_in_sensitivity	string	very_low, low, medium, high, o very_high
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
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",
  "silence_threshold": 0.5,
  "max_call_duration": 600,
  "barge_in_sensitivity": "medium",
  "interruptible": true,
  "welcome_interruptible": false,
  "amd_enabled": false,
  "tts_config": { "speed": 1.0 },
  "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	Umbral de deteccion de silencio (segundos)
max_call_duration	integer	No	0	Duracion maxima de llamada (0 = ilimitado)
barge_in_sensitivity	string	No	"medium"	Nivel de sensibilidad de barge-in
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
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

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.

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.