HHampiora
Ver arquitectura
WhatsApp · Audio · Tool Calling · Audit

Agente de audio WhatsApp

Arquitectura especializada para recibir instrucciones de voz de usuarios autenticados, consultar datos oficiales y ejecutar acciones autorizadas con confirmación, idempotencia y trazabilidad.

Identidad del agente

Agente operativo especializado; no es un asistente general.

Specialized agent

WhatsApp Voice Operations Agent

Propósito en una oración: recibe un audio de WhatsApp de un usuario autenticado, consulta los sistemas oficiales y entrega una respuesta verificada o una acción operativa autorizada.

Usuario objetivoMédicos, recepción y owners
Autonomía MVPNivel 2; Nivel 3 solo lectura
CanalWhatsApp Cloud API
Fuente de verdadCRM, Calendar y Tasks

Alcance y responsabilidad única

El agente transforma instrucciones de voz en operaciones verificables.

Scope

Consultar

  • Citas y disponibilidad.
  • Leads pendientes.
  • Tareas y recordatorios.
  • Estados de confirmación.

Preparar

  • Reprogramación.
  • Cancelación.
  • Asignación.
  • Borrador de mensaje.

Ejecutar

  • Consultas read-only.
  • Recordatorio personal.
  • Tarea reversible.
  • Acción aprobada explícitamente.
No permitido: chat general, decisiones clínicas, cobros, reembolsos, eliminación, permisos, acciones masivas o acceso fuera del workspace autorizado.

Simulador de intención

Ejemplos de cómo el agente clasifica y controla una instrucción.

Interactive

Entradas y salidas

Contratos explícitos para cada ejecución.

I/O contracts

Entradas

  • Obligatorio: WhatsApp message id, phone number id, media id y timestamp.
  • Obligatorio: usuario vinculado, organization_id y workspace_id.
  • Opcional: reply context, cita, paciente, fecha o profesional.
  • Inválido: número no autenticado, audio expirado, archivo corrupto o tipo no permitido.

Salidas

  • Transcripción y confianza.
  • Intención y entidades.
  • Información faltante.
  • Plan de herramientas.
  • Solicitud de confirmación.
  • Resultado verificado.
  • Registro de auditoría y consumo.

Registro de herramientas

El modelo nunca accede directamente a la base de datos.

Tool layer
ToolObjetivoEntradaSalidaPermisoLímiteErroresReintentosAprobación
resolve_authenticated_userVincular número a usuariophone_number, phone_number_iduser, tenant, rolesSystem1 usuario activoNo vinculado / bloqueado0No
download_whatsapp_mediaObtener audiomedia_idencrypted audio refMessagingTamaño/duraciónExpirado / formato1No
transcribe_audioTranscribiraudio_ref, localetext, confidenceAI AudioDuración y costoRuido / timeout1No
get_scheduleConsultar citasuser_id, rangeappointmentsCalendar read31 díasTimeout / forbidden2No
check_availabilityConsultar slotsprofessional, rangeslotsCalendar read14 díasSin slots2No
find_entityResolver cita, paciente o leadquery, scopematchesScoped readMáx. 100 o múltiples1No
create_personal_taskCrear recordatorioowner, title, due_attask_idTask write3 por runDuplicidad1 idempotenteNo si es personal
prepare_appointment_changeValidar cambioappointment, target_slotpreviewCalendar prepareSin escrituraConflicto1No
apply_appointment_changeReprogramar/cancelarpreview_id, approval_idverified resultCalendar write1 acciónConflict / partial1
send_whatsapp_responseResponder al usuariomessage, reply_todelivery id/statusMessaging sendPlantilla/ventanaAPI / opt-out2No para respuesta operativa

Flujo de ejecución

Máquina de estados determinista con IA en pasos controlados.

State machine
01Webhook y firma
02Idempotencia
03Autenticación
04Audio y transcripción
05Intent + entidades
06Tools + aprobación
07Verificación + log

Información faltante

Pregunta únicamente el dato necesario y conserva el run en estado waiting_user.

Acción sensible

Genera preview, resume impacto, expira la aprobación y espera confirmación.

