Integrar módulos de back-end ao seu sistema

Os módulos de back-end fornecem uma infraestrutura para processar grandes volumes de mensagens relacionadas a recursos e interagir com a UI do usuário da área de trabalho do agente. Neste tutorial, mostramos como integrar módulos de back-end ao sistema de agente.

Para mais informações sobre conceitos e estrutura de módulos em segundo plano, consulte a documentação Noções básicas sobre módulos de back-end.

Pré-requisitos

  1. Se você ainda não tiver feito isso, instale a Google Cloud CLI.
  2. Crie um tópico do Cloud Pub/Sub para cada tipo de notificação de evento que você precisa do Dialogflow. Anote o ID e o nome do tópico para implantação posterior do back-end.
  3. Configure seu perfil de conversa usando o console da Assistente de IA com tópicos do Pub/Sub.

Implantação automatizada

A implantação pode ser automatizada por um Google Cloud script de automação ou pelo Terraform.

Script de automação

Confira ./deploy.sh para mais detalhes.

Aplicar mudanças do Terraform

É possível automatizar a implantação com um script de automação da CLI gcloud ou o Terraform. Antes de aplicar as mudanças do Terraform, siga estas etapas.

  1. Conceda os seguintes papéis do IAM à sua conta:
    • Project IAM Admin (roles/resourcemanager.projectIamAdmin)
    • Service Usage Admin (roles/serviceusage.serviceUsageAdmin)
    • Service Account Admin (roles/iam.serviceAccountAdmin)
    • Service Account User (roles/iam.serviceAccountUser)
    • Pub/Sub Admin (roles/pubsub.admin)
    • Secret Manager Admin (roles/secretmanager.admin)
    • Cloud Build Editor (roles/cloudbuild.builds.editor)
    • Artifact Registry Administrator (roles/artifactregistry.admin)
    • Storage Admin (roles/storage.admin)
    • Cloud Run Admin (roles/run.admin)
    • Cloud Memorystore Redis Admin (roles/redis.admin)
    • Serverless VPC Access Admin (roles/vpcaccess.admin)
  2. Crie imagens para o conector de interface e para o interceptor do Cloud Pub/Sub e anote o nome da imagem.
    • Para o conector de interface, execute o seguinte comando na pasta ./ui-connector. 
      $ gcloud builds submit --tag gcr.io/$GCP_PROJECT_ID/aa-integration-backend/ui-connector
    • Para o interceptor do Cloud Pub/Sub, execute o seguinte comando na pasta ./cloud-pubsub-interceptor. 
      $ gcloud builds submit --tag gcr.io/$GCP_PROJECT_ID/aa-integration-backend/cloud-pubsub-interceptor
  3. Crie um bucket do Cloud Storage para armazenar o estado do Terraform e atualize o valor do bucket de back-end em /terraform/backend.tf usando o seguinte comando. 
    GCP_PROJECT_ID=$(gcloud config get-value project)
# Create the Cloud storage bucket
gcloud storage buckets create gs://${GCP_PROJECT_ID}-tfstate
# Enable Object Versioning to keep the history of your deployments
gcloud storage buckets update gs://${GCP_PROJECT_ID}-tfstate --versioning
  4. Exporte o valor das variáveis necessárias do Terraform gcp_project_id, ui_connector_docker_image e cloud_pubsub_interceptor_docker_image. Exemplo: export TF_VAR_gcp_project_id='you-gcp-project-id'. Como alternativa, você pode preencher os valores diretamente em /terraform/variables.tf.
  5. Personalize o método de autenticação modificando o método auth.check_auth() em /ui-connector/auth.py.

Se quiser automatizar essas etapas usando o Cloud Build, siga esta instrução e use o arquivo de configuração de build ./terraform_cloudbuild.yaml. Para permitir que o Cloud Build implante os serviços, conceda à conta de serviço do Cloud Build os papéis do IAM listados na etapa 1.

Implantação manual

As etapas a seguir explicam como implantar módulos de back-end manualmente.

Configurar variáveis de ambiente

Para simplificar os comandos de implantação, recomendamos que você defina as seguintes variáveis de ambiente úteis no shell. Você pode definir as variáveis usando o seguinte comando de exemplo:

