將 Agent Assist 語音功能與 Five9 整合

這項語音整合功能使用 Five9 Classic Connector 和 Five9 MediaStream (舊稱 Voicestream)，在 Five9 Agent Desktop Plus 中為服務專員提供 Agent Assist 建議。

事前準備

如要將 Agent Assist UI 模組與 Five9 整合，您必須具備下列資源的存取權。

必要系統依附元件

• Google Cloud CLI
  • 按照指示安裝 Google Cloud CLI。
  • 使用 gcloud auth login 進行驗證。
• Agent Assist 整合後端部署作業
  • 按照操作說明設定整合功能。
  • 除了正常設定外，請在執行部署指令碼前，於 aa-integration-backend/.env 中設定下列環境變數：
    • AUTH_OPTION：設為 Five9。
    • FIVE9_TRUST_TOKEN：請執行下列指令來產生這個值：
      • cd platforms/five9
      • cp .env.sample .env
      • make generate-trust-token
• Agent Assist 對話設定檔：詳情請參閱「建立對話設定檔」。
• Five9 管理員存取權：這是設定 Mediastream 訂閱和傳統連接器的必要條件。
• Make：用於執行部署指令碼。

選用的系統依附元件

• Podman (選用)：用於建構容器和在本機測試。
  • Podman 安裝指南
  • Podman-Compose 安裝指南
• grpcurl (選用)：用於驗證 gRPC 串流狀況。
  • 安裝指南

整合架構總覽

這項解決方案採用分割服務架構，處理 Five9 通訊協定的不同需求：即時雙向音訊串流 (gRPC) 和非同步事件處理 (HTTP)。這兩項 Cloud Run 服務會連結 Five9 MediaStream 和 Google Cloud Agent Assist，提供即時轉錄和生成式 AI 建議：

• mediastream-grpc-service：處理來自 Five9 MediaStream 的雙向 gRPC 音訊串流。
• mediastream-http-service：顯示 Agent Assist 使用者介面模組，並處理 CTI 和 MediaStream 事件。

高階資料流程

1. 發起通話：Five9 會觸發 CTI 事件至 HTTP 服務，發起工作階段。
2. 音訊串流：Five9 會開啟與 gRPC 服務的安全 gRPC 連線，進行即時音訊交換。
3. 處理：gRPC 服務會將音訊轉送至 Google Cloud Agent Assist。
4. 建議：Agent Assist 會透過 Pub/Sub 傳回轉錄稿和服務專員輔導建議，並透過 Socket.IO (WebSocket) 連線，將這些內容轉送至 UI Connector Cloud Run 服務的 Agent Assist UI 模組。通話期間，這些建議會顯示在 Five9 Agent Desktop Plus 的 Five9 Classic Connector iframe 中。

gRPC 服務 (mediastream-grpc)

• 角色：處理高效能的即時雙向音訊串流。
• 實作：使用 grpcio 的 Python gRPC 伺服器。
• 並行：使用 grpc.aio (AsyncIO) 進行高效能的非封鎖 I/O。
• 通訊協定：使用 mediastream-grpc/proto/voice.proto 定義服務合約。
• 核心模組：VoiceServicer 實作項目會自動調度管理音訊串流處理作業和 Agent Assist API 呼叫。services/get_suggestions.py

HTTP 服務 (mediastream-http)

• 角色：處理控制層事件、權杖驗證，以及提供靜態 UI 資產。
• 實作：Flask 網路伺服器。
• 端點：
  • GET /：伺服器的健康狀態檢查端點。
  • GET /agent-assist-ui-modules：為 Five9 傳統連接器提供 Agent Assist UI 模組。
  • GET /cti-call-event-destination/：驗證 FIVE9_TRUST_TOKEN (傳回 SHA256 雜湊)。
  • POST /cti-call-event-destination/：接收通話 CTI 事件和中繼資料。
  • POST /mediastream-event-destination/subscriptions/<id>：接收媒體串流的非同步錯誤或狀態更新。

安全性

• 信任權杖：整合作業會實作共用密碼安全模式。系統會在 Five9 和 Cloud Run 服務中產生並設定 FIVE9_TRUST_TOKEN。HTTP 服務提供驗證端點 (GET /cti-call-event-destination/)，可傳回設定權杖的 SHA256 雜湊以供驗證。
• 這個信任權杖也會重複使用，做為驗證從 MediaStream HTTP 服務到 UI 連接器要求時的共用密鑰。

部署指南

以下各節說明如何部署這項 Agent Assist Five9 整合功能，並在 Five9 Agent Desktop Plus 中進行測試。

設定環境變數

1. 請先執行 cd aa-integration-backend/platforms/five9 來變更目錄。

2. 確認您有從「必要系統依附元件」部分複製的 .env 檔案。.env.sample最後一行應包含當時產生的 FIVE9_TRUST_TOKEN。