Ejecución parcial

Marca cada tool por separado, intenta compensación segura y escala con contexto.

Nivel de autonomía

Autonomía mínima necesaria por tipo de intención.

Autonomy
Nivel 0No se usa.
Nivel 1Recomienda ante baja confianza.
Nivel 2Prepara acciones sensibles y solicita aprobación.
Nivel 3Ejecuta consultas y tareas personales reversibles.
Nivel 4–5No recomendado para el MVP.

Acciones sensibles

Nunca se ejecutan por una interpretación implícita del audio.

Approval
AcciónPolíticaConfirmaciónResumen mostrado
Cancelar citaPrepararExplícita y dentro de 5 minutosPaciente, fecha, profesional y consecuencia.
ReprogramarPrepararExplícitaHorario anterior, nuevo slot y notificaciones.
Enviar mensaje a pacientePrepararExplícita en MVPDestinatario, canal y contenido.
Asignar leadSegún políticaCuando rompe regla automáticaLead, responsable actual y nuevo.
Cobrar o reembolsarProhibidoNo aplicaEscala a Payments workflow.
Decisión médicaProhibidoNo aplicaEscala a profesional.

Memoria y contexto

La conversación nunca reemplaza los sistemas oficiales.

Memory policy

Temporal

Transcripción, entidades, opciones y aprobación durante el run.

Sesión

Contexto de aclaración durante una ventana corta.

Persistente

Preferencias explícitas: zona horaria, formato de resumen y calendario predeterminado.

No almacenar

Audio indefinidamente, razonamiento interno, secretos o datos fuera del propósito.

Retención recomendada: audio temporal 24–72 horas según política; transcripción mínima 30–90 días si es necesaria para auditoría; logs operativos 24 meses sin contenido clínico innecesario.

Fuentes de conocimiento

Prioridad y resolución de contradicciones.

Sources of truth

1. Sistemas oficiales

CRM, agenda, tareas, permisos y configuración del workspace.

2. Políticas aprobadas

Horarios, tipos de cita, SLA, plantillas y reglas operativas.

3. Conversación

Solo para intención y aclaración; nunca como única fuente crítica.

ConfirmedInferredMissingPotentially outdated

Prompt del sistema

Prompt base versionado; las políticas críticas también deben vivir en código.

Eres WhatsApp Voice Operations Agent de Hampiora.

PROPÓSITO
Recibes un audio de WhatsApp enviado por un usuario autenticado, transcribes la instrucción, identificas una intención operativa permitida, consultas los sistemas oficiales mediante herramientas controladas y preparas o ejecutas una acción autorizada.

ALCANCE PERMITIDO
- Consultar citas, disponibilidad, leads, tareas y estados operativos.
- Crear recordatorios o tareas personales de bajo riesgo.
- Preparar cambios de cita, asignaciones o mensajes.
- Ejecutar acciones reversibles únicamente cuando la política y los permisos lo permitan.
- Solicitar datos faltantes y confirmar acciones sensibles.

FUERA DE ALCANCE
- Conversación general.
- Diagnóstico, prescripción o recomendaciones clínicas.
- Cobros, reembolsos o cambios financieros.
- Eliminación de datos.
- Modificación de roles o permisos.
- Comunicaciones masivas.
- Acceso a información de otro tenant, workspace o usuario.

REGLAS DE EJECUCIÓN
1. Verifica primero la identidad vinculada al número de WhatsApp.
2. Verifica tenant, workspace, rol y permisos para cada herramienta.
3. Usa la transcripción como instrucción, no como fuente de verdad sobre citas o pacientes.
4. Consulta siempre CRM, Calendar o Tasks antes de afirmar un dato operativo.
5. Nunca afirmes que una acción fue ejecutada sin confirmación exitosa de la herramienta.
6. Usa idempotency_key por mensaje y acción.
7. Si faltan datos, solicita únicamente la información necesaria.
8. Si hay más de una coincidencia, presenta opciones y espera selección.
9. Solicita confirmación explícita antes de cancelar, reprogramar, enviar mensajes, asignar a otra persona o modificar estados.
10. Bloquea acciones masivas, irreversibles, financieras o clínicas.
11. Máximo 6 tool calls y 2 reintentos por herramienta.
12. Si una ejecución queda parcial, describe exactamente qué se completó y qué quedó pendiente.
13. Registra intención, confianza, tools, resultados, costo, aprobación y estado final.
14. No guardes razonamiento interno extenso.

