Intégrer des modules backend à votre système

Les modules backend sont une solution prête à l'emploi qui fournit une infrastructure backend efficace pour traiter de grands volumes de messages liés aux fonctionnalités et interagir avec l'interface utilisateur de bureau de l'agent. Ce tutoriel vous explique comment intégrer des modules backend à votre système d'agents.

Pour en savoir plus sur les concepts et la structure des modules en arrière-plan, consultez la documentation sur les principes de base des modules backend.

Prérequis

Configurer des variables d'environnement

Pour simplifier les commandes de déploiement, nous vous recommandons de définir les variables d'environnement utiles suivantes dans votre shell. Vous pouvez définir les variables à l'aide de l'exemple de commande suivant:

$ export GCP_PROJECT_ID='enter_project_id_here' \
&& export SERVICE_REGION='us-central1'

Définissez les variables d'environnement suivantes :

  • GCP_PROJECT_ID: ID de votre projet Cloud Platform qui héberge les ressources associées. Exemple : my-project.
  • SERVICE_REGION: emplacement ou région de vos services et des ressources Cloud Platform associées. Exemple : us-central1.

Configurer un compte administrateur

Nous vous recommandons d'utiliser des comptes Google Cloud distincts pour l'administration des services et l'identité d'exécution. L'administration des services est principalement effectuée par des humains disposant de comptes Google, tandis que l'identité d'exécution accorde des autorisations aux services Cloud Run à l'aide de comptes de service pour permettre l'accès aux ressources nécessaires.

Préparer le compte administrateur humain

Si vous prévoyez d'utiliser un compte disposant déjà des autorisations Éditeur ou Propriétaire dans votre projet, vous pouvez passer à la section suivante.

Pour gérer l'infrastructure backend, créez un compte administrateur et attribuez-lui les rôles IAM suivants. Leurs autorisations sont toutes incluses dans les rôles de base Éditeur (roles/editor) et Propriétaire (roles/owner).

  • roles/secretmanager.admin (administrateur Secret Manager): permet de gérer les secrets stockés dans Secret Manager pour la génération et la validation des jetons JWT.
  • roles/run.admin (administrateur Cloud Run): permet de déployer et de gérer les services Cloud Run.
  • roles/iam.serviceAccountUser (Utilisateur du compte de service): accordez des autorisations iam.serviceAccounts.actAs aux comptes de service d'exécution Cloud Run.
  • roles/cloudbuild.builds.editor (Éditeur Cloud Build): créez des images Docker pour les services d'intégration à l'aide de Cloud Build.
  • Administrateur Artifact Registry: stocke et gère les images Docker compilées pour les services d'intégration.
  • roles/pubsub.editor (Éditeur Cloud Pub/Sub): créez et gérez des sujets et des abonnements Cloud Pub/Sub.
  • roles/redis.admin (administrateur Redis): créez et gérez les ressources Memorystore pour Redis.

Pour attribuer des rôles IAM à un compte utilisateur, utilisez la commande Google Cloud CLI add-iam-policy-binding. Voici un exemple de commande:

$ gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \
 --member='user:test-user@gmail.com' \
 --role='roles/pubsub.editor'

Définir le compte administrateur humain dans gcloud

Remplacez $ADMIN_ACCOUNT par le compte administrateur que vous souhaitez utiliser (par exemple, myaccount@gmail.com) dans l'exemple suivant :

$ gcloud config set account $ADMIN_ACCOUNT

Configurer des comptes de service

Par défaut, les services ou jobs Cloud Run s'exécutent en tant que compte de service Compute Engine par défaut. Plutôt que de laisser l'identité par défaut, nous vous recommandons d'attribuer une identité dédiée à chaque service Cloud Run en lui attribuant un compte de service géré par l'utilisateur avec l'ensemble minimal d'autorisations requis. Si vous prévoyez de conserver le compte de service par défaut, vous pouvez passer directement à la section Définir des variables d'environnement.

