Agent Assist 语音集成（与 Five9 集成）

此语音集成使用 Five9 Classic Connector 和 Five9 MediaStream（以前称为 Voicestream），以便在 Five9 Agent Desktop Plus 中为客服提供 Agent Assist 建议。

Agent Assist Five9 集成架构

准备工作

如需将 Agent Assist 界面模块与 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：用于运行部署脚本。

可选的系统依赖项

集成架构概览

该解决方案采用拆分服务架构来处理 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 会向 HTTP 服务触发 CTI 事件，从而启动会话。
  2. 音频流式传输：Five9 会打开与 gRPC 服务的安全 gRPC 连接，以进行实时音频交换。
  3. 处理：gRPC 服务将音频转发给 Google Cloud Agent Assist。
  4. 建议：Agent Assist 通过 Pub/Sub 返回转写和客服指导建议，这些建议通过 Socket.IO (WebSockets) 连接转发到 Agent Assist UI 模块（与 UI 连接器 Cloud Run 服务）。在通话期间，这些建议会显示在 Five9 Agent Desktop Plus 中的 Five9 Classic Connector iframe 中。

gRPC 服务 (mediastream-grpc)

  • 角色：处理高性能的实时双向音频流式传输。
  • 实现：使用 grpcio 的 Python gRPC 服务器。
  • 并发：使用 grpc.aio (AsyncIO) 实现高性能的非阻塞 I/O。
  • 协议：使用 mediastream-grpc/proto/voice.proto 定义服务合约。
  • 核心模块：services/get_suggestions.py 中的 VoiceServicer 实现可编排音频串流处理和 Agent Assist API 调用。

HTTP 服务 (mediastream-http)

  • 角色：处理控制平面事件、令牌验证和提供静态界面资源。
  • 实现：Flask Web 服务器。
  • 端点：
    • GET /：服务器的健康检查端点。
    • GET /agent-assist-ui-modules：为 Five9 经典连接器提供 Agent Assist 界面模块。
    • 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 服务到界面连接器的请求进行身份验证。

部署指南

以下部分介绍了如何在 Five9 Agent Desktop Plus 中部署此 Agent Assist Five9 集成并对其进行测试。

配置环境变量

  1. 首先，运行 cd aa-integration-backend/platforms/five9 以更改目录。

  2. 检查您是否拥有从必需的系统依赖项部分中的 .env.sample 复制的 .env 文件。最后一行应包含您当时生成的 FIVE9_TRUST_TOKEN。

  3. 环境变量：在 .env 文件中填写以下详细信息。

    变量 说明
    PROJECT_ID 您的 Google Cloud 项目 ID
    REGION Cloud Run 服务将部署到的区域。
    CONVERSATION_PROFILE_NAME Agent Assist 对话配置文件资源 ID。
    FEATURES 要为 Agent Assist 启用的功能。请参阅 界面模块容器 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。
  3. 部署两个 Cloud Run 服务：一个用于 gRPC（语音），一个用于 HTTP（活动）。
  4. 在完成时输出服务网址。

Five9 配置

部署完成后，配置 Five9 以将数据流发送到您的服务。如需了解详细步骤，请参阅 Five9 MediaStream 技术指南。

初始 Five9 配置

请按照以下步骤配置 Five9 管理控制台，以实现 Agent Assist 集成。

  1. 创建新技能，例如 Agent Assist 集成。
  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 服务：Current browser window
    • 触发器（下一个标签页）：On Call Accepted
  4. 创建 IVR 脚本，以定义通过 Five9 DNIS 号码接听电话时的行为。
  5. 制作集客营销活动
  6. 将 IVR 脚本与广告系列相关联
  7. （可选）创建外拨广告系列，以便为外拨电话启用 Agent Assist。这涉及以下方面：
    • 将技能与外拨广告系列相关联。
    • 创建经典版连接器的副本，并将其与出站广告系列相关联。将经典连接器复制的触发条件更改为 On Contact Selected。
    • 开始广告系列。如需进行测试，请在 Agent Desktop Plus 中拨打一个外呼电话，然后从下拉菜单中选择外呼广告系列。

经典连接器的配置示例，用于支持 Agent Desktop Plus 中的界面模块

创建 MediaStream 订阅

  1. 订阅名称：Agent Assist 集成媒体流
  2. Streaming Type: Voice streaming
    • 流式传输目的地：其他（自助服务）
    • 流式传输协议：gRPC
    • 主要流式传输目的地：
      • <five9-mediastream-grpc-deployment-url-without-protocol>:443
      • 例如：five9-mediastream-grpc-123412341234.us-central1.run.app:443
    • CTI 通话事件目标：
      • https://<five9-mediastream-http-deployment-url>/cti-call-event-destination/
      • 例如：https://five9-mediastream-http-123412341234-uc.a.run.app/cti-call-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 密钥：此字段将在您保存 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 转写和建议功能。

成功完成 Agent Assist 集成端到端测试的示例

本地测试（可选）

如需在不进行部署的情况下进行问题排查或测试，您可以使用 Docker/Podman 在本地运行服务。使用 Podman Compose 在本地停止容器、构建和运行容器。

make all

运行除流式传输测试以外的所有测试（健康状况、单元）

make test

通过流式传输 .wav 文件来模拟通话

make test-grpc-stream LOCAL=true