Backend modules is an out-of-the-box solution that provides an effective backend infrastructure to process large volumes of feature-related messages and interact with the agent desktop UI. This tutorial walks you through the process of integrating backend modules with your agent system.
For more information about background modules concepts and structure, see the backend modules basics documentation.
Prerequisites
- Install the Google Cloud CLI if you haven't already configured it.
Set up environment variables
To make the commands for deployment simpler, we recommend that you set the following useful environment variables in your shell. You can set the variables using the following example command:
$ export GCP_PROJECT_ID='enter_project_id_here' \ && export SERVICE_REGION='us-central1'
Set the following environment variables:
GCP_PROJECT_ID
: The project ID of your Cloud Platform project that hosts related resources. Example:my-project
.SERVICE_REGION
: The location or region of your services and related Cloud Platform resources. Example:us-central1
.
Set up an administrative account
We recommend using separate Google Cloud Platform accounts for service administration and runtime identity. Service administration is mainly performed by humans with Google accounts, while runtime identity grants Cloud Run services permissions using service accounts to enable access to necessary resources.
Prepare the human administrative account
If you plan to use an account that already has Editor or Owner permissions in your project, you can skip ahead to the next section.
To manage the backend infrastructure, establish an administrator account and grant it the following IAM roles. Their permissions are all included in the basic roles Editor (roles/editor) and Owner (roles/owner).
roles/secretmanager.admin
(Secret Manager Admin): Manage secrets stored in Secret Manager for JWT generation and verification.roles/run.admin
(Cloud Run Admin): Deploy and manage Cloud Run services.roles/iam.serviceAccountUser
(Service Account User): Grant Cloud Run runtime service accountsiam.serviceAccounts.actAs
permissions.roles/cloudbuild.builds.editor
(Cloud Build Editor): Build Docker images for the integration services using Cloud Build.- Artifact Registry Administrator: Store and manage built Docker images for the integration services.
roles/pubsub.editor
(Cloud Pub/Sub Editor): Create and manage Cloud Pub/Sub topics and subscriptions.roles/redis.admin
(Redis Admin): Create and manage Memorystore for Redis' resources.
To grant IAM roles to a human account, use the
add-iam-policy-binding
gcloud command. The following is an example command:
$ gcloud projects add-iam-policy-binding $GCP_PROJECT_ID \ --member='user:test-user@gmail.com' \ --role='roles/pubsub.editor'
Set the human administrative account in gcloud
Replace $ADMIN_ACCOUNT
with the admin account you would like to use
(for example: myaccount@gmail.com
) in the following sample:
$ gcloud config set account $ADMIN_ACCOUNT
Set up service accounts
By default, Cloud Run services or jobs run as the default Compute Engine service account. Rather than leave the default, we recommend giving every Cloud Run service a dedicated identity by assigning it a user-managed service account with the minimum required set of permissions. If you plan to keep the default service account, you can skip ahead to set environment variables.
Create two service accounts for each Cloud Run runtime
- To create the service accounts, replace the value of
$CONNECTOR_SERVICE_ACCOUNT_ID
and$INTERCEPTOR_SERVICE_ACCOUNT_ID
if and run the following commands:
$ 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'
- Use the following sample command to assign the following roles to the UI connector and Cloud Pub/Sub connector service accounts:
$ 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'
Grant the following IAM roles to the UI connector service account:
roles/redis.editor
roles/vpcaccess.user
roles/compute.viewer
roles/secretmanager.secretAccessor
roles/dialogflow.agentAssistClient
Grant the following roles to the Cloud Pub/Sub connector service account:
roles/redis.editor
roles/vpcaccess.user
roles/compute.viewer
Set environment variables
Set the values of the following environment variables to be the service accounts you just created or the default Compute Engine service account in your project.
CONNECTOR_SERVICE_ACCOUNT
: The service account for UI connector runtime. Example:aa-ui-connector@my-project-id.iam.gserviceaccount.com
.INTERCEPTOR_SERVICE_ACCOUNT
: The service account for Cloud Pub/Sub Interceptor runtime. Example:aa-pubsub-interceptor@my-project-id.iam.gserviceaccount.com
.
Customize the user authentication method
In the code repository, open the ui_connector/auth.py
file and implement the
check_auth(auth_token)
function. This function takes an authentication token
that is sent by the UI as an input, and should validate that token and return
either true
or false
depending on whether the token is valid. How the token
is validated will be up to you, as each token type might have a different means
of validation. Without any changes, it returns false
for every request.
Generate and store a JWT secret key
In order for the UI connector service to send secure authentication tokens back to the client, it must encrypt them using a JWT secret key. The key's value can be any arbitrary string, although it should be unique and difficult to guess.
This secret key will be stored in Secret Manager.
Set environment variable
JWT_SECRET_NAME
: The name for the secret key in Secret Manager. It can be any arbitrary name. Recommended value:aa-integration-jwt-secret
.
Generate the key
We recommend generating a random hash as the JWT secret key so that it cannot be guessed by attackers. To do so, you can use python secrets to generate secure random numbers for it.
Store the key in Secret Manager
In the following example command, replace my_key
with the secret key you plan
to use.
printf "my_key" | gcloud secrets create $JWT_SECRET_NAME --data-file=- --replication-policy=user-managed --locations=$SERVICE_REGION
Set up Memorystore for Redis
Set up environment variables
VPC_CONNECTOR_NAME
: The name of your Serverless VPC Access connector for connecting Cloud Run services to Memorystore for Redis. Recommended value:aa-integration-vpc
.VPC_NETWORK
: The VPC network to attach your Serverless VPC Access connector to. The value should be 'default' if you do not set up VPC for your Google Cloud Platform project.REDIS_IP_RANGE
: An unreserved internal IP network for your Serverless VPC Access connector. A '/28' of unallocated space is required. Recommended value:10.8.0.0/28
(this value should work for most new projects).REDIS_INSTANCE_ID
: A name for your Redis instance. Recommended value:aa-integration-redis
.
Create a Redis instance in the same region as your Cloud Run services
Run the following command:
$ gcloud redis instances create $REDIS_INSTANCE_ID --size=5 --region=$SERVICE_REGION
Create a Serverless VPC Access connector
Ensure that the Serverless VPC Access API is enabled for your project:
$ gcloud services enable vpcaccess.googleapis.com
Create a Serverless VPC Access connector with a custom IP range:
$ gcloud compute networks vpc-access connectors create $VPC_CONNECTOR_NAME \ --network $VPC_NETWORK \ --region $SERVICE_REGION \ --range $REDIS_IP_RANGE
Save the Redis host and Redis port as environment variables
- Set the IP Address of your Redis instance to environment variable
REDIS_HOST
. - Set the port number of your Redis instance to environment variable
REDIS_PORT
.
Deploy the UI connector service
Set environment variables
CONNECTOR_SERVICE_NAME
: The Cloud Run service name of your UI Connector. Recommended value:ui-connector
.CONNECTOR_IMAGE_NAME
: The image name of your UI Connector service. It can be the same asCONNECTOR_SERVICE_NAME
. Recommended value:ui-connector
.
Build the Docker image
Under the /ui-connector
folder, run the following command:
$ gcloud builds submit --tag gcr.io/$GCP_PROJECT_ID/$CONNECTOR_IMAGE_NAME
Deploy to Cloud Run
Under the /ui-connector
folder,
run the following command. Make a note of the service URL for the deployed UI
Connector, which will be used by clients (agent desktops).
$ 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
Deploy the Cloud Pub/Sub Interceptor service
Set environment variables
INTERCEPTOR_SERVICE_NAME
: The Cloud Run service name of your Cloud Pub/Sub Interceptor. Recommended value:cloud-pubsub-interceptor
.INTERCEPTOR_IMAGE_NAME
: The image name of your Cloud Pub/Sub Interceptor service. It can be the same asINTERCEPTOR_SERVICE_NAME
. Recommended value:cloud-pubsub-interceptor
.
Build the Docker image
Under the /cloud-pubsub-interceptor
folder, run the following command:
$ gcloud builds submit --tag gcr.io/$GCP_PROJECT_ID/$INTERCEPTOR_IMAGE_NAME
Deploy to Cloud Run
Under the /cloud-pubsub-interceptor
folder, run the following command:
$ 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
Save the deployed URL
Set the deployed URL as the INTERCEPTOR_SERVICE_URL
environment variable.
Configure Cloud Pub/Sub subscriptions
Create Cloud Pub/Sub topics
Create a Cloud Pub/Sub topic for each kind of event notification you need from Dialogflow. The available event notification types are:
- New suggestion events: Events sent when new Agent Assist suggestions are available (for example, new Smart Reply suggestions in response to a customer utterance).
- New message events: Events sent whenever a new utterance is recognized
from an agent or customer (for example, customer says
Hi
). - New conversation lifecycle events: Events sent for certain conversation lifecycle changes (for example, when a conversation is started, or when it is completed).
Make a note of the topic ID and topic name for later backend deployment.
Configure a conversation profile
Configure a conversation profile with the Cloud Pub/Sub topics that you created in the previous step.
- When you create a new conversation profile, select Pub/Sub notifications and then Enable Pub/Sub notifications. Once enabled, you can check the boxes next to the types of notifications you'd like to enable and enter the topic ID for the notification's associated Cloud Pub/Sub topic.
- Select
JSON
as the message format for each topic.
Create a service account to represent the Pub/Sub subscription identity
Create a new service account using the following command:
$ gcloud iam service-accounts create cloud-run-pubsub-invoker \ --display-name "Cloud Run Pub/Sub Invoker"
Give the service account permission to invoke your interceptor service
Run the following command:
$ 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
Create Cloud Pub/Sub subscriptions for each topic
For each topic that you created, you must create a corresponding Cloud Pub/Sub subscription.
New suggestion events
Replace your-new-suggestion-topic-id
with the Cloud Pub/Sub topic you
configured for new 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
New message events
Replace your-new-message-event-topic-id
with the Cloud Pub/Sub topic you
configured for new message events:
$ 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
Conversation lifecycle events
Replace your-conversation-lifecycle-event-topic
with the Cloud Pub/Sub topic
you configured for new conversation lifecycle events:
$ 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