3. 環境變數：在 .env 檔案中填寫下列詳細資料。

   變數	說明
   PROJECT_ID	您的 Google Cloud 專案 ID
   REGION	要部署 Cloud Run 服務的區域。
   CONVERSATION_PROFILE_NAME	Agent Assist 對話設定檔資源 ID。
   FEATURES	啟用 Agent Assist 的功能。請參閱「UI Modules Container V2 Properties」說明文件。
   FIVE9_API_KEY	請將此值設為您在設定 MediaStream 訂閱時取得的 Five9 API 金鑰。
   FIVE9_TRUST_TOKEN	您在「事前準備」中產生的共用密鑰，可讓 mediastream-http-service 向 ui-connector Cloud Run 服務進行驗證。

部署到 Google Cloud Run

使用提供的自動化功能，將 gRPC 和 HTTP 服務部署至 Cloud Run：

make deploy

這個指令碼將：

1. 建構容器映像檔。
2. 將這些映像檔推送至 Google Container Registry (GCR) 或 Artifact Registry。
3. 部署兩個 Cloud Run 服務：一個用於 gRPC (語音)，另一個用於 HTTP (事件)。
4. 完成後輸出服務網址。

Five9 設定

部署完成後，請設定 Five9 將串流傳送至您的服務。如需詳細步驟，請參閱 Five9 MediaStream 技術指南。

初始 Five9 設定

請按照下列步驟，在 Five9 管理控制台中設定 Agent Assist 整合功能。

1. 建立新技能，例如「Agent Assist Integration」。
2. 將使用者指派給技能。
3. 為廣告活動設定 Five9 傳統連接器，並將您在上一個步驟中部署的 MediaStream Cloud Run 服務網址設為 iframe：
   • 網址：{mediastream-http-service-url}/agent-assist-ui-modules/
   • 方法：GET
   • 參數：call_id
   • 執行模式：In Browser
     • 代理程式應用程式：Use embedded tab for Web Agent
     • CTI Web Services：Current browser window
   • 觸發條件 (下一個分頁)：On Call Accepted
4. 建立 IVR 指令碼，定義透過 Five9 DNIS 號碼接聽電話時的行為。
5. 建立進站廣告活動
6. 將 IVR 指令碼與廣告活動建立關聯
7. (選用) 建立外撥廣告活動，為外撥電話啟用 Agent Assist。這項程序包括：
   • 將技能與撥出廣告活動建立關聯。
   • 複製傳統連結器，並與外送活動建立關聯。將傳統連接器副本的觸發條件變更為「On Contact Selected」。
   • 開始廣告活動。如要測試，請在 Agent Desktop Plus 中撥打外撥電話，並從下拉式選單中選取外撥廣告活動。

建立 MediaStream 訂閱項目

1. 訂閱名稱：Agent Assist Integration Media Stream
2. 串流類型：語音串流
   • 串流目的地：其他 (自助式)
   • 串流通訊協定：gRPC
   • 主要串流目的地：
     • <five9-mediastream-grpc-deployment-url-without-protocol>:443
     • 例如：five9-mediastream-grpc-123412341234.us-central1.run.app:443
   • CTI Call Event Destination:
     • https://<five9-mediastream-http-deployment-url>/cti-call-event-destination/
     • 例如：https://five9-mediastream-http-123412341234-uc.a.run.app/cti-call-event-destination/
   • Mediastream Event Destination：
     • https://<five9-mediastream-http-deployment-url>/mediastream-event-destination/
     • 例如：https://five9-mediastream-http-123412341234-uc.a.run.app/mediastream-event-destination/
   • 信任權杖：您在稍早步驟中產生的 FIVE9_TRUST_TOKEN。
   • API 金鑰：儲存 Mediastream 訂閱項目後，系統會產生這個欄位。將收到的 FIVE9_API_KEY 複製到 platforms/five9/.env。下一個步驟會用到這項資訊。
   • 串流篩選器：
     • 自訂篩選器：已勾選
     • 篩選器類型：廣告活動
     • 搜尋已加入的廣告活動：搜尋並加入廣告活動。

重新部署至 Google Cloud Run

• 重要事項：建立 MediaStream 訂閱項目後，您必須將收到的 FIVE9_API_KEY 新增至 platforms/five9/.env 檔案，然後執行 make deploy 重新部署。

部署驗證

確認您部署的服務可在 Cloud Run 上存取：

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

將 .wav 檔案串流至 mediastream-grpc-service，模擬通話：

make test-grpc-stream

現在，您可以在 Five9 Agent Desktop Plus 接聽電話時，測試 Agent Assist 的轉錄和建議功能。

本機測試 (選用)

如要進行疑難排解或測試，但不想部署服務，可以使用 Docker/Podman 在本機執行服務。停止容器，並使用 Podman Compose 在本機建構及執行。

make all

執行所有測試 (健康狀態、單元)，但串流除外

make test

透過串流 .wav 檔案模擬通話

make test-grpc-stream LOCAL=true

注意： 您也可以在 test-grpc-stream 期間查看 gRPC 語音轉錄和建議結果，方法是在 platforms/five9/mediastream-grpc-server/main.py 中將記錄層級設為偵錯。