Integração de voz do Agent Assist com o Five9

Essa integração de voz usa um conector clássico do Five9 e o Five9 MediaStream (antigo Voicestream) para fornecer sugestões do Agent Assist aos seus agentes no Five9 Agent Desktop Plus.

Antes de começar

Para integrar os módulos da interface do Agent Assist ao Five9, você precisa de acesso aos seguintes recursos.

Dependências necessárias do sistema

• Google Cloud CLI
  • Instale a CLI do Google Cloud conforme as instruções.
  • Autentique-se usando gcloud auth login.
• Implantação do back-end de integração do Agent Assist
  • Siga as instruções para configurar a integração.
  • Além da configuração normal e antes de executar o script de implantação, configure as seguintes variáveis de ambiente em aa-integration-backend/.env:
    • AUTH_OPTION: defina como Five9.
    • FIVE9_TRUST_TOKEN: gere isso executando o seguinte:
      • cd platforms/five9
      • cp .env.sample .env
      • make generate-trust-token
• Perfil de conversa do Agent Assist: consulte Criar um perfil de conversa para mais detalhes.
• Acesso de administrador do Five9: necessário para configurar a assinatura do Mediastream e o Classic Connector.
• Make: usado para executar scripts de implantação.

Dependências opcionais do sistema

• Podman (opcional): para criação de contêineres e testes locais.
  • Guia de instalação do Podman
  • Guia de instalação do Podman-Compose
• grpcurl (opcional): para verificar a integridade do stream gRPC.
  • Guia de instalação

Visão geral da arquitetura de integração

A solução usa uma arquitetura de serviço dividido para lidar com os requisitos distintos do protocolo da Five9: streaming de áudio bidirecional em tempo real (gRPC) e processamento de eventos assíncrono (HTTP). Esses dois serviços do Cloud Run conectam o Five9 MediaStream ao Google Cloud Assistente de agente, permitindo transcrição em tempo real e sugestões de IA generativa:

• mediastream-grpc-service: processa o stream de áudio gRPC bidirecional do Five9 MediaStream.
• mediastream-http-service: apresenta módulos da interface do Agent Assist e processa eventos de CTI e MediaStream.

Fluxo de dados de alto nível

1. Início da chamada: o Five9 aciona um evento de CTI para o serviço HTTP, iniciando a sessão.
2. Streaming de áudio: o Five9 abre uma conexão gRPC segura com o serviço gRPC para troca de áudio em tempo real.
3. Processamento: o serviço gRPC encaminha o áudio para o Google Cloud Agent Assist.
4. Sugestões: o Agent Assist retorna sugestões de transcrição e treinamento de agentes pelo Pub/Sub, que são encaminhadas para os módulos da interface do Agent Assist por uma conexão Socket.IO (WebSockets) com o serviço do conector da interface do Cloud Run. Essas sugestões são renderizadas em um iframe do Five9 Classic Connector no Five9 Agent Desktop Plus durante as chamadas.

Serviço gRPC (mediastream-grpc)

• Função: processa streaming de áudio bidirecional em tempo real e de alta performance.
• Implementação: servidor gRPC Python usando grpcio.
• Simultaneidade: usa grpc.aio (AsyncIO) para E/S não bloqueadora de alto desempenho.
• Protocolo: define o contrato de serviço usando mediastream-grpc/proto/voice.proto.
• Módulo principal: a implementação do VoiceServicer em services/get_suggestions.py orquestra o processamento do stream de áudio e as chamadas da API Agent Assist.

Serviço HTTP (mediastream-http)

• Função: processa eventos do plano de controle, validação de token e disponibilização de recursos estáticos da UI.
• Implementação: servidor da Web Flask.
• Endpoints:
  • GET /: um endpoint de verificação de integridade para o servidor.
  • GET /agent-assist-ui-modules: veicula os módulos da interface do Assistente do agente para o conector clássico do Five9.
  • GET /cti-call-event-destination/: valida o FIVE9_TRUST_TOKEN (retorna o hash SHA256).
  • POST /cti-call-event-destination/: recebe eventos e metadados de CTI de chamadas.
  • POST /mediastream-event-destination/subscriptions/<id>: recebe erros assíncronos ou atualizações de status do stream de mídia.

Segurança

• Token de confiança: a integração implementa um modelo de segurança de segredo compartilhado. Um FIVE9_TRUST_TOKEN é gerado e configurado no Five9 e no serviço do Cloud Run. O serviço HTTP fornece um endpoint de validação (GET /cti-call-event-destination/) que retorna o hash SHA256 do token configurado para verificação.
• Esse token de confiança também é reutilizado como a chave secreta compartilhada que autentica solicitações do serviço HTTP MediaStream para o conector de interface.

Guia de implantação

As seções a seguir descrevem como implantar e testar essa integração do Agent Assist com o Five9 no Five9 Agent Desktop Plus.

Configure as variáveis de ambiente

1. Primeiro, execute cd aa-integration-backend/platforms/five9 para mudar de diretório.

2. Verifique se você tem um arquivo .env copiado de .env.sample na seção Dependências necessárias do sistema. A última linha precisa conter o FIVE9_TRUST_TOKEN gerado naquele momento.

