Questa pagina è stata tradotta dall'API Cloud Translation.

Integrare i moduli di backend con il sistema

I moduli di backend sono una soluzione pronta all'uso che fornisce un'infrastruttura di backend efficace per elaborare grandi volumi di messaggi correlati alle funzionalità e interagire con l'interfaccia utente desktop dell'agente. Questo tutorial illustra la procedura di integrazione dei moduli di backend con il sistema dell'agente.

Per ulteriori informazioni sui concetti e sulla struttura dei moduli in background, consulta la documentazione relativa alle nozioni di base sui moduli di backend.

Prerequisiti

Installa Google Cloud CLI se non l'hai ancora configurato.

Imposta le variabili di ambiente

Per semplificare i comandi di deployment, ti consigliamo di impostare le seguenti variabili di ambiente utili nella shell. Puoi impostare le variabili utilizzando il seguente comando di esempio:

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

Imposta le seguenti variabili di ambiente:

GCP_PROJECT_ID: l'ID del tuo progetto piattaforma Cloud che ospita le risorse correlate. Esempio: my-project.
SERVICE_REGION: la località o la regione dei tuoi servizi e delle risorse della piattaforma Cloud correlate. Esempio: us-central1.

Configurare un account amministrativo

Ti consigliamo di utilizzare account Google Cloud separati per l'amministrazione del servizio e l'identità di runtime. L'amministrazione dei servizi viene eseguita principalmente da persone con account Google, mentre l'identità di runtime concede le autorizzazioni ai servizi Cloud Run utilizzando gli account di servizio per consentire l'accesso alle risorse necessarie.

Prepara l'account amministrativo dell'utente

Se prevedi di utilizzare un account che dispone già delle autorizzazioni Editor o Proprietario nel tuo progetto, puoi andare alla sezione successiva.

Per gestire l'infrastruttura di backend, crea un account amministratore e concessi i seguenti ruoli IAM. Le relative autorizzazioni sono incluse nei ruoli di base Editor (roles/editor) e Proprietario (roles/owner).

roles/secretmanager.admin (Amministratore Secret Manager): gestisci i secret archiviati in Secret Manager per la generazione e la verifica dei JWT.
roles/run.admin (Amministratore di Cloud Run): esegui il deployment e gestisci i servizi Cloud Run.
roles/iam.serviceAccountUser (utente account di servizio): concedi le autorizzazioni iam.serviceAccounts.actAs agli account di servizio di runtime Cloud Run.
roles/cloudbuild.builds.editor (Editor Cloud Build): crea immagini Docker per i servizi di integrazione utilizzando Cloud Build.
Amministratore di Artifact Registry: archivia e gestisci le immagini Docker create per i servizi di integrazione.
roles/pubsub.editor (editor Cloud Pub/Sub): crea e gestisci argomenti e sottoscrizioni Cloud Pub/Sub.
roles/redis.admin (Redis Admin): crea e gestisci le risorse di Memorystore for Redis.

Per concedere i ruoli IAM a un account utente, utilizza il comando add-iam-policy-binding Google Cloud CLI. Di seguito è riportato un esempio di comando:

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

Impostare l'account amministrativo dell'utente in gcloud

Sostituisci $ADMIN_ACCOUNT con l'account amministratore che vuoi utilizzare (ad esempio: myaccount@gmail.com) nel seguente esempio:

$ gcloud config set account $ADMIN_ACCOUNT

Configurare gli account di servizio

Per impostazione predefinita, i servizi o i job Cloud Run vengono eseguiti come account di servizio Compute Engine predefinito. Anziché lasciare quello predefinito, ti consigliamo di assegnare a ogni servizio Cloud Run un'identità dedicata assegnandogli un account di servizio gestito dall'utente con l'insieme minimo di autorizzazioni richieste. Se prevedi di mantenere l'account di servizio predefinito, puoi andare avanti e impostare le variabili di ambiente.

Crea due account di servizio per ogni runtime Cloud Run

Per creare gli account di servizio, sostituisci il valore di $CONNECTOR_SERVICE_ACCOUNT_ID e $INTERCEPTOR_SERVICE_ACCOUNT_ID se ed esegui i seguenti comandi:

$ 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'

Utilizza il seguente comando di esempio per assegnare i seguenti ruoli agli account di servizio del connettore UI e del connettore 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'

Concedi i seguenti ruoli IAM all'account di servizio del connettore dell'interfaccia utente:

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

Concedi i seguenti ruoli all'account di servizio del connettore Cloud Pub/Sub:

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

Imposta le variabili di ambiente

Imposta i valori delle seguenti variabili di ambiente come gli account di servizio appena creati o l'account di servizio Compute Engine predefinito nel tuo progetto.

