이 음성 통합은 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/five9cp .env.sample .envmake generate-trust-token
- Agent Assist 대화 프로필: 자세한 내용은 대화 프로필 만들기를 참고하세요.
- Five9 관리자 액세스: Mediastream 구독 및 Classic Connector를 구성하는 데 필요합니다.
- Make: 배포 스크립트를 실행하는 데 사용됩니다.
선택적 시스템 종속 항목
- Podman (선택사항): 컨테이너 빌드 및 로컬 테스트에 사용됩니다.
- 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 UI 모듈을 표시하고 CTI 및 MediaStream 이벤트를 처리합니다.
개괄적인 데이터 흐름
- 통화 시작: Five9는 HTTP 서비스에 CTI 이벤트를 트리거하여 세션을 시작합니다.
- 오디오 스트리밍: Five9는 실시간 오디오 교환을 위해 gRPC 서비스에 보안 gRPC 연결을 엽니다.
- 처리: gRPC 서비스는 오디오를 Google Cloud Agent Assist로 전달합니다.
- 제안: Agent Assist는 Pub/Sub를 통해 텍스트 변환 및 상담사 코칭 제안을 반환하며, 이는 UI 커넥터 Cloud Run 서비스와의 Socket.IO (WebSockets) 연결을 통해 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구현은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 커넥터로의 요청을 인증하는 공유 비밀번호로도 재사용됩니다.
배포 가이드
다음 섹션에서는 이 Agent Assist Five9 통합을 배포하고 Five9 Agent Desktop Plus에서 테스트하는 방법을 설명합니다.
환경 변수 구성
- 먼저
cd aa-integration-backend/platforms/five9를 실행하여 디렉터리를 변경합니다. 필수 시스템 종속 항목 섹션의
.env.sample에서 복사한.env파일이 있는지 확인합니다. 마지막 줄에는 당시 생성한FIVE9_TRUST_TOKEN이 포함되어야 합니다.환경 변수: 다음 세부정보로
.env파일을 채웁니다.변수 설명 PROJECT_ID프로젝트 ID Google Cloud REGIONCloud Run 서비스가 배포될 리전입니다. CONVERSATION_PROFILE_NAMEAgent Assist 대화 프로필 리소스 ID입니다. FEATURESAgent Assist에 사용 설정할 기능입니다. UI 모듈 컨테이너 V2 속성 문서를 참고하세요. FIVE9_API_KEYMediaStream 구독을 설정할 때 받은 Five9 API 키로 설정합니다. FIVE9_TRUST_TOKEN시작하기 전에 생성한 공유 비밀번호로, mediastream-http-service가ui-connectorCloud Run 서비스로 인증할 수 있도록 합니다.
Google Cloud Run에 배포
제공된 자동화를 사용하여 gRPC 및 HTTP 서비스를 모두 Cloud Run에 배포합니다.
make deploy
이 스크립트는 다음을 수행합니다.
- 컨테이너 이미지를 빌드합니다.
- Google Container Registry (GCR) 또는 Artifact Registry로 푸시합니다.
- 두 개의 Cloud Run 서비스를 배포합니다. 하나는 gRPC (음성)용이고 다른 하나는 HTTP (이벤트)용입니다.
- 완료 시 서비스 URL을 출력합니다.
Five9 구성
배포 후 Five9를 구성하여 스트림을 서비스로 전송합니다. 자세한 단계는 Five9 MediaStream 기술 가이드를 참고하세요.
초기 Five9 구성
다음 단계에 따라 Agent Assist 통합을 위해 Five9 관리 콘솔을 구성합니다.
- 새로운 기능(예: Agent Assist 통합)을 만듭니다.
- 사용자를 기능에 할당합니다.
- 이전 단계에서 배포한 MediaStream Cloud Run 서비스 URL을 iframe으로 처리하여 캠페인용 Five9 Classic Connector를 구성합니다.
- URL:
{mediastream-http-service-url}/agent-assist-ui-modules/ - 메서드:
GET - 매개변수:
call_id - 실행 모드:
In Browser- 상담사 애플리케이션:
Use embedded tab for Web Agent - CTI 웹 서비스:
Current browser window
- 상담사 애플리케이션:
- 트리거 (다음 탭):
On Call Accepted
- URL:
- IVR 스크립트를 만들어 Five9 DNIS 번호를 통해 통화를 수신할 때의 동작을 정의합니다.
- 인바운드 캠페인을 만듭니다.
- IVR 스크립트를 캠페인과 연결합니다.
- 선택적으로 아웃바운드 캠페인을 만들어 아웃바운드 통화에 Agent Assist를 사용 설정합니다. 여기에는 다음이 포함됩니다.
- 기술을 아웃바운드 캠페인과 연결합니다.
- Classic Connector의 사본을 만들고 아웃바운드 캠페인과 연결합니다. Classic Connector 사본의 트리거를 연락처 선택 시 로 변경합니다.
- 캠페인을 시작합니다. 테스트하려면 Agent Desktop Plus에서 아웃바운드 통화를 걸고 드롭다운에서 아웃바운드 캠페인을 선택합니다.
MediaStream 구독 만들기
- 구독 이름: Agent Assist 통합 미디어 스트림
- 스트리밍 유형: 음성 스트리밍
- 스트리밍 대상: 기타 (셀프서비스)
- 스트리밍 프로토콜: 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/
- Mediastream 이벤트 대상:
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