Integración de voz de Agent Assist con Five9

Esta integración de voz usa un conector clásico de Five9 y Five9 MediaStream (antes llamado Voicestream) para proporcionar sugerencias de Agent Assist a tus agentes en Five9 Agent Desktop Plus.

Antes de comenzar

Para integrar los módulos de la IU de Agent Assist con Five9, necesitas acceso a los siguientes recursos.

Dependencias del sistema requeridas

• Google Cloud CLI
  • Instala Google Cloud CLI según las instrucciones.
  • Autentícate con gcloud auth login.
• Implementación de backend de la integración de Agent Assist
  • Sigue las instrucciones para configurar la integración.
  • Además de la configuración normal, y antes de ejecutar la secuencia de comandos de implementación, configura las siguientes variables de entorno en aa-integration-backend/.env:
    • AUTH_OPTION: Configura esto como Five9.
    • FIVE9_TRUST_TOKEN: Para generar este valor, ejecuta el siguiente comando:
      • cd platforms/five9
      • cp .env.sample .env
      • make generate-trust-token
• Perfil de conversación de Agent Assist: Consulta Cómo crear un perfil de conversación para obtener más detalles.
• Acceso de administrador de Five9: Se requiere para configurar la suscripción a Mediastream y el conector clásico.
• Make: Se usa para ejecutar secuencias de comandos de implementación.

Dependencias opcionales del sistema

• Podman (opcional): Para la compilación de contenedores y las pruebas locales.
  • Guía de instalación de Podman
  • Guía de instalación de Podman-Compose
• grpcurl (opcional): Para verificar el estado de la transmisión de gRPC
  • Guía de instalación

Descripción general de la arquitectura de integración

La solución usa una arquitectura de servicios divididos para controlar los distintos requisitos del protocolo de Five9: transmisión de audio bidireccional en tiempo real (gRPC) y control de eventos asíncronos (HTTP). Estos dos servicios de Cloud Run conectan Five9 MediaStream con Google Cloud Agent Assist, lo que permite la transcripción en tiempo real y las sugerencias de IA generativa:

• mediastream-grpc-service: Controla la transmisión de audio bidireccional de gRPC desde Five9 MediaStream.
• mediastream-http-service: Presenta los módulos de la IU de Agent Assist y controla los eventos de CTI y MediaStream.

Flujo de datos de alto nivel

1. Inicio de la llamada: Five9 activa un evento de CTI en el servicio HTTP, lo que inicia la sesión.
2. Transmisión de audio: Five9 abre una conexión de gRPC segura al servicio de gRPC para el intercambio de audio en tiempo real.
3. Procesamiento: El servicio de gRPC reenvía el audio a Google Cloud Agent Assist.
4. Sugerencias: Agent Assist devuelve sugerencias de transcripción y entrenamiento del agente a través de Pub/Sub, que se reenvían a los módulos de la IU de Agent Assist a través de una conexión Socket.IO (WebSockets) con el servicio de UI Connector Cloud Run. Estas sugerencias se renderizan en un iframe de Five9 Classic Connector en Five9 Agent Desktop Plus durante las llamadas.

Servicio de gRPC (mediastream-grpc)

• Rol: Controla la transmisión de audio bidireccional en tiempo real y de alto rendimiento.
• Implementación: Servidor gRPC de Python que usa grpcio.
• Simultaneidad: Usa grpc.aio (AsyncIO) para E/S sin bloqueo de alto rendimiento.
• Protocolo: Define el contrato de servicio con mediastream-grpc/proto/voice.proto.
• Módulo principal: La implementación de VoiceServicer en services/get_suggestions.py organiza el control de la transmisión de audio y las llamadas a la API de Agent Assist.

Servicio HTTP (mediastream-http)

• Rol: Controla los eventos del plano de control, la validación de tokens y la publicación de recursos estáticos de la IU.
• Implementación: Servidor web de Flask
• Endpoints:
  • GET /: Es un extremo de verificación de estado para el servidor.
  • GET /agent-assist-ui-modules: Proporciona los módulos de la IU de Agent Assist para el conector clásico de Five9.
  • GET /cti-call-event-destination/: Valida el FIVE9_TRUST_TOKEN (devuelve el hash SHA256).
  • POST /cti-call-event-destination/: Recibe eventos y metadatos de CTI de llamadas.
  • POST /mediastream-event-destination/subscriptions/<id>: Recibe errores asíncronos o actualizaciones de estado de la transmisión de medios.

Seguridad

• Token de confianza: La integración implementa un modelo de seguridad de secreto compartido. Se genera y configura un FIVE9_TRUST_TOKEN tanto en Five9 como en el servicio de Cloud Run. El servicio HTTP proporciona un extremo de validación (GET /cti-call-event-destination/) que devuelve el hash SHA256 del token configurado para la verificación.
• Este token de confianza también se reutiliza como el secreto compartido que autentica las solicitudes del servicio HTTP de MediaStream al conector de IU.

Guía de implementación

En las siguientes secciones, se describe cómo implementar esta integración de Agent Assist en Five9 y probarla en Five9 Agent Desktop Plus.

Configure las variables de entorno

1. Primero, ejecuta cd aa-integration-backend/platforms/five9 para cambiar de directorio.

2. Verifica que tengas un archivo .env que hayas copiado de .env.sample en la sección Dependencias del sistema requeridas. La última línea debe contener el FIVE9_TRUST_TOKEN que generaste en ese momento.