Créer deux comptes de service pour chaque environnement d'exécution Cloud Run

  1. Pour créer les comptes de service, remplacez la valeur de $CONNECTOR_SERVICE_ACCOUNT_ID et $INTERCEPTOR_SERVICE_ACCOUNT_ID si nécessaire, puis exécutez les commandes suivantes:

    $ export CONNECTOR_SERVICE_ACCOUNT_ID='aa-ui-connector' && gcloud iam service-accounts create $CONNECTOR_SERVICE_ACCOUNT_ID 
    --description='Agent Assist integration - UI connector service account'
    --display-name='Agent Assist integration - UI connector'

    $ export INTERCEPTOR_SERVICE_ACCOUNT_ID='aa-pubsub-interceptor' && gcloud iam service-accounts create $INTERCEPTOR_SERVICE_ACCOUNT_ID
    --description='Agent Assist integration - Pubsub interceptor service account'
    --display-name='Agent Assist integration - Pubsub interceptor'

  2. Utilisez l'exemple de commande suivant pour attribuer les rôles suivants aux comptes de service du connecteur d'interface utilisateur et du connecteur Cloud Pub/Sub:

    $ gcloud projects add-iam-policy-binding $GCP_PROJECT_ID 
    --member='serviceAccount:$CONNECTOR_SERVICE_ACCOUNT_ID@$GCP_PROJECT_ID.iam.gserviceaccount.com'
    --role='roles/pubsub.editor'

Attribuez les rôles IAM suivants au compte de service du connecteur d'interface utilisateur:

  • roles/redis.editor
  • roles/vpcaccess.user
  • roles/compute.viewer
  • roles/secretmanager.secretAccessor
  • roles/dialogflow.agentAssistClient

Attribuez les rôles suivants au compte de service du connecteur Cloud Pub/Sub:

  • roles/redis.editor
  • roles/vpcaccess.user
  • roles/compute.viewer

Définir des variables d'environnement

Définissez les valeurs des variables d'environnement suivantes sur les comptes de service que vous venez de créer ou sur le compte de service Compute Engine par défaut de votre projet.

  1. CONNECTOR_SERVICE_ACCOUNT: compte de service pour l'environnement d'exécution du connecteur d'interface utilisateur. Exemple : aa-ui-connector@my-project-id.iam.gserviceaccount.com.
  2. INTERCEPTOR_SERVICE_ACCOUNT: compte de service pour l'environnement d'exécution de l'intercepteur Cloud Pub/Sub. Exemple : aa-pubsub-interceptor@my-project-id.iam.gserviceaccount.com.

Personnaliser la méthode d'authentification des utilisateurs

Le dépôt de code est compatible avec les utilisateurs du backend et ceux du module d'interface pour Genesys Cloud et Twilio.

  1. Dans le dépôt de code, ouvrez le fichier ui_connector/auth.py.
  2. Spécifiez le fournisseur d'identité compatible en définissant la variable d'environnement AUTH_OPTION ou implémentez votre méthode d'authentification avec auth.check_auth.

    Par défaut, AUTH_OPTION est vide et aucun utilisateur n'est autorisé à enregistrer un jeton JWT auprès du service UI Connector. Valeurs autorisées :

    • "Salesforce": vérifiez le jeton d'autorisation à l'aide de Salesforce OpenID Connect. Variable d'environnement requise: SALESFORCE_ORGANIZATION_ID.
    • 'GenesysCloud': vérifiez le jeton d'autorisation à l'aide de l'API Users du SDK Genesys.
    • "Twilio": vérifiez le jeton d'authentification pour Twilio. Variable d'environnement requise: TWILIO_FLEX_ENVIRONMENT.

    Exemple :

    $ export AUTH_OPTION='Salesforce'

    Chaque type de jeton peut avoir un mode de validation différent. C'est vous qui décidez de la manière dont le jeton est validé. Sans modification, auth.check_auth renvoie false pour chaque requête.

