Se usó la API de Cloud Translation para traducir esta página.

Integra módulos de backend con tu sistema

Los módulos de backend son una solución lista para usar que proporciona una infraestructura de backend eficaz para procesar grandes volúmenes de mensajes relacionados con las funciones y para interactuar con la IU de escritorio del agente. En este instructivo, se explica el proceso de integración de los módulos de backend con tu sistema de agentes.

Para obtener más información sobre los conceptos y la estructura de los módulos en segundo plano, consulta la documentación sobre los conceptos básicos de los módulos de backend.

Requisitos previos

Instala Google Cloud CLI si aún no lo configuraste.

Configura variables de entorno

Para simplificar los comandos de implementación, te recomendamos que configures las siguientes variables de entorno útiles en tu shell. Puedes configurar las variables con el siguiente comando de ejemplo:

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

Configura las siguientes variables de entorno:

GCP_PROJECT_ID: Es el ID del proyecto de tu proyecto de Cloud Platform que aloja los recursos relacionados. Ejemplo: my-project.
SERVICE_REGION: Es la ubicación o región de tus servicios y los recursos relacionados de Cloud Platform. Ejemplo: us-central1.

Configura una cuenta de administrador

Te recomendamos que uses cuentas de Google Cloud separadas para la administración de servicios y la identidad del entorno de ejecución. La administración de servicios la realizan principalmente las personas con Cuentas de Google, mientras que la identidad del entorno de ejecución otorga permisos a los servicios de Cloud Run con cuentas de servicio para habilitar el acceso a los recursos necesarios.

Prepara la cuenta de administrador humana

Si planeas usar una cuenta que ya tiene permisos de editor o propietario en tu proyecto, puedes avanzar a la siguiente sección.

Para administrar la infraestructura de backend, establece una cuenta de administrador y otórgale los siguientes roles de IAM. Todos sus permisos se incluyen en los roles básicos Editor (roles/editor) y Propietario (roles/owner).

roles/secretmanager.admin (Administrador de Secret Manager): Administra los secretos almacenados en Secret Manager para la generación y verificación de JWT.
roles/run.admin (Administrador de Cloud Run): Implementa y administra servicios de Cloud Run.
roles/iam.serviceAccountUser (Usuario de cuenta de servicio): Otorga permisos iam.serviceAccounts.actAs a las cuentas de servicio del entorno de ejecución de Cloud Run.
roles/cloudbuild.builds.editor (editor de Cloud Build): Compila imágenes de Docker para los servicios de integración con Cloud Build.
Administrador de Artifact Registry: Almacena y administra imágenes de Docker compiladas para los servicios de integración.
roles/pubsub.editor (editor de Cloud Pub/Sub): Crea y administra temas y suscripciones de Cloud Pub/Sub.
roles/redis.admin (Administrador de Redis): Crea y administra los recursos de Memorystore para Redis.

Para otorgar roles de IAM a una cuenta humana, usa el comando add-iam-policy-binding de Google Cloud CLI. El siguiente es un ejemplo de comando:

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

Configura la cuenta de administrador humana en gcloud

Reemplaza $ADMIN_ACCOUNT por la cuenta de administrador que deseas usar (por ejemplo, myaccount@gmail.com) en el siguiente ejemplo:

$ gcloud config set account $ADMIN_ACCOUNT

Configura cuentas de servicio

De forma predeterminada, los servicios o trabajos de Cloud Run se ejecutan como la cuenta de servicio predeterminada de Compute Engine. En lugar de dejar la configuración predeterminada, te recomendamos que asignes una cuenta de servicio administrada por el usuario a cada servicio de Cloud Run con el conjunto mínimo de permisos requeridos. Si planeas conservar la cuenta de servicio predeterminada, puedes avanzar al paso para configurar variables de entorno.

Crea dos cuentas de servicio para cada entorno de ejecución de Cloud Run

Para crear las cuentas de servicio, reemplaza el valor de $CONNECTOR_SERVICE_ACCOUNT_ID y $INTERCEPTOR_SERVICE_ACCOUNT_ID si y ejecuta los siguientes comandos:

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

Usa el siguiente comando de muestra para asignar los siguientes roles al conector de la IU y a las cuentas de servicio del conector de 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'

Otorga los siguientes roles de IAM a la cuenta de servicio del conector de la IU:

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

Otorga los siguientes roles a la cuenta de servicio del conector de Cloud Pub/Sub:

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

Configura variables de entorno

Establece los valores de las siguientes variables de entorno para que sean las cuentas de servicio que acabas de crear o la cuenta de servicio predeterminada de Compute Engine de tu proyecto.

