Agent Assist と Five9 の音声統合

この音声統合では、Five9 Classic Connector と Five9 MediaStream（以前は Voicestream と呼ばれていました） を使用して、Five9 Agent Desktop Plus のエージェントに Agent Assist の提案を提供します。

Agent Assist と Five9 の統合のアーキテクチャ

始める前に

Agent Assist UI モジュールを Five9 と統合するには、次のリソースにアクセスする必要があります。

必要なシステムの依存関係

省略可能なシステムの依存関係

統合アーキテクチャの概要

このソリューションでは、分割サービス アーキテクチャを使用して、Five9 のプロトコルの個別の要件（リアルタイムの双方向音声ストリーミング（gRPC）と非同期イベント処理（HTTP））を処理します。これら 2 つの Cloud Run サービスは、Five9 MediaStream と Google Cloud Agent Assist を橋渡しし、リアルタイムの文字起こしと生成 AI の提案を可能にします。

  • mediastream-grpc-service: Five9 MediaStream からの双方向 gRPC 音声ストリームを処理します。
  • mediastream-http-service: Agent Assist UI モジュールを表示し、CTI イベントと MediaStream イベントを処理します。

大まかなデータフロー

  1. 通話の開始: Five9 は CTI イベントを HTTP サービス にトリガーし、セッションを開始します。
  2. 音声ストリーミング: Five9 は、リアルタイムの音声交換のために gRPC サービス への安全な gRPC 接続を開きます。
  3. 処理: gRPC サービスは音声を Google Cloud Agent Assist に転送します。
  4. 提案: Agent Assist は、Pub/Sub を介して文字起こしとエージェント コーチングの提案を返します。これは、UI Connector Cloud Run サービスとの Socket.IO（WebSockets）接続を介して Agent Assist UI モジュール に転送されます。これらの提案は、通話中に Five9 Agent Desktop Plus の Five9 Classic Connector iframe にレンダリングされます。

gRPC サービス（mediastream-grpc）

  • ロール: 高性能なリアルタイム双方向音声ストリーミングを処理します。
  • 実装: grpcio を使用する Python gRPC サーバー。
  • 同時実行: 高性能なノンブロッキング I/O に grpc.aio（AsyncIO）を使用します。
  • プロトコル: mediastream-grpc/proto/voice.proto を使用してサービス コントラクトを定義します。
  • コアモジュール: VoiceServicer の services/get_suggestions.py 実装は、音声ストリーム処理と Agent Assist API 呼び出しを調整します。

HTTP サービス（mediastream-http）

  • ロール: コントロール プレーン イベント、トークン検証、静的 UI アセットの提供を処理します。
  • 実装: Flask ウェブサーバー。
  • エンドポイント:
    • GET /: サーバーのヘルスチェック エンドポイント。
    • GET /agent-assist-ui-modules: Five9 Classic Connector の 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_TRUST_TOKEN は、Five9 と Cloud Run サービスの両方で生成および構成されます。HTTP サービスは、検証用の構成済みトークンの SHA256 ハッシュを返す検証エンドポイント（GET /cti-call-event-destination/）を提供します。
  • この信頼トークンは、MediaStream HTTP サービスから UI Connector へのリクエストを認証する共有シークレットとしても再利用されます。

デプロイガイド

以降のセクションでは、この Agent Assist Five9 統合をデプロイし、Five9 Agent Desktop Plus でテストする方法について説明します。

環境変数を構成する

  1. まず、cd aa-integration-backend/platforms/five9 を実行してディレクトリを変更します。

  2. 必要なシステムの依存関係セクションで .env.sample からコピーした .env ファイルがあることを確認します。最後の行には、そのときに生成した FIVE9_TRUST_TOKEN が含まれている必要があります。

  3. 環境変数: .env ファイルに次の詳細を入力します。

    変数 説明
    PROJECT_ID プロジェクト ID Google Cloud
    REGION Cloud Run サービスがデプロイされるリージョン。
    CONVERSATION_PROFILE_NAME Agent Assist 会話プロファイルのリソース ID。
    FEATURES Agent Assist で有効にする機能。UI モジュール コンテナ V2 のプロパティのドキュメントをご覧ください。
    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 に push します。
  3. 2 つの Cloud Run サービスをデプロイします。1 つは gRPC（音声用）、もう 1 つは HTTP（イベント用）です。
  4. 完了時にサービス URL を出力します。

Five9 の構成

デプロイ後、サービスにストリームを送信するように Five9 を構成します。詳細な手順については、Five9 MediaStream 技術ガイドをご覧ください。

Five9 の初期構成

次の手順に沿って、Agent Assist 統合用に Five9 管理コンソールを構成します。

  1. 新しいスキルを作成します（例: Agent Assist Integration）。
  2. ユーザーをスキルに割り当てます。
  3. 前のステップでデプロイした MediaStream Cloud Run サービス URL を iframe に設定して、キャンペーン用の Five9 Classic Connector を構成します:
    • URL: {mediastream-http-service-url}/agent-assist-ui-modules/
    • Method: GET
    • Parameters: call_id
    • Execution Mode: In Browser
      • Agent Application: 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 を有効にします。これには次の操作が含まれます。
    • スキルをアウトバウンド キャンペーンに関連付けます。
    • Classic Connector のコピーを作成し、アウトバウンド キャンペーンに関連付けます。Classic Connector コピーのトリガーを [On Contact Selected] に変更します。
    • キャンペーンを開始します。テストするには、Agent Desktop Plus でアウトバウンド通話を発信し、プルダウンからアウトバウンド キャンペーンを選択します。

Agent Desktop Plus で UI モジュールをサポートするためのクラシック コネクタの構成例

MediaStream サブスクリプションを作成する

  1. Subscription Name: Agent Assist Integration Media Stream
  2. Streaming Type: 音声ストリーミング
    • Streaming Destination: Other (Self-Service)
    • Streaming Protocol: gRPC
    • Primary Streaming Destination:
      • <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/
    • Trust Token: 前のステップで生成した FIVE9_TRUST_TOKEN。
    • API Key: このフィールドは、Mediastream サブスクリプションを保存した後に生成されます。受け取った FIVE9_API_KEY を platforms/five9/.env にコピーします。これは次のステップで必要になります。
    • Streaming Filter:
      • Custom filter: チェック済み
      • Filter Type: Campaigns
      • Search added campaigns: キャンペーンを検索して追加します。

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 の文字起こしと提案をテストする準備ができました。

Agent Assist 統合のエンドツーエンド テストが成功した例

ローカル テスト（省略可）

トラブルシューティングやデプロイなしでのテストの場合は、Docker/Podman を使用してサービスをローカルで実行できます。コンテナを停止し、Podman Compose でローカルでビルドして実行します。

make all

ストリームを除くすべてのテスト（ヘルス、ユニット）を実行する

make test

.wav ファイルをストリーミングして通話をシミュレートする

make test-grpc-stream LOCAL=true