$ export GCP_PROJECT_ID='aa-integration-service'

Configure as variáveis de ambiente a seguir:

  • GCP_PROJECT_ID: o ID do projeto do Cloud Platform que hospeda recursos relacionados. Exemplo: my-project.
  • SERVICE_REGION: o local ou a região dos seus serviços e dos recursos Google Cloud relacionados. Recursos da plataforma. Exemplo: us-central1.

Configurar uma conta administrativa

Recomendamos usar contas Google Cloud separadas para administração de serviços e identidade de tempo de execução. A administração de serviços é feita principalmente por humanos com Contas do Google, enquanto a identidade de tempo de execução concede permissões aos serviços do Cloud Run usando contas de serviço para permitir o acesso aos recursos necessários.

Preparar a conta administrativa humana

Se você planeja usar uma conta que já tem permissões de editor ou proprietário no seu projeto, pule para a próxima seção.

Para gerenciar a infraestrutura de back-end, crie uma conta de administrador e conceda a ela os seguintes papéis do Identity and Access Management (IAM). Todas as permissões deles estão incluídas nos papéis básicos de editor e proprietário.

  • roles/secretmanager.admin (administrador do Secret Manager): gerencie os secrets armazenados no Secret Manager para geração e verificação de JWTs.
  • roles/run.admin (administrador do Cloud Run): implante e gerencie serviços do Cloud Run.
  • roles/iam.serviceAccountUser (usuário da conta de serviço): conceda permissões iam.serviceAccounts.actAs às contas de serviço do ambiente de execução do Cloud Run.
  • roles/cloudbuild.builds.editor (Editor do Cloud Build): crie imagens Docker para os serviços de integração usando o Cloud Build.
  • Administrador do Artifact Registry: armazena e gerencia imagens do Docker criadas para os serviços de integração.
  • roles/pubsub.editor (Editor do Cloud Pub/Sub): crie e gerencie tópicos e assinaturas do Cloud Pub/Sub.
  • roles/redis.admin (administrador do Redis): crie e gerencie recursos do Memorystore para Redis.

Para conceder papéis do IAM a uma conta humana, use o comando da Google Cloud CLI add-iam-policy-binding. Confira um exemplo de comando:

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

Definir a conta administrativa humana na gcloud

Substitua $ADMIN_ACCOUNT pela conta de administrador que você quer usar (por exemplo: myaccount@gmail.com) no exemplo a seguir:

$ gcloud config set account $ADMIN_ACCOUNT

Configurar contas de serviço

Por padrão, os serviços ou jobs do Cloud Run são executados como a conta de serviço padrão do Compute Engine. Em vez de deixar o padrão, recomendamos dar a cada serviço do Cloud Run uma identidade dedicada, atribuindo a ele uma conta de serviço gerenciado pelo usuário com o conjunto mínimo de permissões necessárias. Se você planeja manter a conta de serviço padrão, pule para definir variáveis de ambiente.

Crie duas contas de serviço para cada ambiente de execução do Cloud Run

  1. Para criar as contas de serviço, substitua o valor de $CONNECTOR_SERVICE_ACCOUNT_ID e $INTERCEPTOR_SERVICE_ACCOUNT_ID, se necessário, e execute os seguintes 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'

  2. Use o seguinte comando de exemplo para atribuir os papéis a seguir às contas de serviço do conector da UI e do conector do 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'

Conceda os seguintes papéis do IAM à conta de serviço do conector da UI:

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

Conceda os seguintes papéis à conta de serviço do conector do Cloud Pub/Sub:

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

Defina as variáveis de ambiente

Defina os valores das seguintes variáveis de ambiente como as contas de serviço que você acabou de criar ou a conta de serviço padrão do Compute Engine no seu projeto.

  1. CONNECTOR_SERVICE_ACCOUNT: a conta de serviço para o ambiente de execução do conector de UI. Exemplo: aa-ui-connector@my-project-id.iam.gserviceaccount.com.
  2. INTERCEPTOR_SERVICE_ACCOUNT: a conta de serviço do tempo de execução do interceptor do Cloud Pub/Sub. Exemplo: aa-pubsub-interceptor@my-project-id.iam.gserviceaccount.com.