CONNECTOR_SERVICE_ACCOUNT: Es la cuenta de servicio del entorno de ejecución del conector de IU. Ejemplo: aa-ui-connector@my-project-id.iam.gserviceaccount.com.
INTERCEPTOR_SERVICE_ACCOUNT: Es la cuenta de servicio del entorno de ejecución del Interceptor de Cloud Pub/Sub. Ejemplo: aa-pubsub-interceptor@my-project-id.iam.gserviceaccount.com.

Personaliza el método de autenticación del usuario

El repositorio de código admite usuarios de backend y usuarios del módulo de frontend para Genesys Cloud y Twilio.

Dentro del repositorio de código, abre el archivo ui_connector/auth.py.
Para especificar el proveedor de identidad compatible, configura la variable de entorno AUTH_OPTION o implementa tu método de autenticación con auth.check_auth.

De forma predeterminada, AUTH_OPTION está vacío y ningún usuario puede registrar JWT con el servicio de conector de IU. Valores admitidos:
- "Salesforce": Verifica el token de autenticación con OpenID Connect de Salesforce. Variable de entorno obligatoria: SALESFORCE_ORGANIZATION_ID.
- 'GenesysCloud': Verifica el token de autenticación con la API de Users del SDK de Genesys.
- "Twilio": Verifica el token de autenticación de Twilio. Variable de entorno obligatoria: TWILIO_FLEX_ENVIRONMENT.
Ejemplo:
```
$ export AUTH_OPTION='Salesforce'
```
Cada tipo de token puede tener un medio de validación diferente. Tú decides cómo se valida el token. Sin ningún cambio, auth.check_auth muestra false para cada solicitud.

Genera y almacena una clave secreta de JWT

Para que el servicio del conector de IU envíe tokens de autenticación seguros al cliente, debe encriptarlos con una clave secreta de JWT. El valor de la clave puede ser cualquier cadena arbitraria, aunque debe ser única y difícil de adivinar.

Esta clave secreta se almacenará en Secret Manager.

Configura la variable de entorno

JWT_SECRET_NAME: Es el nombre de la clave secreta en Secret Manager. Puede ser cualquier nombre arbitrario. Valor recomendado: aa-integration-jwt-secret.

Genera la clave

Te recomendamos que generes un hash aleatorio como la clave secreta de JWT para que los atacantes no puedan adivinarla. Para ello, puedes usar secretos de Python para generar números aleatorios seguros.

Almacena la clave en Secret Manager

En el siguiente comando de ejemplo, reemplaza my_key por la clave secreta que planeas usar.

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

Configura Memorystore para Redis

Para configurar Redis, necesitas las siguientes variables de entorno:

VPC_CONNECTOR_NAME: Es el nombre de tu conector de Acceso a VPC sin servidores para conectar servicios de Cloud Run a Memorystore para Redis. Valor recomendado: aa-integration-vpc.
VPC_NETWORK: La red de VPC a la que conectarás tu conector de Acceso a VPC sin servidores El valor debe ser default si no configuras VPC para tu proyecto de Google Cloud .
REDIS_IP_RANGE: Una red IP interna no reservada para tu conector de Acceso a VPC sin servidores. Se requiere un /28 de espacio no asignado. Valor recomendado: 10.8.0.0/28 (este valor debería funcionar en la mayoría de los proyectos nuevos).
REDIS_INSTANCE_ID: Es un nombre para tu instancia de Redis. Valor recomendado: aa-integration-redis.

Crea una instancia de Redis en la región de tus servicios de Cloud Run

Ejecuta el siguiente comando:

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

Creación de un conector de acceso a VPC sin servidores

Asegúrate de que esté habilitada la API de Acceso a VPC sin servidores en el proyecto:

$ gcloud services enable vpcaccess.googleapis.com

Crea un conector de acceso a VPC sin servidores con un rango de IP personalizado:

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

Guarda el host y el puerto de Redis como variables de entorno

Establece la dirección IP de tu instancia de Redis en la variable de entorno REDIS_HOST.
Establece el número de puerto de tu instancia de Redis en la variable de entorno REDIS_PORT.

Implementa el servicio del conector de IU

Para el servicio de conector de IU, necesitas las siguientes variables de entorno:

CONNECTOR_SERVICE_NAME: Es el nombre del servicio de Cloud Run de tu conector de IU. Valor recomendado: ui-connector.
CONNECTOR_IMAGE_NAME: Es el nombre de la imagen de tu servicio de conector de IU. Puede ser igual a CONNECTOR_SERVICE_NAME. Valor recomendado: ui-connector.