CONNECTOR_SERVICE_ACCOUNT: l'account di servizio per il runtime del connettore dell'interfaccia utente. Esempio: aa-ui-connector@my-project-id.iam.gserviceaccount.com.
INTERCEPTOR_SERVICE_ACCOUNT: l'account di servizio per il runtime di Cloud Pub/Sub Interceptor. Esempio: aa-pubsub-interceptor@my-project-id.iam.gserviceaccount.com.

Personalizzare il metodo di autenticazione utente

Il repository del codice supporta sia gli utenti di backend sia gli utenti del modulo frontend per Genesys Cloud e Twilio.

All'interno del repository del codice, apri il file ui_connector/auth.py.
Specifica il provider di identità supportato impostando la variabile di ambiente AUTH_OPTION o implementa il tuo metodo di autenticazione con auth.check_auth.

Per impostazione predefinita, AUTH_OPTION è vuoto e nessun utente è autorizzato a registrare JWT con il servizio UI Connector. Valori supportati:
- "Salesforce": verifica il token di autenticazione utilizzando Salesforce OpenID Connect. Variabile di ambiente obbligatoria: SALESFORCE_ORGANIZATION_ID.
- 'GenesysCloud': verifica il token di autenticazione utilizzando l'API Users dell'SDK Genesys.
- "Twilio": verifica il token di autenticazione per Twilio. Variabile di ambiente obbligatoria: TWILIO_FLEX_ENVIRONMENT.
Esempio:
```
$ export AUTH_OPTION='Salesforce'
```
Ogni tipo di token potrebbe avere un metodo di convalida diverso. Sei tu a decidere come viene convalidato il token. Senza modifiche, auth.check_auth restituisce false per ogni richiesta.

Genera e archivia una chiave segreta JWT

Affinché il servizio del connettore dell'interfaccia utente invii nuovamente i token di autenticazione sicuri al client, deve criptarli utilizzando una chiave segreta JWT. Il valore della chiave può essere qualsiasi stringa arbitraria, anche se deve essere univoca e difficile da indovinare.

Questa chiave segreta verrà archiviata in Secret Manager.

Imposta variabile di ambiente

JWT_SECRET_NAME: il nome della chiave segreta in Secret Manager. Può essere un nome qualsiasi. Valore consigliato: aa-integration-jwt-secret.

Genera la chiave

Ti consigliamo di generare un hash casuale come chiave segreta JWT in modo che non possa essere adivinata dagli utenti malintenzionati. A tale scopo, puoi utilizzare python secrets per generare numeri casuali sicuri.

Memorizza la chiave in Secret Manager

Nel seguente comando di esempio, sostituisci my_key con la chiave segreta che prevedi di utilizzare.

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

Configurare Memorystore for Redis

Per configurare Redis, sono necessarie le seguenti variabili di ambiente:

VPC_CONNECTOR_NAME: il nome del connettore di accesso VPC serverless per collegare i servizi Cloud Run a Memorystore for Redis. Valore consigliato: aa-integration-vpc.
VPC_NETWORK: la rete VPC a cui collegare il connettore di accesso VPC serverless. Il valore deve essere default se non configuri la VPC per il tuo progetto Google Cloud .
REDIS_IP_RANGE: una rete IP interna non prenotata per il connettore di accesso VPC serverless. È necessario /28 di spazio non allocato. Valore consigliato: 10.8.0.0/28 (questo valore dovrebbe funzionare per la maggior parte dei nuovi progetti).
REDIS_INSTANCE_ID: un nome per l'istanza Redis. Valore consigliato: aa-integration-redis.

Crea un'istanza Redis nella regione dei tuoi servizi Cloud Run

Esegui questo comando:

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

Crea un connettore di accesso VPC serverless

Assicurati che l'API Serverless VPC Access sia abilitata per il tuo progetto:

$ gcloud services enable vpcaccess.googleapis.com

Crea un connettore di accesso VPC serverless con un intervallo IP personalizzato:

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

Salva l'host Redis e la porta Redis come variabili di ambiente

Imposta l'indirizzo IP della tua istanza Redis sulla variabile di ambiente REDIS_HOST.
Imposta il numero di porta dell'istanza Redis sulla variabile di ambiente REDIS_PORT.

Esegui il deployment del servizio del connettore dell'interfaccia utente

Per il servizio del connettore dell'interfaccia utente, sono necessarie le seguenti variabili di ambiente:

CONNECTOR_SERVICE_NAME: il nome del servizio Cloud Run del connettore UI. Valore consigliato: ui-connector.
CONNECTOR_IMAGE_NAME: il nome dell'immagine del servizio UI Connector. Può essere uguale a CONNECTOR_SERVICE_NAME. Valore consigliato: ui-connector.