3. Variáveis de ambiente: preencha o arquivo .env com os seguintes detalhes.

   Variável	Descrição
   PROJECT_ID	O ID do projeto do Google Cloud .
   REGION	A região em que seus serviços do Cloud Run serão implantados.
   CONVERSATION_PROFILE_NAME	O ID do recurso do perfil de conversa do Agent Assist.
   FEATURES	Os recursos a serem ativados para o Agent Assist. Consulte a documentação Propriedades do contêiner de módulos da interface V2.
   FIVE9_API_KEY	Defina isso como a chave de API do Five9 que você recebeu ao configurar a assinatura do MediaStream.
   FIVE9_TRUST_TOKEN	A chave secreta compartilhada gerada em Antes de começar, que permite que o mediastream-http-service se autentique com o serviço do Cloud Run ui-connector.

Implantar no Google Cloud Run

Implante os serviços gRPC e HTTP no Cloud Run usando a automação fornecida:

make deploy

Esse script fará o seguinte:

1. Crie as imagens de contêiner.
2. Envie-os para o Google Container Registry (GCR) ou o Artifact Registry.
3. Implante dois serviços do Cloud Run: um para gRPC (voz) e outro para HTTP (eventos).
4. Mostre os URLs de serviço após a conclusão.

Configuração do Five9

Após a implantação, configure o Five9 para enviar streams ao seu serviço. Consulte o Guia técnico do MediaStream do Five9 para conferir as etapas detalhadas.

Configuração inicial do Five9

Siga estas etapas para configurar o Admin Console do Five9 para a integração com o Agent Assist.

1. Crie uma nova habilidade, por exemplo, Integração do Agent Assist.
2. Atribua usuários à habilidade.
3. Configure um conector clássico do Five9 para sua campanha, usando o URL do serviço do Cloud Run MediaStream que você implantou em uma etapa anterior:
   • URL: {mediastream-http-service-url}/agent-assist-ui-modules/
   • Método: GET
   • Parâmetros: call_id
   • Modo de execução: In Browser
     • Aplicativo do agente: Use embedded tab for Web Agent
     • Serviços da Web de CTI: Current browser window
   • Acionador (próxima guia): On Call Accepted
4. Crie um script de URA para definir o comportamento ao receber chamadas pelo número DNIS do Five9.
5. Criar uma campanha inbound
6. Associe o script da URA à campanha
7. Se quiser, crie uma campanha de saída para ativar o Agent Assist em ligações desse tipo. Isso envolve o seguinte:
   • Associe uma habilidade à campanha de saída.
   • Crie uma cópia do conector clássico e associe-a à campanha de saída. Mude o acionador da cópia do conector clássico para Ao selecionar contato.
   • Inicie a campanha. Para testar, faça uma ligação externa no Agent Desktop Plus, selecionando a campanha externa no menu suspenso.

Criar uma assinatura de MediaStream

1. Nome da assinatura: fluxo de mídia de integração do Agent Assist
2. Tipo de streaming: streaming de voz
   • Destino de streaming: outro (self-service)
   • Protocolo de streaming: gRPC
   • Destino principal de streaming:
     • <five9-mediastream-grpc-deployment-url-without-protocol>:443
     • Por exemplo: five9-mediastream-grpc-123412341234.us-central1.run.app:443
   • Destino do evento de chamada CTI:
     • https://<five9-mediastream-http-deployment-url>/cti-call-event-destination/
     • Por exemplo: https://five9-mediastream-http-123412341234-uc.a.run.app/cti-call-event-destination/
   • Destino do evento mediastream:
     • https://<five9-mediastream-http-deployment-url>/mediastream-event-destination/
     • Por exemplo: https://five9-mediastream-http-123412341234-uc.a.run.app/mediastream-event-destination/
   • Token de confiança: o FIVE9_TRUST_TOKEN gerado em uma etapa anterior.
   • Chave de API: esse campo será gerado depois que você salvar sua assinatura do Mediastream. Copie o FIVE9_API_KEY que você recebeu para platforms/five9/.env. Você vai precisar dele na próxima etapa.
   • Filtro de streaming:
     • Filtro personalizado: marcado
     • Tipo de filtro: campanhas
     • Pesquisar campanhas adicionadas: pesquise e adicione sua campanha.

Reimplantar no Google Cloud Run

• Importante: depois de criar sua assinatura do MediaStream, adicione o FIVE9_API_KEY recebido ao arquivo platforms/five9/.env e reimplante executando make deploy.

Verificação da implantação

Confirme se os serviços implantados estão acessíveis no Cloud Run:

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

Simule uma chamada transmitindo um arquivo .wav para o mediastream-grpc-service:

make test-grpc-stream

Agora você pode testar a transcrição e as sugestões do Agent Assist enquanto atende chamadas no Five9 Agent Desktop Plus.

Teste local (opcional)

Para resolver problemas ou testar sem implantação, execute os serviços localmente usando o Docker/Podman. Parar contêineres, criar e executar localmente com o Podman Compose.

make all

Executar todos os testes (integridade, unidade), exceto stream

make test

Simular uma chamada transmitindo um arquivo .wav

make test-grpc-stream LOCAL=true

Observação: também é possível ver os resultados da transcrição e das sugestões do gRPC durante test-grpc-stream definindo o nível de geração de registros como "debug" em platforms/five9/mediastream-grpc-server/main.py.