Compila la imagen de Docker

En la carpeta /ui-connector, ejecuta el siguiente comando:

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

Implementa el conector de IU en Cloud Run

En la carpeta /ui-connector, ejecuta el siguiente comando. Anota la URL del servicio del conector de IU implementado, que usarán los clientes (escritorios de agentes).

$ 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

Implementa el servicio de interceptor de Cloud Pub/Sub

Para el servicio de interceptor de Pub/Sub, necesitas las siguientes variables de entorno:

INTERCEPTOR_SERVICE_NAME: Es el nombre del servicio de Cloud Run de tu interceptor de Cloud Pub/Sub. Valor recomendado: cloud-pubsub-interceptor.
INTERCEPTOR_IMAGE_NAME: Es el nombre de la imagen de tu servicio de interceptor de Cloud Pub/Sub. Puede ser igual a INTERCEPTOR_SERVICE_NAME. Valor recomendado: cloud-pubsub-interceptor.

Compila la imagen de Docker

En la carpeta /cloud-pubsub-interceptor, ejecuta el siguiente comando:

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

Implementa el interceptor de Pub/Sub en Cloud Run

En la carpeta /cloud-pubsub-interceptor, ejecuta el siguiente 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

Guarda la URL implementada

Establece la URL implementada como la variable de entorno INTERCEPTOR_SERVICE_URL.

Configura suscripciones a Cloud Pub/Sub

Las suscripciones de Cloud Pub/Sub usan lo siguiente:

Temas
Perfil de conversación
Cuenta de servicio
Permiso de la cuenta de servicio para el servicio de interceptor
Eventos del ciclo de vida de la conversación

Crea temas de Cloud Pub/Sub

Crea un tema de Cloud Pub/Sub para cada tipo de notificación de evento que necesites de Dialogflow. Los tipos de notificaciones de eventos disponibles son los siguientes:

Eventos de sugerencias nuevas: Son eventos que se envían cuando hay sugerencias nuevas de Agent Assist disponibles (por ejemplo, sugerencias nuevas de Smart Reply en respuesta a una frase del cliente).
Eventos de mensaje nuevo: Son eventos que se envían cada vez que se reconoce una nueva oración de un agente o cliente (por ejemplo, el cliente dice Hi).
Nuevos eventos de ciclo de vida de la conversación: Son eventos que se envían para ciertos cambios en el ciclo de vida de la conversación (por ejemplo, cuando se inicia una conversación o cuando se completa).
Nuevos eventos de notificación de resultados de reconocimiento: Son eventos que se envían cuando se reconoce una transcripción intermedia de un agente o cliente (por ejemplo, el cliente dice Hi, how can I help you?, una transcripción intermedia es Hi how can mientras el cliente habla).

Anota el ID y el nombre del tema para la implementación posterior del backend.

Cómo configurar un perfil de conversación

Configura un perfil de conversación con los temas de Cloud Pub/Sub que creaste en el paso anterior.

Cuando crees un perfil de conversación nuevo, selecciona Notificaciones de Pub/Sub y, luego, Habilitar notificaciones de Pub/Sub. Una vez habilitadas, puedes marcar las casillas junto a los tipos de notificaciones que deseas habilitar y, luego, ingresar el ID del tema de Cloud Pub/Sub asociado a la notificación.
Selecciona JSON como el formato de mensaje para cada tema.

Crea una cuenta de servicio para la identidad de suscripción de Pub/Sub

Crea una cuenta de servicio que represente la identidad de suscripción de Pub/Sub con el siguiente comando:

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

Otorga permiso a la cuenta de servicio para invocar tu servicio de interceptor

Ejecuta el siguiente 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

Crea suscripciones a Cloud Pub/Sub para temas

Para cada tema que creaste, debes crear la suscripción correspondiente a Cloud Pub/Sub.

Eventos de sugerencias nuevas

Reemplaza your-new-suggestion-topic-id por el tema de Cloud Pub/Sub que configuraste para las sugerencias nuevas:

$ 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

Eventos de mensajes nuevos

Reemplaza your-new-message-event-topic-id por el tema de Cloud Pub/Sub que configuraste para eventos de mensajes nuevos:

$ 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

Eventos del ciclo de vida de la conversación

Reemplaza your-conversation-lifecycle-event-topic por el tema de Cloud Pub/Sub que configuraste para los eventos nuevos del ciclo de vida de la conversación:

$ 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

Nuevos eventos de notificación de resultados de reconocimiento

$ 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