Crea l'immagine Docker

Nella cartella /ui-connector, esegui il seguente comando:

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

Esegui il deployment del connettore dell'interfaccia utente in Cloud Run

Nella cartella /ui-connector, esegui il seguente comando. Prendi nota dell'URL del servizio per il connettore UI di cui è stato eseguito il deployment, che verrà utilizzato dai client (computer degli agenti).

$ 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

Esegui il deployment del servizio di intercettazione Cloud Pub/Sub

Per il servizio di intercettazione Pub/Sub, sono necessarie le seguenti variabili di ambiente:

INTERCEPTOR_SERVICE_NAME: il nome del servizio Cloud Run dell'intercettatore Cloud Pub/Sub. Valore consigliato: cloud-pubsub-interceptor.
INTERCEPTOR_IMAGE_NAME: il nome dell'immagine del servizio di intercettazione Cloud Pub/Sub. Può essere uguale a INTERCEPTOR_SERVICE_NAME. Valore consigliato: cloud-pubsub-interceptor.

Crea l'immagine Docker

Nella cartella /cloud-pubsub-interceptor, esegui il seguente comando:

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

Esegui il deployment dell'intercettatore Pub/Sub in Cloud Run

Nella cartella /cloud-pubsub-interceptor, esegui il seguente comando:

$ 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

Salva l'URL di deployment

Imposta l'URL di cui è stato eseguito il deployment come variabile di ambiente INTERCEPTOR_SERVICE_URL.

Configurare le sottoscrizioni Cloud Pub/Sub

Gli abbonamenti Cloud Pub/Sub utilizzano quanto segue:

Argomenti
Profilo di conversazione
Service account
Autorizzazione account di servizio per il servizio di intercettazione
Eventi del ciclo di vita della conversazione

Creare argomenti Cloud Pub/Sub

Crea un argomento Cloud Pub/Sub per ogni tipo di notifica di evento di cui hai bisogno da Dialogflow. I tipi di notifiche di eventi disponibili sono:

Eventi relativi ai nuovi suggerimenti: eventi inviati quando sono disponibili nuovi suggerimenti di Agent Assist (ad esempio, nuovi suggerimenti di Risposta rapida in risposta a un'espressione del cliente).
Eventi relativi a nuovi messaggi: eventi inviati ogni volta che viene riconosciuta una nuova frase da un agente o un cliente (ad esempio, il cliente dice Hi).
Nuovi eventi del ciclo di vita della conversazione: eventi inviati per determinate modifiche del ciclo di vita della conversazione (ad esempio quando una conversazione viene avviata o completata).
Nuovi eventi di notifica del risultato del riconoscimento: eventi inviati quando la trascrizione intermedia viene riconosciuta da un agente o un cliente (ad esempio, il cliente dice Hi, how can I help you?, mentre la trascrizione intermedia è Hi how can mentre il cliente parla).

Prendi nota dell'ID e del nome dell'argomento per il successivo deployment del backend.

Configurare un profilo di conversazione

Configura un profilo di conversazione con gli argomenti Cloud Pub/Sub che hai creato nel passaggio precedente.

Quando crei un nuovo profilo di conversazione, seleziona Notifiche Pub/Sub, quindi Attiva notifiche Pub/Sub. Una volta attivata, puoi selezionare le caselle accanto ai tipi di notifiche che vuoi attivare e inserire l'ID argomento per l'argomento Cloud Pub/Sub associato alla notifica.
Seleziona JSON come formato del messaggio per ogni argomento.

Creare un account di servizio per l'identità della sottoscrizione Pub/Sub

Crea un account di servizio che rappresenti l'identità dell'abbonamento Pub/Sub utilizzando il seguente comando:

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

Concedi all'account di servizio l'autorizzazione per richiamare il servizio di intercettazione

Esegui questo comando:

$ 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

Creare sottoscrizioni Cloud Pub/Sub per gli argomenti

Per ogni argomento creato, devi creare una sottoscrizione Cloud Pub/Sub corrispondente.

Nuovi eventi di suggerimento

Sostituisci your-new-suggestion-topic-id con l'argomento Cloud Pub/Sub configurato per i nuovi suggerimenti:

$ 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

Nuovi eventi di messaggio

Sostituisci your-new-message-event-topic-id con l'argomento Cloud Pub/Sub configurato per i nuovi eventi di messaggio:

$ 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

Eventi del ciclo di vita della conversazione

Sostituisci your-conversation-lifecycle-event-topic con l'argomento Cloud Pub/Sub configurato per i nuovi eventi del ciclo di vita della conversazione:

$ 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

Nuovi eventi di notifica dei risultati di riconoscimento

$ 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