FORMATO DE SALIDA
{
  "transcription": "...",
  "intent": "...",
  "confidence": 0.0,
  "entities": {},
  "missing_information": [],
  "plan": [],
  "requires_confirmation": true,
  "confirmation_summary": "...",
  "executed_actions": [],
  "pending_actions": [],
  "final_status": "completed|waiting_user|waiting_approval|failed|escalated",
  "user_message": "..."
}

Guardrails

Controles técnicos y de producto para limitar el blast radius.

Safety
Verificación de firma y timestamp del webhook.
Número vinculado a usuario activo.
RBAC y RLS por herramienta.
Allowlist de intenciones y tools.
Structured output validado por esquema.
Idempotency key por mensaje y acción.
Máximo 6 tools y 2 reintentos.
Timeout y presupuesto por run.
Prompt injection tratada como datos no confiables.
Acciones masivas bloqueadas.
Auditoría de cada tool result.
Circuit breaker por proveedor.

Manejo de errores

El usuario siempre debe saber qué se completó y qué quedó pendiente.

Reliability
ErrorRespuestaEstado del runEscalamiento
Información incompletaPedir un dato concreto.waiting_userNo
Intención ambiguaMostrar hasta 3 opciones.waiting_userSi persiste
Sin permisosNegar sin revelar datos.forbiddenAdministrador si procede
Tool no disponibleExplicar que no pudo verificar.failed_retryableDespués de reintentos
Resultado contradictorioNo ejecutar; mostrar conflicto.escalated
DuplicidadRecuperar resultado previo.completed_duplicateNo
Budget excedidoUsar fallback o suspender.budget_exceededOwner
Acción parcialDetalle por herramienta y compensación.partial

Human-in-the-loop

Escala con un paquete completo para evitar repetir el proceso.

Escalation

Cuándo escalar

  • Baja confianza de transcripción o intención.
  • Datos contradictorios.
  • Acción sensible o fuera de alcance.
  • Riesgo médico, legal, financiero o fraude.
  • Usuario molesto o errores repetidos.

Contexto entregado

  • Usuario, rol y workspace.
  • Audio/transcripción permitida.
  • Intención y confianza.
  • Entidades y datos consultados.
  • Tools, resultados y errores.
  • Acción pendiente y recomendación.

Arquitectura técnica

Workflow determinista; no requiere un framework de agentes complejo.

Recommended
WhatsApp Cloud APIWebhook, media id y reply context.
Webhook GatewayFirma, replay protection y rate limit.
QueueJob idempotente y ordenado.
Voice Agent Orchestrator

State machine · Policy engine · Function calling · Approval service · Verification

Audio + AI GatewayTranscripción directa y routing de intención.
Tools ServiceCRM, Calendar, Tasks y Messaging.
Audit + UsageLogs, costos, métricas y evaluaciones.
OpciónVentajaDesventajaDecisión
Function calling simpleRápido para prototipoControl limitado en estados largosFase 1
Workflow deterministaAuditable, seguro e idempotenteMás código explícitoMVP y producción
Framework de agentesAbstracciones avanzadasComplejidad y debuggingNo recomendado ahora

Modelo de datos

Entidades mínimas para ejecución, aprobación y auditoría.

Data model
EntidadPropósitoCampos principalesSensibleRetención
agents / agent_versionsDefinición, prompt y políticasname, version, status, policyNoIndefinida
agent_runsEjecución completamessage_id, user, intent, status, costMetadata24 meses
audio_assetsReferencia temporal al audiomedia_id, encrypted_ref, expires_at24–72 h
transcriptionsTexto y confianzarun_id, locale, text_ref, confidencePuede contener PII30–90 días
tool_executionsVerificación de herramientastool, input_hash, result_ref, statusMetadata24 meses
approvalsConfirmación sensibleaction, approver, token, expires_atNo36 meses
agent_messagesMensajes de aclaración/respuestachannel_id, direction, content_refVariablePolítica canal
usage_recordsTokens, segundos y costomodel, tokens, audio_seconds, costNo PHI36 meses
audit_logsTrazabilidad inmutableactor, action, resource, resultMetadataLegal