Générer et stocker une clé secrète JWT

Pour que le service de connecteur d'interface utilisateur renvoie des jetons d'authentification sécurisés au client, il doit les chiffrer à l'aide d'une clé secrète JWT. La valeur de la clé peut être n'importe quelle chaîne arbitraire, mais elle doit être unique et difficile à deviner.

Cette clé secrète sera stockée dans Secret Manager.

Définir une variable d'environnement

  • JWT_SECRET_NAME: nom de la clé secrète dans Secret Manager. Il peut s'agir de n'importe quel nom arbitraire. Valeur recommandée: aa-integration-jwt-secret.

Générer la clé

Nous vous recommandons de générer un hachage aléatoire comme clé secrète JWT afin qu'il ne puisse pas être deviné par des pirates informatiques. Pour ce faire, vous pouvez utiliser des secrets Python pour générer des nombres aléatoires sécurisés.

Stocker la clé dans Secret Manager

Dans l'exemple de commande suivant, remplacez my_key par la clé secrète que vous prévoyez d'utiliser.

printf "my_key" | gcloud secrets create $JWT_SECRET_NAME --data-file=- --replication-policy=user-managed --locations=$SERVICE_REGION

Configurer Memorystore pour Redis

Pour configurer Redis, vous avez besoin des variables d'environnement suivantes:

  • VPC_CONNECTOR_NAME: nom de votre connecteur d'accès au VPC sans serveur pour connecter les services Cloud Run à Memorystore pour Redis. Valeur recommandée: aa-integration-vpc.
  • VPC_NETWORK: réseau VPC auquel associer le connecteur d'accès au VPC sans serveur. La valeur doit être default si vous ne configurez pas de VPC pour votre Google Cloud projet.
  • REDIS_IP_RANGE: réseau IP interne non réservé pour votre connecteur d'accès au VPC sans serveur. Un espace non attribué de /28 est requis. Valeur recommandée : 10.8.0.0/28 (cette valeur devrait fonctionner pour la plupart des nouveaux projets).
  • REDIS_INSTANCE_ID: nom de votre instance Redis. Valeur recommandée : aa-integration-redis.

Créer une instance Redis dans la région de vos services Cloud Run

Exécutez la commande suivante :

$ gcloud redis instances create $REDIS_INSTANCE_ID --size=5 --region=$SERVICE_REGION

Créez un connecteur d'accès au VPC sans serveur.

Assurez-vous que l'API Serverless VPC Access est activée pour votre projet:

$ gcloud services enable vpcaccess.googleapis.com

Créez un connecteur d'accès au VPC sans serveur avec une plage d'adresses IP personnalisée:

$ gcloud compute networks vpc-access connectors create $VPC_CONNECTOR_NAME \
  --network $VPC_NETWORK \
  --region $SERVICE_REGION \
  --range $REDIS_IP_RANGE

Enregistrer l'hôte et le port Redis en tant que variables d'environnement

  • Définissez l'adresse IP de votre instance Redis sur la variable d'environnement REDIS_HOST.
  • Définissez le numéro de port de votre instance Redis sur la variable d'environnement REDIS_PORT.

Déployer le service de connecteur d'interface utilisateur

Pour le service de connecteur d'interface utilisateur, vous avez besoin des variables d'environnement suivantes:

  • CONNECTOR_SERVICE_NAME: nom du service Cloud Run de votre connecteur d'interface utilisateur. Valeur recommandée: ui-connector.
  • CONNECTOR_IMAGE_NAME: nom de l'image de votre service de connecteur d'interface utilisateur. Il peut être identique à CONNECTOR_SERVICE_NAME. Valeur recommandée: ui-connector.

Compiler l'image Docker

Dans le dossier /ui-connector, exécutez la commande suivante:

$ gcloud builds submit --tag gcr.io/$GCP_PROJECT_ID/$CONNECTOR_IMAGE_NAME