Personalizar o método de autenticação do usuário

O repositório de código é compatível com usuários de back-end e do módulo de front-end para Genesys Cloud e Twilio.

  1. No repositório de código, abra o arquivo ui_connector/auth.py.

  2. Especifique o provedor de identidade compatível definindo a variável de ambiente AUTH_OPTION ou implemente seu método de autenticação com auth.check_auth.

    Por padrão, AUTH_OPTION está vazio e nenhum usuário pode registrar JWT com o serviço UI Connector. Valores aceitos:

    • Salesforce: verifique o token de autenticação usando o OpenID Connect do Salesforce. Variável de ambiente obrigatória: SALESFORCE_ORGANIZATION_ID.
    • SalesforceLWC: verifique um token de autenticação de credenciais do cliente OAuth do Salesforce usando o endpoint REST oauth2/userinfo. Variáveis de ambiente obrigatórias: SALESFORCE_ORGANIZATION_ID, SALESFORCE_DOMAIN.
    • GenesysCloud: verifique o token de autenticação usando a UsersAPI do SDK do Genesys.
    • Twilio: verifique o token de autenticação do Twilio. Variável de ambiente obrigatória: TWILIO_FLEX_ENVIRONMENT.
    • Skip: ignora a verificação do token de autenticação. Ele não deve ser usado na produção.

    Exemplo: 

    $ export AUTH_OPTION='Salesforce'

    Cada tipo de token pode ter uma forma diferente de validação. Você decide como o token é validado. Sem mudanças, auth.check_auth retorna false para cada solicitação.

Para limitar as origens que podem acessar seu serviço, mude o valor da variável config.CORS_ALLOWED_ORIGINS. O valor padrão * permite que qualquer origem acesse seu serviço.

Gerar e armazenar uma chave secreta JWT

Para que o serviço de conector da UI envie tokens de autenticação seguros de volta ao cliente, é necessário criptografá-los usando uma chave secreta JWT. O valor da chave pode ser qualquer string arbitrária, mas precisa ser exclusivo e difícil de adivinhar.

Essa chave secreta será armazenada no Secret Manager.

Definir variável de ambiente

  • JWT_SECRET_NAME: o nome da chave secreta no Secret Manager. Pode ser qualquer nome arbitrário. Valor recomendado: aa-integration-jwt-secret.

Gerar a chave

Recomendamos gerar um hash aleatório como chave secreta do JWT para que ele não possa ser adivinhado por invasores. Para isso, use python secrets para gerar números aleatórios seguros.

# generate_secret_key.py
import secrets
jwt_secret_key = secrets.token_bytes(16)
print(jwt_secret_key) # Output example: b'L\x9b\xd6i4\xc3\x1d\x95\xe3\xf78z\xdda\x97\xec'

Armazenar a chave no Secret Manager

No exemplo de comando a seguir, substitua my_key pela chave secreta que você planeja usar.

$ python generate_secret_key.py | gcloud secrets create $JWT_SECRET_NAME --data-file=- \
--replication-policy=user-managed --locations=$SERVICE_REGION

Configurar o Memorystore para Redis

Para configurar o Redis, você precisa das seguintes variáveis de ambiente:

  • VPC_CONNECTOR_NAME: o nome do seu conector de acesso VPC sem servidor para conectar serviços do Cloud Run ao Memorystore para Redis. Valor recomendado: aa-integration-vpc.
  • VPC_NETWORK: a rede VPC a que seu conector de acesso VPC sem servidor será anexado. O valor deve ser default se você não configurar a VPC para seu projeto Google Cloud .
  • VPC_SUBNET: o nome da rede VPC autorizada a que a instância do Redis está anexada. O valor será default se você não tiver personalizado as configurações da rede VPC.
  • REDIS_IP_RANGE: uma rede IP interna não reservada para seu conector de acesso VPC sem servidor. É necessário ter /28 de espaço não alocado. Valor recomendado: 10.8.0.0/28 (esse valor funciona na maioria dos novos projetos).
  • REDIS_INSTANCE_ID: um nome para a instância do Redis. Valor recomendado: aa-integration-redis.