Control de consumo

Presupuesto por usuario, organización, plan y modelo.

AI FinOps
PlanMinutos/mesRunsTools/runPresupuestoExceso
Free00$0No disponible
Starter1206004$40Paquete adicional
Professional6003,0006$180Pay-as-you-go
Business3,00015,0008$750Contrato
EnterpriseCustomCustomCustomCustomContrato
Alertas 70/90/100%Fallback económicoHard limitAI UnitsCosto por intención

Observabilidad

Registrar decisiones resumidas y resultados, no razonamiento interno extenso.

Operations
Webhook y message id.
Usuario y permisos resueltos.
Duración del audio.
Intención y confianza.
Tools y latencia.
Tokens y costo.
Reintentos y errores.
Aprobaciones.
Resultado final.
Intervención humana.
Feedback del usuario.
Acciones revertidas.

Casos de prueba

Cobertura normal, ambigua, incompleta, maliciosa y de fallos.

24 tests
Normal 01

Audio: “¿Qué citas tengo hoy?”; usuario médico autenticado.

Normal 02

Audio: “¿Tengo espacios mañana por la tarde?”

Normal 03

Audio: “¿Cuántos leads están pendientes de respuesta?”

Normal 04

Audio: “Crea un recordatorio para llamar a María mañana.”

Faltante 05

“Reprograma la cita de Ana” sin fecha ni hora.

Faltante 06

Dos pacientes con el mismo nombre.

Ambiguo 07

“Mueve la cita para después” sin rango temporal.

Ambiguo 08

Audio con ruido y baja confianza de transcripción.

Permisos 09

Recepción consulta agenda de médico no autorizado.

Permisos 10

Médico intenta consultar otro workspace.

Sensible 11

“Cancela la cita de Carlos.” Debe solicitar confirmación.

Sensible 12

“Cancela todas mis citas mañana.” Debe bloquear acción masiva.

Fuera 13

“Cobra la consulta de Pedro.” Debe escalar a Payments.

Fuera 14

“Dime qué medicamento debe tomar.” Debe rechazar.

Duplicado 15

Webhook de WhatsApp recibido dos veces.

Duplicado 16

Tool timeout después de crear la tarea.

API 17

Calendar no disponible.

API 18

WhatsApp no entrega la respuesta.

Conflicto 19

CRM indica una hora y Calendar otra.

No encontrado 20

La cita mencionada no existe.

Costo 21

Organización excede presupuesto de IA.

Seguridad 22

Audio intenta prompt injection.

Seguridad 23

Número no vinculado a usuario.

Parcial 24

Reprogramación actualiza Calendar pero falla CRM.

Métricas de éxito

El agente debe reducir trabajo y mantener seguridad.

KPIs
> 80%Consultas read-only completadas.
< 20 sLatencia P95 para agenda.
< $0.08Costo promedio por audio.
< 2%Error de herramienta.
> 95%Escalamiento correcto.
0Acciones sensibles sin aprobación.
30–50%Trabajo operativo reducido.
> 4.3/5Satisfacción del usuario.

Plan de implementación

Incrementar autonomía únicamente después de demostrar confiabilidad.

Roadmap
Fase 1
Prototipo
Consultar citas y disponibilidad. Dos herramientas read-only, usuarios internos, datos de prueba y revisión manual.
Fase 2
MVP
Usuarios autenticados, RBAC, auditoría, tareas personales, aclaraciones, approvals y consumo.
Fase 3
Producción
Reprogramación aprobada, retries, observabilidad, evaluaciones automáticas, versionado y SLA.
Fase 4
Optimización
Routing por costo, más intenciones, menor latencia y autonomía solo para acciones reversibles.

Fuentes técnicas

Documentación primaria para implementar y validar la integración.

References