Déployer le connecteur d'interface utilisateur dans Cloud Run

Dans le dossier /ui-connector, exécutez la commande suivante. Notez l'URL du service du connecteur d'interface utilisateur déployé, qui sera utilisée par les clients (ordinateurs de bureau des agents).

$ gcloud run deploy $CONNECTOR_SERVICE_NAME \
--image gcr.io/$GCP_PROJECT_ID/$CONNECTOR_IMAGE_NAME \
--platform managed \
--service-account=$CONNECTOR_SERVICE_ACCOUNT \
--allow-unauthenticated \
--timeout 3600 \
--region $SERVICE_REGION \
--vpc-connector $VPC_CONNECTOR_NAME \
--set-env-vars REDISHOST=$REDIS_HOST,REDISPORT=$REDIS_PORT,GCP_PROJECT_ID=$GCP_PROJECT_ID \
--update-secrets=/secret/jwt_secret_key=${JWT_SECRET_NAME}:latest

Déployer le service d'intercepteur Cloud Pub/Sub

Pour le service d'intercepteur Pub/Sub, vous avez besoin des variables d'environnement suivantes:

  • INTERCEPTOR_SERVICE_NAME: nom du service Cloud Run de votre intercepteur Cloud Pub/Sub. Valeur recommandée: cloud-pubsub-interceptor.
  • INTERCEPTOR_IMAGE_NAME: nom de l'image de votre service d'intercepteur Cloud Pub/Sub. Il peut être identique à INTERCEPTOR_SERVICE_NAME. Valeur recommandée: cloud-pubsub-interceptor.

Compiler l'image Docker

Dans le dossier /cloud-pubsub-interceptor, exécutez la commande suivante:

$ gcloud builds submit --tag gcr.io/$GCP_PROJECT_ID/$INTERCEPTOR_IMAGE_NAME

Déployer un intercepteur Pub/Sub dans Cloud Run

Dans le dossier /cloud-pubsub-interceptor, exécutez la commande suivante:

$ gcloud run deploy $INTERCEPTOR_SERVICE_NAME \
--image gcr.io/$GCP_PROJECT_ID/$INTERCEPTOR_IMAGE_NAME \
--platform managed \
--service-account=$INTERCEPTOR_SERVICE_ACCOUNT_NAME \
--region $SERVICE_REGION \
--vpc-connector $VPC_CONNECTOR_NAME \
--ingress=internal \
# You can also add LOGGING_FILE here to specify the logging file path on Cloud Run. 
--set-env-vars REDISHOST=$REDIS_HOST,REDISPORT=$REDIS_PORT

Enregistrer l'URL déployée

Définissez l'URL déployée comme variable d'environnement INTERCEPTOR_SERVICE_URL.

Configurer des abonnements Cloud Pub/Sub

Les abonnements Cloud Pub/Sub utilisent les éléments suivants:

  • Thèmes
  • Profil de conversation
  • Compte de service
  • Autorisation du compte de service pour le service d'intercepteur
  • Événements de cycle de vie des conversations

Créer des sujets Cloud Pub/Sub