Criar uma instância do Redis na região dos serviços do Cloud Run

Execute este comando:

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

É possível se conectar a uma instância do Redis a partir do Cloud Run usando a saída direta ou o acesso VPC sem servidor.

Crie um conector de acesso VPC sem servidor {:#create-svpca-connector} (opcional)

Agora, isso é opcional se os clientes escolherem o Direct Egress. Se você escolher o acesso VPC sem servidor, crie um conector de acesso VPC sem servidor. Para mais detalhes sobre esta etapa, consulte o tutorial do Cloud Run.

Verifique se a API de acesso VPC sem servidor está ativada para seu projeto:

$ gcloud services enable vpcaccess.googleapis.com

Crie um conector de acesso VPC sem servidor com um intervalo de IP personalizado:

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

Salve o host e a porta do Redis como variáveis de ambiente

  • Defina o endereço IP da sua instância do Redis como a variável de ambiente REDIS_HOST.
  • Defina o número da porta da instância do Redis como a variável de ambiente REDIS_PORT.

Implantar o serviço de conector da UI

Para o serviço de conector da UI, você precisa das seguintes variáveis de ambiente:

  • CONNECTOR_SERVICE_NAME: o nome do serviço do Cloud Run do seu conector de interface. Valor recomendado: ui-connector.
  • CONNECTOR_IMAGE_NAME: o nome da imagem do serviço do conector de UI. Pode ser igual a CONNECTOR_SERVICE_NAME. Valor recomendado: ui-connector.

Compilar a imagem Docker

Na pasta /ui-connector, execute o seguinte comando:

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

Implantar o conector de interface no Cloud Run

Na pasta /ui-connector, execute o seguinte comando:

  • Se você estiver usando a saída direta para se conectar ao Redis.
$ gcloud run deploy $CONNECTOR_IMAGE_NAME \
--image gcr.io/$GCP_PROJECT_ID/$CONNECTOR_IMAGE_NAME \
--platform managed \
--service-account=$CONNECTOR_SERVICE_ACCOUNT_NAME \
--allow-unauthenticated \
--timeout 3600 \
--region $SERVICE_REGION \
--network $VPC_NETWORK \
--subnet $VPC_SUBNET \
--clear-vpc-connector \
--min-instances=1 \
--set-env-vars REDISHOST=$REDIS_HOST,REDISPORT=$REDIS_PORT,GCP_PROJECT_ID=$GCP_PROJECT_ID,AUTH_OPTION=$AUTH_OPTION \
--update-secrets=/secret/jwt_secret_key=${JWT_SECRET_NAME}:latest
  • Se você estiver usando um conector de acesso VPC sem servidor criado para a conexão do Redis.
$ gcloud run deploy $CONNECTOR_IMAGE_NAME \
--image gcr.io/$GCP_PROJECT_ID/$CONNECTOR_IMAGE_NAME \
--platform managed \
--service-account=$CONNECTOR_SERVICE_ACCOUNT_NAME \
--allow-unauthenticated \
--timeout 3600 \
--region $SERVICE_REGION \
--vpc-connector $VPC_CONNECTOR_NAME \
--clear-network \
--min-instances=1 \
--no-cpu-throttling \
--set-env-vars REDISHOST=$REDIS_HOST,REDISPORT=$REDIS_PORT,GCP_PROJECT_ID=$GCP_PROJECT_ID,AUTH_OPTION=$AUTH_OPTION \
--update-secrets=/secret/jwt_secret_key=${JWT_SECRET_NAME}:latest

Anote o URL do serviço do conector de interface implantado, que será usado pelos clientes (desktops de agentes).

Implantar o serviço de interceptor do Cloud Pub/Sub

Para o serviço interceptor do Pub/Sub, você precisa das seguintes variáveis de ambiente:

  • INTERCEPTOR_SERVICE_NAME: o nome do serviço do Cloud Run do seu interceptor do Cloud Pub/Sub. Valor recomendado: cloud-pubsub-interceptor.
  • INTERCEPTOR_IMAGE_NAME: o nome da imagem do seu serviço de interceptor do Cloud Pub/Sub. Pode ser igual a INTERCEPTOR_SERVICE_NAME. Valor recomendado: cloud-pubsub-interceptor.
  • INTERCEPTOR_SERVICE_ACCOUNT_NAME: a conta de serviço do ambiente de execução do interceptor do Cloud Pub/Sub.

Compilar a imagem Docker

Na pasta /cloud-pubsub-interceptor, execute o seguinte comando: 

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

Implantar o interceptor do Pub/Sub no Cloud Run

Na pasta /cloud-pubsub-interceptor, execute o seguinte comando:

  • Se você estiver usando a saída direta para se conectar ao Redis.
$ 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 \
--network $VPC_NETWORK \
--subnet $VPC_SUBNET \
--clear-vpc-connector \
--ingress=internal \
--min-instances=1 \
--no-cpu-throttling \
# 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
  • Se você estiver usando um conector de acesso VPC sem servidor criado para a conexão do Redis.
$ 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 \
--clear-network \
--ingress=internal \
--min-instances=1 \
# 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

Salvar o URL implantado

Defina o URL implantado como a variável de ambiente INTERCEPTOR_SERVICE_URL.

Configurar assinaturas do Cloud Pub/Sub

As assinaturas do Cloud Pub/Sub usam o seguinte:

  • Tópicos
  • Perfil de conversa
  • Conta de serviço
  • Permissão da conta de serviço para o serviço de interceptor

Criar tópicos do Cloud Pub/Sub

Crie um tópico do Cloud Pub/Sub para cada tipo de notificação de evento que você precisa do Dialogflow. Os tipos de notificação de evento disponíveis são:

  • Novos eventos de sugestão: eventos enviados quando novas sugestões do Assistente de IA estão disponíveis (por exemplo, novas respostas rápidas inteligentes em resposta a uma declaração do cliente).
  • Novos eventos de mensagem: eventos enviados sempre que uma nova declaração é reconhecida de um agente ou cliente (por exemplo, o cliente diz Hi).
  • Novos eventos do ciclo de vida da conversa: eventos enviados para determinadas mudanças no ciclo de vida da conversa (por exemplo, quando uma conversa é iniciada ou concluída).
  • Novos eventos de notificação de resultado de reconhecimento: eventos enviados quando uma transcrição intermediária é reconhecida de um agente ou cliente (por exemplo, o cliente diz Hi, how can I help you?, uma transcrição intermediária é Hi how can enquanto o cliente está falando).

Anote o ID e o nome do tópico para implantação posterior do back-end.

Configurar um perfil de conversa

Configure um perfil de conversa com os tópicos do Cloud Pub/Sub que você criou na etapa anterior.

  • Ao criar um perfil de conversa, selecione Notificações do Pub/Sub e depois Ativar notificações do Pub/Sub. Depois de ativar, marque as caixas ao lado dos tipos de notificações que você quer ativar e insira o ID do tópico associado do Cloud Pub/Sub.
  • Selecione JSON como o formato de mensagem para cada tópico.

Criar uma conta de serviço para a identidade de assinatura do Pub/Sub

Crie uma conta de serviço que represente a identidade da assinatura do Pub/Sub usando o seguinte comando:

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

Conceda à conta de serviço permissão para invocar o serviço de interceptor

Execute este 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

Criar assinaturas do Cloud Pub/Sub para tópicos

Para cada tópico criado, é necessário criar uma assinatura correspondente do Cloud Pub/Sub.

Novos eventos de sugestão

Substitua your-new-suggestion-topic-id pelo tópico do Cloud Pub/Sub que você configurou para novas sugestões:

$ 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
Novos eventos de mensagem

Substitua your-new-message-event-topic-id pelo tópico do Cloud Pub/Sub que você configurou para novos eventos de mensagem:

$ 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 de ciclo de vida da conversa

Substitua your-conversation-lifecycle-event-topic pelo tópico do Cloud Pub/Sub que você configurou para novos eventos do ciclo de vida da conversa:

$ 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
Novos eventos de notificação de resultado de reconhecimento
$ 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