3. Variables de entorno: Completa tu archivo .env con los siguientes detalles.

   Variable	Descripción
   PROJECT_ID	ID del proyecto de Google Cloud
   REGION	Región en la que se implementarán tus servicios de Cloud Run.
   CONVERSATION_PROFILE_NAME	Es el ID de recurso del perfil de conversación de Agent Assist.
   FEATURES	Son las funciones que se habilitarán para Agent Assist. Consulta la documentación de UI Modules Container V2 Properties.
   FIVE9_API_KEY	Establece este parámetro en tu clave de API de Five9 que obtuviste cuando configuraste la suscripción a MediaStream.
   FIVE9_TRUST_TOKEN	El secreto compartido que generaste en Antes de comenzar, que permite que mediastream-http-service se autentique con el servicio de Cloud Run ui-connector.

Implementa en Google Cloud Run

Implementa los servicios de gRPC y HTTP en Cloud Run con la automatización proporcionada:

make deploy

Esta secuencia de comandos hará lo siguiente:

1. Compila las imágenes de contenedor.
2. Envía las imágenes a Google Container Registry (GCR) o Artifact Registry.
3. Implementa dos servicios de Cloud Run: uno para gRPC (Voz) y otro para HTTP (Eventos).
4. Genera las URLs de servicio cuando se complete la operación.

Configuración de Five9

Después de la implementación, configura Five9 para que envíe transmisiones a tu servicio. Consulta la Guía técnica de MediaStream de Five9 para conocer los pasos detallados.

Configuración inicial de Five9

Sigue estos pasos para configurar la consola de administrador de Five9 para la integración de Agent Assist.

1. Crea una habilidad nueva, por ejemplo, Integración de Agent Assist.
2. Asigna usuarios a la habilidad.
3. Configura un conector clásico de Five9 para tu campaña, que muestre la URL del servicio de Cloud Run de MediaStream que implementaste en un paso anterior en un iframe:
   • URL: {mediastream-http-service-url}/agent-assist-ui-modules/
   • Método: GET
   • Parámetros: call_id
   • Modo de ejecución: In Browser
     • Agent Application: Use embedded tab for Web Agent
     • Servicios web de CTI: Current browser window
   • Activador (pestaña Siguiente): On Call Accepted
4. Crea un guion de IVR para definir el comportamiento cuando recibas llamadas a través de tu número de DNIS de Five9.
5. Crea una campaña de entrada
6. Asocia el guion del IVR a la campaña
7. De forma opcional, crea una campaña saliente para habilitar Agent Assist en las llamadas salientes. Esto implica lo siguiente:
   • Asocia una habilidad a la campaña saliente.
   • Crea una copia del conector clásico y asóciala a la campaña saliente. Cambia el activador de la copia del conector clásico a On Contact Selected.
   • Inicia la campaña. Para realizar una prueba, haz una llamada saliente en Agent Desktop Plus y selecciona la campaña saliente en el menú desplegable.

Crea una suscripción a MediaStream

1. Nombre de la suscripción: Flujo de medios de integración de Agent Assist
2. Tipo de transmisión: Transmisión de voz
   • Destino de transmisión: Otro (autoservicio)
   • Protocolo de transmisión: gRPC
   • Destino de transmisión principal:
     • <five9-mediastream-grpc-deployment-url-without-protocol>:443
     • Por ejemplo: five9-mediastream-grpc-123412341234.us-central1.run.app:443
   • Destino del evento de llamada de CTI:
     • https://<five9-mediastream-http-deployment-url>/cti-call-event-destination/
     • Por ejemplo: https://five9-mediastream-http-123412341234-uc.a.run.app/cti-call-event-destination/
   • Destino de eventos de Mediastream:
     • https://<five9-mediastream-http-deployment-url>/mediastream-event-destination/
     • Por ejemplo: https://five9-mediastream-http-123412341234-uc.a.run.app/mediastream-event-destination/
   • Trust Token: El FIVE9_TRUST_TOKEN que generaste en un paso anterior.
   • Clave de API: Este campo se generará después de guardar tu suscripción a Mediastream. Copia el FIVE9_API_KEY que recibas en platforms/five9/.env. La necesitarás en el próximo paso.
   • Filtro de transmisión:
     • Filtro personalizado: Marcado
     • Tipo de filtro: Campañas
     • Buscar campañas agregadas: Busca tu campaña y agrégala.

Cómo volver a implementar en Google Cloud Run

• Importante: Después de crear tu suscripción a MediaStream, deberás agregar el FIVE9_API_KEY que recibiste a tu archivo platforms/five9/.env y, luego, volver a implementar ejecutando make deploy.

Verificación de la implementación

Confirma que se pueda acceder a los servicios que implementaste en Cloud Run:

make test-http-reachable
make test-grpc-reachable

Simula una llamada transmitiendo un archivo .wav al mediastream-grpc-service:

make test-grpc-stream

Ahora puedes probar las transcripciones y sugerencias de Agent Assist mientras atiendes llamadas en Five9 Agent Desktop Plus.

Pruebas locales (opcional)

Para solucionar problemas o realizar pruebas sin implementación, puedes ejecutar los servicios de forma local con Docker o Podman. Detener contenedores, compilar y ejecutar de forma local con Podman Compose

make all

Ejecuta todas las pruebas (de estado y de unidades), excepto las de transmisión

make test

Simula una llamada transmitiendo un archivo .wav

make test-grpc-stream LOCAL=true

Nota: También es posible ver los resultados de la transcripción y las sugerencias de gRPC durante test-grpc-stream si se configura el nivel de registro como depuración en platforms/five9/mediastream-grpc-server/main.py.