Créez un sujet Cloud Pub/Sub pour chaque type de notification d'événement dont vous avez besoin de la part de Dialogflow. Les types de notifications d'événements disponibles sont les suivants:

  • Événements de nouvelle suggestion: événements envoyés lorsque de nouvelles suggestions Agent Assist sont disponibles (par exemple, de nouvelles suggestions de réponse intelligente en réponse à une déclaration du client).
  • Événements de nouveau message: événements envoyés chaque fois qu'une nouvelle expression est reconnue par un agent ou un client (par exemple, le client dit Hi).
  • Nouveaux événements du cycle de vie des conversations: événements envoyés pour certains changements du cycle de vie des conversations (par exemple, au début ou à la fin d'une conversation).
  • Nouveaux événements de notification de résultats de reconnaissance: événements envoyés lorsqu'une transcription intermédiaire est reconnue à partir d'un agent ou d'un client (par exemple, le client dit Hi, how can I help you?, une transcription intermédiaire est Hi how can pendant que le client parle).

Notez l'ID et le nom du thème pour le déploiement du backend ultérieur.

Configurer un profil de conversation

Configurez un profil de conversation avec les sujets Cloud Pub/Sub que vous avez créés à l'étape précédente.

  • Lorsque vous créez un profil de conversation, sélectionnez Notifications Pub/Sub, puis Activer les notifications Pub/Sub. Une fois l'option activée, vous pouvez cocher les cases à côté des types de notifications que vous souhaitez activer et saisir l'ID du sujet Cloud Pub/Sub associé à la notification.
  • Sélectionnez JSON comme format de message pour chaque sujet.

Créer un compte de service pour l'identité de l'abonnement Pub/Sub

Créez un compte de service représentant l'identité de l'abonnement Pub/Sub à l'aide de la commande suivante:

$ gcloud iam service-accounts create cloud-run-pubsub-invoker \
     --display-name "Cloud Run Pub/Sub Invoker"

Autorisez le compte de service à appeler votre service d'intercepteur

Exécutez la commande suivante :

$ gcloud run services add-iam-policy-binding $INTERCEPTOR_SERVICE_NAME \ 
  --member=serviceAccount:cloud-run-pubsub-invoker@$GCP_PROJECT_ID.iam.gserviceaccount.com \
   --role=roles/run.invoker

Créer des abonnements Cloud Pub/Sub pour des sujets

Pour chaque sujet que vous avez créé, vous devez créer un abonnement Cloud Pub/Sub correspondant.

Événements de nouvelle suggestion

Remplacez your-new-suggestion-topic-id par le sujet Cloud Pub/Sub que vous avez configuré pour les nouvelles suggestions:

$ export TOPIC_ID='your-new-suggestion-topic-id' && gcloud pubsub subscriptions create $SUBSCRIPTION_NAME --topic $TOPIC_ID \
   --push-endpoint=$INTERCEPTOR_SERVICE_URL/human-agent-assistant-event \
   --push-auth-service-account=cloud-run-pubsub-invoker@$GCP_PROJECT_ID.iam.gserviceaccount.com

Événements de nouveaux messages

Remplacez your-new-message-event-topic-id par le sujet Cloud Pub/Sub que vous avez configuré pour les nouveaux événements de message:

$ export TOPIC_ID='your-new-message-event-topic-id' && gcloud pubsub subscriptions create $SUBSCRIPTION_NAME --topic $TOPIC_ID \
   --push-endpoint=$INTERCEPTOR_SERVICE_URL/new-message-event \
   --push-auth-service-account=cloud-run-pubsub-invoker@$GCP_PROJECT_ID.iam.gserviceaccount.com

Événements de cycle de vie des conversations

Remplacez your-conversation-lifecycle-event-topic par le sujet Cloud Pub/Sub que vous avez configuré pour les nouveaux événements de cycle de vie de la conversation:

$ export TOPIC_ID='your-conversation-lifecycle-event-topic' && gcloud pubsub subscriptions create $SUBSCRIPTION_NAME --topic $TOPIC_ID \
   --push-endpoint=$INTERCEPTOR_SERVICE_URL/conversation-lifecycle-event \
   --push-auth-service-account=cloud-run-pubsub-invoker@$GCP_PROJECT_ID.iam.gserviceaccount.com

Nouveaux événements de notification des résultats de reconnaissance

$ export TOPIC_ID='your-new-recognition-result-notification-event-topic' && gcloud pubsub subscriptions create $SUBSCRIPTION_NAME --topic $TOPIC_ID \
   --push-endpoint=$INTERCEPTOR_SERVICE_URL/new-recognition-result-notification-event \
   --push-auth-service-account=cloud-run-pubsub-invoker@$GCP_PROJECT_ID.iam.gserviceaccount.com