Aplicativo RAG agêntico do AlloyDB com a MCP Toolbox

1. Introdução

Neste codelab, você vai aprender a criar um cluster do AlloyDB, implantar a caixa de ferramentas do MCP e configurá-la para usar o AlloyDB como uma fonte de dados. Em seguida, você vai criar um aplicativo interativo de RAG de exemplo que usa a caixa de ferramentas implantada para fundamentar as solicitações.

Confira mais informações sobre a caixa de ferramentas do MCP na página de documentação e o aplicativo de exemplo Cymbal Air aqui.

Este laboratório faz parte de uma coleção dedicada aos recursos de IA do AlloyDB. Leia mais na página da AlloyDB AI na documentação e confira outros laboratórios.

Pré-requisitos

• Conhecimentos básicos sobre o console do Google Cloud
• Habilidades básicas na interface de linha de comando e no Google Cloud Shell

O que você vai aprender

• Como implantar um cluster do AlloyDB com a integração da Vertex AI
• Como se conectar ao AlloyDB
• Como configurar e implantar o serviço da caixa de ferramentas do MCP
• Como implantar um aplicativo de amostra com o serviço implantado

O que é necessário

• Uma conta e um projeto do Google Cloud
• Um navegador da Web, como o Chrome

2. Configuração e requisitos

Configuração de ambiente autoguiada

1. Faça login no Console do Google Cloud e crie um novo projeto ou reutilize um existente. Crie uma conta do Gmail ou do Google Workspace, se ainda não tiver uma.

• O Nome do projeto é o nome de exibição para os participantes do projeto. É uma string de caracteres não usada pelas APIs do Google e pode ser atualizada quando você quiser.
• O ID do projeto precisa ser exclusivo em todos os projetos do Google Cloud e não pode ser mudado após a definição. O console do Cloud gera automaticamente uma string exclusiva. Em geral, não importa o que seja. Na maioria dos codelabs, é necessário fazer referência ao ID do projeto, normalmente identificado como PROJECT_ID. Se você não gostar do ID gerado, crie outro aleatório. Se preferir, teste o seu e confira se ele está disponível. Ele não pode ser mudado após essa etapa e permanece durante o projeto.
• Para sua informação, há um terceiro valor, um Número do projeto, que algumas APIs usam. Saiba mais sobre esses três valores na documentação.

Atenção: o ID do projeto é globalmente exclusivo e não pode ser usado por outras pessoas após a seleção. Você é o único usuário com esse ID. Mesmo que um projeto seja excluído, o ID não poderá ser usado novamente.

Observação: se você usa uma conta do Gmail, defina o local padrão como Sem organização. Se você usa uma conta do Google Workspace, escolha um local adequado para a organização.

2. Em seguida, ative o faturamento no console do Cloud para usar os recursos/APIs do Cloud. A execução deste codelab não vai ser muito cara, se tiver algum custo. Para encerrar os recursos e evitar cobranças além deste tutorial, exclua os recursos criados ou exclua o projeto. Novos usuários do Google Cloud estão qualificados para o programa de US$ 300 de avaliação sem custos.

Inicie o Cloud Shell

Embora o Google Cloud e o Spanner possam ser operados remotamente do seu laptop, neste codelab usaremos o Google Cloud Shell, um ambiente de linha de comando executado no Cloud.

No Console do Google Cloud, clique no ícone do Cloud Shell na barra de ferramentas superior à direita:

O provisionamento e a conexão com o ambiente levarão apenas alguns instantes para serem concluídos: Quando o processamento for concluído, você verá algo como:

Essa máquina virtual contém todas as ferramentas de desenvolvimento necessárias. Ela oferece um diretório principal persistente de 5 GB, além de ser executada no Google Cloud. Isso aprimora o desempenho e a autenticação da rede. Neste codelab, todo o trabalho pode ser feito com um navegador. Você não precisa instalar nada.

3. Antes de começar

Ativar API

Saída:

Alguns recursos ativados vão ter custos se você não usar o nível promocional. Em circunstâncias normais, se todos os recursos forem destruídos após a conclusão do laboratório, o custo deles não vai exceder US$ 5. É recomendável conferir o faturamento e confirmar se o exercício é adequado para você.

No Cloud Shell, verifique se o ID do projeto está configurado:

Normalmente, o ID do projeto é mostrado entre parênteses no prompt de comando do Cloud Shell, como mostra a figura:

gcloud config set project [YOUR-PROJECT-ID]

Defina a variável de ambiente PROJECT_ID para o ID do projeto do Google Cloud:

PROJECT_ID=$(gcloud config get-value project)

Ative todos os serviços necessários:

gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       run.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com

Resultado esperado

student@cloudshell:~ (gleb-test-short-004)$ gcloud services enable alloydb.googleapis.com \
                       compute.googleapis.com \
                       cloudresourcemanager.googleapis.com \
                       servicenetworking.googleapis.com \
                       vpcaccess.googleapis.com \
                       aiplatform.googleapis.com \
                       cloudbuild.googleapis.com \
                       artifactregistry.googleapis.com \
                       run.googleapis.com \
                       iam.googleapis.com \
                       secretmanager.googleapis.com
Operation "operations/acf.p2-404051529011-664c71ad-cb2b-4ab4-86c1-1f3157d70ba1" finished successfully.

4. Implantar cluster do AlloyDB

Crie um cluster do AlloyDB e uma instância principal. O procedimento a seguir descreve como criar um cluster e uma instância do AlloyDB usando o SDK do Google Cloud. Se preferir a abordagem do console, siga a documentação aqui.

Antes de criar um cluster do AlloyDB, é necessário ter um intervalo de IP privado disponível na VPC para ser usado pela instância futura do AlloyDB. Se não tivermos, precisamos criar e atribuir para uso por serviços internos do Google. Depois disso, será possível criar o cluster e a instância.

Criar um intervalo de IP privado

Observação:essa etapa é necessária apenas se você ainda não tiver um intervalo de IP particular não usado atribuído para trabalhar com serviços internos do Google.

É preciso configurar o Acesso a serviços particulares na VPC para o AlloyDB. Vamos supor que o projeto tem uma rede VPC "padrão" a ser usada para todas as ações.

Crie o intervalo de IP privado:

gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default

Crie uma conexão privada com o intervalo de IP alocado:

gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default

Observação: a execução do segundo comando leva alguns minutos.

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ gcloud compute addresses create psa-range \
    --global \
    --purpose=VPC_PEERING \
    --prefix-length=24 \
    --description="VPC private service access" \
    --network=default
Created [https://www.googleapis.com/compute/v1/projects/test-project-402417/global/addresses/psa-range].

student@cloudshell:~ (test-project-402417)$ gcloud services vpc-peerings connect \
    --service=servicenetworking.googleapis.com \
    --ranges=psa-range \
    --network=default
Operation "operations/pssn.p24-4470404856-595e209f-19b7-4669-8a71-cbd45de8ba66" finished successfully.

student@cloudshell:~ (test-project-402417)$

Criar cluster do AlloyDB

Nesta seção, vamos criar um cluster do AlloyDB na região us-central1.

Defina a senha do usuário postgres. Você pode definir sua própria senha ou usar uma função aleatória para gerar uma.

export PGPASSWORD=`openssl rand -hex 12`

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ export PGPASSWORD=`openssl rand -hex 12`

Anote a senha do PostgreSQL para uso futuro.

echo $PGPASSWORD

Você vai precisar dessa senha no futuro para se conectar à instância como o usuário postgres. Recomendamos que você anote ou copie em algum lugar para usar depois.

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ echo $PGPASSWORD
bbefbfde7601985b0dee5723

Criar um cluster de teste sem custo financeiro

Se você nunca usou o AlloyDB, crie um cluster de teste sem custo financeiro:

Defina a região e o nome do cluster do AlloyDB. Vamos usar a região us-central1 e alloydb-aip-01 como nome do cluster:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01

Execute o comando para criar o cluster:

gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION \
    --subscription-type=TRIAL

Saída esperada do console:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION \
    --subscription-type=TRIAL
Operation ID: operation-1697655441138-6080235852277-9e7f04f5-2012fce4
Creating cluster...done.                                                                                                                                                                                                                                                           

Crie uma instância principal do AlloyDB para o cluster na mesma sessão do Cloud Shell. Se você se desconectar, será necessário definir as variáveis de ambiente de região e nome do cluster novamente.

Observação:a criação da instância geralmente leva de 6 a 10 minutos para ser concluída.

gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=8 \
    --region=$REGION \
    --cluster=$ADBCLUSTER

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=8 \
    --region=$REGION \
    --availability-type ZONAL \
    --cluster=$ADBCLUSTER
Operation ID: operation-1697659203545-6080315c6e8ee-391805db-25852721
Creating instance...done.                                                                                                                                                                                                                                                     

Criar cluster padrão do AlloyDB

Se não for seu primeiro cluster do AlloyDB no projeto, crie um cluster padrão.

Defina a região e o nome do cluster do AlloyDB. Vamos usar a região us-central1 e alloydb-aip-01 como nome do cluster:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01

Execute o comando para criar o cluster:

gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION

Saída esperada do console:

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
gcloud alloydb clusters create $ADBCLUSTER \
    --password=$PGPASSWORD \
    --network=default \
    --region=$REGION 
Operation ID: operation-1697655441138-6080235852277-9e7f04f5-2012fce4
Creating cluster...done.                                                                                                                                                                                                                                                           

Crie uma instância principal do AlloyDB para o cluster na mesma sessão do Cloud Shell. Se você se desconectar, será necessário definir as variáveis de ambiente de região e nome do cluster novamente.

Observação:a criação da instância geralmente leva de 6 a 10 minutos para ser concluída.

gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --cluster=$ADBCLUSTER

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ gcloud alloydb instances create $ADBCLUSTER-pr \
    --instance-type=PRIMARY \
    --cpu-count=2 \
    --region=$REGION \
    --availability-type ZONAL \
    --cluster=$ADBCLUSTER
Operation ID: operation-1697659203545-6080315c6e8ee-391805db-25852721
Creating instance...done.                                                                                                                                                                                                                                                     

Conceder as permissões necessárias ao AlloyDB

Adicione permissões da Vertex AI ao agente de serviço do AlloyDB.

Abra outra guia do Cloud Shell pelo sinal "+" na parte superior.

Na nova guia do Cloud Shell, execute:

PROJECT_ID=$(gcloud config get-value project)
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Saída esperada do console:

student@cloudshell:~ (test-project-001-402417)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-11039]
student@cloudshell:~ (test-project-001-402417)$ gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
Updated IAM policy for project [test-project-001-402417].
bindings:
- members:
  - serviceAccount:[e-mail]
  role: roles/aiplatform.user
- members:
...
etag: BwYIEbe_Z3U=
version: 1
 

Feche a guia pelo comando de execução "sair" na guia:

exit

5. Preparar a máquina virtual do GCE

Vamos usar uma VM do Google Compute Engine (GCE) como plataforma para trabalhar com o banco de dados e implantar diferentes partes do aplicativo de exemplo. O uso de uma VM oferece mais flexibilidade nos componentes instalados e acesso direto ao IP privado do AlloyDB para etapas de preparação de dados.

Criar uma conta de serviço

Como vamos usar a VM para implantar a caixa de ferramentas do MCP como um serviço e implantar ou hospedar o aplicativo de amostra, a primeira etapa é criar uma conta de serviço do Google (GSA). A GSA vai ser usada pela VM do GCE, e é preciso conceder os privilégios necessários para trabalhar com outros serviços.

No Cloud Shell, execute:

PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts create compute-aip --project $PROJECT_ID

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/cloudbuild.builds.editor"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/artifactregistry.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/storage.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/run.admin"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/iam.serviceAccountUser"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.viewer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"

gcloud projects add-iam-policy-binding $PROJECT_ID \
    --member serviceAccount:compute-aip@$PROJECT_ID.iam.gserviceaccount.com \
    --role roles/secretmanager.admin

Implantar a VM do GCE

Crie uma VM do GCE na mesma região e VPC que o cluster do AlloyDB.

No Cloud Shell, execute:

ZONE=us-central1-a
PROJECT_ID=$(gcloud config get-value project)
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-12 AND family!=debian-12-arm64" --format="value(name)") \
    --scopes=https://www.googleapis.com/auth/cloud-platform \
    --service-account=compute-aip@$PROJECT_ID.iam.gserviceaccount.com

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ ZONE=us-central1-a
PROJECT_ID=$(gcloud config get-value project)
gcloud compute instances create instance-1 \
    --zone=$ZONE \
    --create-disk=auto-delete=yes,boot=yes,image=projects/debian-cloud/global/images/$(gcloud compute images list --filter="family=debian-12 AND family!=debian-12-arm64" --format="value(name)") \
    --scopes=https://www.googleapis.com/auth/cloud-platform \
    --service-account=compute-aip@$PROJECT_ID.iam.gserviceaccount.com
Your active configuration is: [cloudshell-10282]
Created [https://www.googleapis.com/compute/v1/projects/gleb-test-short-002-470613/zones/us-central1-a/instances/instance-1].
NAME: instance-1
ZONE: us-central1-a
MACHINE_TYPE: n1-standard-1
PREEMPTIBLE: 
INTERNAL_IP: 10.128.0.2
EXTERNAL_IP: 34.28.55.32
STATUS: RUNNING

Instalar o cliente Postgres

Instale o software do cliente PostgreSQL na VM implantada.

Conecte-se à VM:

Observação: a primeira conexão SSH com a VM pode levar mais tempo, porque o processo inclui a criação da Chave RSA para conexão segura e a propagação da parte pública da chave para o projeto.

gcloud compute ssh instance-1 --zone=us-central1-a

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ gcloud compute ssh instance-1 --zone=us-central1-a
Updating project ssh metadata...working..Updated [https://www.googleapis.com/compute/v1/projects/test-project-402417].                                                                                                                                                         
Updating project ssh metadata...done.                                                                                                                                                                                                                                              
Waiting for SSH key to propagate.
Warning: Permanently added 'compute.5110295539541121102' (ECDSA) to the list of known hosts.
Linux instance-1 5.10.0-26-cloud-amd64 #1 SMP Debian 5.10.197-1 (2023-09-29) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
student@instance-1:~$ 

Instale o comando em execução do software na VM:

sudo apt-get update
sudo apt-get install --yes postgresql-client

Saída esperada do console:

student@instance-1:~$ sudo apt-get update
sudo apt-get install --yes postgresql-client
Get:1 file:/etc/apt/mirrors/debian.list Mirrorlist [30 B]
Get:4 file:/etc/apt/mirrors/debian-security.list Mirrorlist [39 B]
Hit:7 https://packages.cloud.google.com/apt google-compute-engine-bookworm-stable InRelease
Get:8 https://packages.cloud.google.com/apt cloud-sdk-bookworm InRelease [1652 B]
Get:2 https://deb.debian.org/debian bookworm InRelease [151 kB]
Get:3 https://deb.debian.org/debian bookworm-updates InRelease [55.4 kB]
...redacted...
update-alternatives: using /usr/share/postgresql/15/man/man1/psql.1.gz to provide /usr/share/man/man1/psql.1.gz (psql.1.gz) in auto mode
Setting up postgresql-client (15+248) ...
Processing triggers for man-db (2.11.2-2) ...
Processing triggers for libc-bin (2.36-9+deb12u7) ...

Conectar-se à instância do AlloyDB

Conecte-se à instância principal pela VM com psql.

Continue com a sessão SSH aberta na VM. Em caso de desconexão, conecte-se de novo com o mesmo comando acima.

Use o $PGASSword anotado e o nome do cluster para se conectar ao AlloyDB pela VM do GCE:

export PGPASSWORD=<Noted password>

PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres sslmode=require"

Saída esperada do console:

student@instance-1:~$ PROJECT_ID=$(gcloud config get-value project)
REGION=us-central1
ADBCLUSTER=alloydb-aip-01
INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres sslmode=require"
psql (15.13 (Debian 15.13-0+deb12u1), server 16.8)
WARNING: psql major version 15, server major version 16.
         Some psql features might not work.
SSL connection (protocol: TLSv1.3, cipher: TLS_AES_256_GCM_SHA384, compression: off)
Type "help" for help.

postgres=>

Saia da sessão do psql, mas mantenha a conexão SSH ativa:

exit

Saída esperada do console:

postgres=> exit
student@instance-1:~$ 

6. Inicializar o banco de dados

Vamos usar a VM de cliente como plataforma para preencher o banco de dados com dados e hospedar o aplicativo. A primeira etapa é criar um banco de dados para preencher com dados.

Criar banco de dados

Crie um banco de dados com o nome "assistantdemo".

Na sessão da VM do GCE, execute:

Observação: se a sessão SSH tiver sido encerrada, você precisará redefinir as variáveis de ambiente, como as seguintes:

export PGPASSWORD=<The noted AlloyDB password>

export REGION=us-central1

export ADBCLUSTER=alloydb-aip-01

export INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")

psql "host=$INSTANCE_IP user=postgres" -c "CREATE DATABASE assistantdemo"  

Saída esperada do console:

student@instance-1:~$ psql "host=$INSTANCE_IP user=postgres" -c "CREATE DATABASE assistantdemo"
CREATE DATABASE
student@instance-1:~$  

Preparar o ambiente Python

Para continuar, vamos usar scripts Python preparados do repositório do GitHub, mas antes é preciso instalar o software necessário.

Na VM do GCE, execute:

sudo apt install -y python3.11-venv git
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip

Saída esperada do console:

student@instance-1:~$ sudo apt install -y python3.11-venv git
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
The following additional packages will be installed:
  git-man liberror-perl patch python3-distutils python3-lib2to3 python3-pip-whl python3-setuptools-whl
Suggested packages:
  git-daemon-run | git-daemon-sysvinit git-doc git-email git-gui gitk gitweb git-cvs git-mediawiki git-svn ed diffutils-doc
The following NEW packages will be installed:
  git git-man liberror-perl patch python3-distutils python3-lib2to3 python3-pip-whl python3-setuptools-whl python3.11-venv
0 upgraded, 9 newly installed, 0 to remove and 2 not upgraded.
Need to get 12.4 MB of archives.
After this operation, 52.2 MB of additional disk space will be used.
Get:1 file:/etc/apt/mirrors/debian.list Mirrorlist [30 B]
...redacted...
Installing collected packages: pip
  Attempting uninstall: pip
    Found existing installation: pip 23.0.1
    Uninstalling pip-23.0.1:
      Successfully uninstalled pip-23.0.1
Successfully installed pip-24.0
(.venv) student@instance-1:~$

Verifique a versão do Python.

Na VM do GCE, execute:

python -V

Saída esperada do console:

(.venv) student@instance-1:~$ python -V
Python 3.11.2
(.venv) student@instance-1:~$ 

Instalar a caixa de ferramentas do MCP localmente

O MCP Toolbox for Databases (mais adiante no texto, caixa de ferramentas do MCP ou caixa de ferramentas) é um servidor MCP de código aberto que funciona com diferentes fontes de dados. Ele ajuda você a desenvolver ferramentas mais rapidamente, fornecendo um nível de abstração para diferentes fontes de dados e adicionando recursos como autenticação e agrupamento de conexões. Leia sobre todos os recursos na página oficial.

Vamos usar a caixa de ferramentas do MCP para iniciar o conjunto de dados de amostra e, mais tarde, como servidor do MCP para processar solicitações de fonte de dados do aplicativo durante o fluxo de geração aumentada por recuperação (RAG).

Vamos instalar a caixa de ferramentas do MCP localmente para preencher o banco de dados assistantdemo.

Na VM do GCE, execute:

export VERSION=0.16.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox

Saída esperada do console:

(.venv) student@instance-1:~$ export VERSION=0.16.0
curl -O https://storage.googleapis.com/genai-toolbox/v$VERSION/linux/amd64/toolbox
chmod +x toolbox
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  133M  100  133M    0     0   158M      0 --:--:-- --:--:-- --:--:--  158M

Executar a caixa de ferramentas para inicialização de dados

Na VM do GCE, execute:

Observação:se a sessão SSH tiver sido encerrada por inatividade ou qualquer outro motivo, você precisará definir variáveis de ambiente, como:

export PGPASSWORD=<Noted password>

REGION=us-central1

ADBCLUSTER=alloydb-aip-01

INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")

Exporte variáveis de ambiente para preencher o banco de dados:

export ALLOYDB_POSTGRES_PROJECT=$(gcloud config get-value project)
export ALLOYDB_POSTGRES_REGION="us-central1"
export ALLOYDB_POSTGRES_CLUSTER="alloydb-aip-01"
export ALLOYDB_POSTGRES_INSTANCE="alloydb-aip-01-pr"
export ALLOYDB_POSTGRES_DATABASE="assistantdemo"
export ALLOYDB_POSTGRES_USER="postgres"
export ALLOYDB_POSTGRES_PASSWORD=$PGPASSWORD
export ALLOYDB_POSTGRES_IP_TYPE="private"

Inicie a caixa de ferramentas para a inicialização do banco de dados. Ele vai iniciar o processo localmente, o que vai ajudar você a se conectar perfeitamente ao banco de dados de destino no AlloyDB para preenchê-lo com dados de amostra.

./toolbox --prebuilt alloydb-postgres

Saída esperada do console. Na última linha da saída, você vai encontrar "Server ready to serve!":

student@instance-1:~$ cexport ALLOYDB_POSTGRES_PROJECT=$PROJECT_ID
export ALLOYDB_POSTGRES_REGION="us-central1"
export ALLOYDB_POSTGRES_CLUSTER="alloydb-aip-01"
export ALLOYDB_POSTGRES_INSTANCE="alloydb-aip-01-pr"
export ALLOYDB_POSTGRES_DATABASE="assistantdemo"
export ALLOYDB_POSTGRES_USER="postgres"
export ALLOYDB_POSTGRES_PASSWORD=$PGPASSWORD
export ALLOYDB_POSTGRES_IP_TYPE="private"
student@instance-1:~$ ./toolbox --prebuilt alloydb-postgres
2025-09-02T18:30:58.957655886Z INFO "Using prebuilt tool configuration for alloydb-postgres" 
2025-09-02T18:30:59.507306664Z INFO "Initialized 1 sources." 
2025-09-02T18:30:59.50748379Z INFO "Initialized 0 authServices." 
2025-09-02T18:30:59.507618807Z INFO "Initialized 2 tools." 
2025-09-02T18:30:59.507726704Z INFO "Initialized 2 toolsets." 
2025-09-02T18:30:59.508258894Z INFO "Server ready to serve!" 

Não saia nem feche esta guia do Cloud Shell até que o preenchimento de dados seja concluído.

Preencher o banco de dados

Abra outra guia do Cloud Shell pelo sinal "+" na parte superior.

E conecte-se à VM instance-1:

gcloud compute ssh instance-1 --zone=us-central1-a

Saída esperada do console:

student@cloudshell:~ (test-project-402417)$ gcloud compute ssh instance-1 --zone=us-central1-a
Linux instance-1 6.1.0-37-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.140-1 (2025-05-22) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Tue Sep  2 21:44:07 2025 from 35.229.111.9
student@instance-1:~$ 

Clone o repositório do GitHub com o código do serviço de recuperação e do aplicativo de amostra.

Na VM do GCE, execute:

git clone  https://github.com/GoogleCloudPlatform/cymbal-air-toolbox-demo.git

Saída esperada do console:

student@instance-1:~$ git clone  https://github.com/GoogleCloudPlatform/cymbal-air-toolbox-demo.git
Cloning into 'cymbal-air-toolbox-demo'...
remote: Enumerating objects: 3481, done.
remote: Counting objects: 100% (47/47), done.
remote: Compressing objects: 100% (41/41), done.
remote: Total 3481 (delta 16), reused 7 (delta 5), pack-reused 3434 (from 3)
Receiving objects: 100% (3481/3481), 57.96 MiB | 6.04 MiB/s, done.
Resolving deltas: 100% (2549/2549), done.
student@instance-1:~

Preste atenção se houver erros.

Prepare o ambiente Python e instale os pacotes de requisitos:

source .venv/bin/activate
cd cymbal-air-toolbox-demo
pip install -r requirements.txt

Defina o caminho do Python para a pasta raiz do repositório e execute o script para preencher o banco de dados com o conjunto de dados de exemplo. O primeiro comando adiciona um caminho aos nossos módulos Python ao ambiente, e o segundo preenche o banco de dados com os dados.

export PYTHONPATH=$HOME/cymbal-air-toolbox-demo
python data/run_database_init.py

Saída esperada do console(editada). Você vai ver "database init done" no final:

student@instance-1:~$ source .venv/bin/activate
(.venv) student@instance-1:~$ 
(.venv) student@instance-1:~$ cd cymbal-air-toolbox-demo/
(.venv) student@instance-1:~/cymbal-air-toolbox-demo$ pip install -r requirements.txt
python run_database_init.py
Collecting fastapi==0.115.0 (from -r requirements.txt (line 1))
  Downloading fastapi-0.115.0-py3-none-any.whl.metadata (27 kB)
Collecting google-auth==2.40.3 (from -r requirements.txt (line 2))
  Downloading google_auth-2.40.3-py2.py3-none-any.whl.metadata (6.2 kB)
Collecting google-cloud-aiplatform==1.97.0 (from google-cloud-aiplatform[evaluation]==1.97.0->-r requirements.txt (line 3))
  Downloading google_cloud_aiplatform-1.97.0-py2.py3-none-any.whl.metadata (36 kB)
Collecting itsdangerous==2.2.0 (from -r requirements.txt (line 4))
  Downloading itsdangerous-2.2.0-py3-none-any.whl.metadata (1.9 kB)
Collecting jinja2==3.1.5 (from -r requirements.txt (line 5))
  Downloading jinja2-3.1.5-py3-none-any.whl.metadata (2.6 kB)
Collecting langchain-community==0.3.25 (from -r requirements.txt (line 6))
  Downloading langchain_community-0.3.25-py3-none-any.whl.metadata (2.9 kB)
Collecting langchain==0.3.25 (from -r requirements.txt (line 7))
...

(.venv) student@instance-1:~/cymbal-air-toolbox-demo$ 
(.venv) student@instance-1:~/cymbal-air-toolbox-demo$ export PYTHONPATH=$HOME/cymbal-air-toolbox-demo
python data/run_database_init.py
Airports table initialized
Amenities table initialized
Flights table initialized
Tickets table initialized
Policies table initialized
database init done.
(.venv) student@instance-1:~/cymbal-air-toolbox-demo$ 

Você já pode fechar esta guia.

Na sessão da VM, execute:

exit

Na sessão do Cloud Shell, pressione ctrl+d ou execute :

exit

Na primeira guia com a caixa de ferramentas do MCP em execução, pressione ctrl+c para sair da sessão em execução.

O banco de dados foi preenchido com dados de amostra para o aplicativo.

Para verificar, conecte-se ao banco de dados e confira o número de linhas na tabela "airports". Você pode usar o utilitário psql, como já fizemos, ou o AlloyDB Studio . Confira como verificar usando psql

Na sessão SSH da VM instance-1, execute:

export PGPASSWORD=<Noted AlloyDB password>

REGION=us-central1
ADBCLUSTER=alloydb-aip-01
INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres dbname=assistantdemo" -c "SELECT COUNT(*) FROM airports"  

Saída esperada do console:

student@instance-1:~$ REGION=us-central1
ADBCLUSTER=alloydb-aip-01
INSTANCE_IP=$(gcloud alloydb instances describe $ADBCLUSTER-pr --cluster=$ADBCLUSTER --region=$REGION --format="value(ipAddress)")
psql "host=$INSTANCE_IP user=postgres dbname=assistantdemo" -c "SELECT COUNT(*) FROM airports"
 count 
-------
  7698
(1 row)

O banco de dados está pronto, e podemos passar para a implantação do MCP Toolbox.

7. Implantar a MCP Toolbox no Cloud Run

Agora podemos implantar a MCP Toolbox no Cloud Run. Há diferentes maneiras de implantar a caixa de ferramentas do MCP. A maneira mais simples é executar na linha de comando, mas, se quisermos ter um serviço escalonável e confiável, o Cloud Run é uma solução melhor.

Preparar ID do cliente

Para usar a funcionalidade de reserva do aplicativo, precisamos preparar o ID do cliente OAuth 2.0 usando o console do Cloud. Sem ele, não é possível fazer login no aplicativo com nossas credenciais do Google para fazer uma reserva e registrar a reserva no banco de dados.

No console do Cloud, acesse "APIs e serviços" e clique em "Tela de permissão OAuth". Aqui está um link para a página. Isso vai abrir a página de visão geral do OAuth, onde clicamos em "Começar".

Na próxima página, forneça o nome do aplicativo, o e-mail de suporte ao usuário e clique em "Próxima".

Na próxima tela, escolha "Interno" para o aplicativo e clique em "Próxima" novamente.

Em seguida, forneça novamente o e-mail de contato e clique em "Próxima".

Em seguida, concordamos com as políticas dos serviços de API do Google e clicamos no botão "Criar".

Isso vai nos levar à página em que podemos criar um cliente OAuth.

Na tela, escolha "Aplicativo da Web" no menu suspenso, insira "Cymbal Air" como aplicativo e clique no botão "Adicionar URI".

Os URIs representam fontes confiáveis para o aplicativo e dependem de onde você está tentando acessar o aplicativo. Definimos "http://localhost:8081" como URI autorizado e "http://localhost:8081/login/google" como URI de redirecionamento. Esses valores funcionariam se você colocasse "http://localhost:8081" no navegador como um URI para conexão. Por exemplo, quando você se conecta por um túnel SSH do seu computador. Vou mostrar como fazer isso mais tarde.

Depois de clicar no botão "Criar", uma janela pop-up vai aparecer com as credenciais dos seus clientes. As credenciais serão registradas no sistema. Você sempre pode copiar o ID do cliente para usar quando iniciar o aplicativo.

Mais tarde, você vai saber onde fornecer esse ID do cliente.

Criar uma conta de serviço

Precisamos de uma conta de serviço dedicada para nosso serviço do Cloud Run com todos os privilégios necessários. Para nosso serviço, precisamos de acesso ao AlloyDB e ao Cloud Secret Manager. Quanto ao nome da conta de serviço, vamos usar toolbox-identity.

Abra outra guia do Cloud Shell pelo sinal "+" na parte superior.

Na nova guia do Cloud Shell, execute:

export PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts create toolbox-identity

gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/alloydb.client"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/serviceusage.serviceUsageConsumer"
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com" \
  --role="roles/secretmanager.secretAccessor"

Preste atenção se houver erros. O comando deve criar uma conta de serviço para o serviço do Cloud Run e conceder privilégios para trabalhar com o Secret Manager, o banco de dados e a Vertex AI.

Feche a guia pressionando ctrl+d ou executando o comando "exit" na guia:

exit

Preparar a configuração da caixa de ferramentas do MCP

Prepare o arquivo de configuração para a caixa de ferramentas do MCP. Você pode ler sobre todas as opções de configuração na documentação, mas aqui vamos usar o arquivo de exemplo tools.yaml e substituir alguns valores, como nome do cluster e da instância, senha do AlloyDB e ID do projeto, pelos nossos valores reais.

Exportar senha do AlloyDB:

export PGPASSWORD=<noted AlloyDB password>

Exporte o ID do cliente que preparamos na etapa anterior:

export CLIENT_ID=<noted OAuth 2.0 client ID for our application>

Prepare o arquivo de configuração.

PROJECT_ID=$(gcloud config get-value project)
ADBCLUSTER=alloydb-aip-01
sed -e "s/project: retrieval-app-testing/project: $(gcloud config get-value project)/g" \
-e "s/cluster: my-alloydb-cluster/cluster: $ADBCLUSTER/g" \
-e "s/instance: my-alloydb-instance/instance: $ADBCLUSTER-pr/g" \
-e "s/password: postgres/password: $PGPASSWORD\\n    ipType: private/g" \
-e "s/^ *clientId: .*/    clientId: $CLIENT_ID/g" \
cymbal-air-toolbox-demo/tools.yaml >~/tools.yaml

Se você analisar a seção do arquivo que define a fonte de dados de destino, verá que também adicionamos uma linha para usar o IP particular na conexão.

sources:
  my-pg-instance:
    kind: alloydb-postgres
    project: gleb-test-short-003-471020
    region: us-central1
    cluster: alloydb-aip-01
    instance: alloydb-aip-01-pr
    database: assistantdemo
    user: postgres
    password: L23F...
    ipType: private
authServices:
  my_google_service:
    kind: google
    clientId: 96828*******-***********.apps.googleusercontent.com

Crie um secret usando a configuração tools.yaml como origem.

No console SSH da VM, execute:

gcloud secrets create tools --data-file=tools.yaml

Saída esperada do console:

student@instance-1:~$ gcloud secrets create tools --data-file=tools.yaml
Created version [1] of the secret [tools].

Implantar a caixa de ferramentas do MCP como um serviço do Cloud Run

Agora está tudo pronto para implantar a caixa de ferramentas do MCP como um serviço no Cloud Run. Para testes locais, execute "./toolbox –tools-file=./tools.yaml", mas se quisermos que o aplicativo seja executado na nuvem, a implantação no Cloud Run faz muito mais sentido.

Na sessão SSH da VM, execute:

export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
gcloud run deploy toolbox \
    --image $IMAGE \
    --service-account toolbox-identity \
    --region us-central1 \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --network default \
    --subnet default \
    --no-allow-unauthenticated

Saída esperada do console:

student@instance-1:~$ export IMAGE=us-central1-docker.pkg.dev/database-toolbox/toolbox/toolbox:latest
gcloud run deploy toolbox \
    --image $IMAGE \
    --service-account toolbox-identity \
    --region us-central1 \
    --set-secrets "/app/tools.yaml=tools:latest" \
    --args="--tools-file=/app/tools.yaml","--address=0.0.0.0","--port=8080" \
    --network default \
    --subnet default \
    --no-allow-unauthenticated
Deploying container to Cloud Run service [toolbox] in project [gleb-test-short-002-470613] region [us-central1]
✓ Deploying new service... Done.                                                                                                                                                                                                
  ✓ Creating Revision...                                                                                                                                                                                                        
  ✓ Routing traffic...                                                                                                                                                                                                          
Done.                                                                                                                                                                                                                           
Service [toolbox] revision [toolbox-00001-l9c] has been deployed and is serving 100 percent of traffic.
Service URL: https://toolbox-868691532292.us-central1.run.app

student@instance-1:~$

Conferir o serviço

Agora é possível verificar se o serviço está ativo e se podemos acessar o endpoint. Usamos o utilitário gcloud para receber o endpoint do serviço de recuperação e o token de autenticação. Também é possível verificar o URI do serviço no console do Cloud.

Copie o valor e substitua no comando curl a parte "$(gcloud run services list –filter="(toolbox)" –format="value(URL)" .

Veja como conseguir o URL de forma dinâmica na linha de comando:

curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" $(gcloud  run services list --filter="(toolbox)" --format="value(URL)")

Saída esperada do console:

student@instance-1:~$ curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" $(gcloud  run services list --filter="(toolbox)" --format="value(URL)")
🧰 Hello, World! 🧰student@instance-1:~$

Se a mensagem "Hello World" for mostrada, significa que o serviço está funcionando e atendendo às solicitações.

8. Implantar o aplicativo de amostra

Agora que o serviço de recuperação está em execução, podemos implantar um aplicativo de amostra. O aplicativo representa um assistente de aeroporto on-line que pode fornecer informações sobre voos e aeroportos e até mesmo reservar um voo com base nos dados de voos e aeroportos do nosso banco de dados.

O aplicativo pode ser implantado localmente, em uma VM na nuvem ou em qualquer outro serviço, como o Cloud Run ou o Kubernetes. Aqui vamos mostrar como implantar na VM primeiro.

Prepare o ambiente

Vamos continuar trabalhando na VM usando a mesma sessão SSH. Para executar o aplicativo, precisamos de alguns módulos do Python, que já foram adicionados quando iniciamos o banco de dados. Vamos mudar para o ambiente virtual do Python e mudar nosso local para o diretório do app.

Na sessão SSH da VM, execute:

source ~/.venv/bin/activate
cd cymbal-air-toolbox-demo

Saída esperada (editada):

student@instance-1:~$ source ~/.venv/bin/activate
cd cymbal-air-toolbox-demo
(.venv) student@instance-1:~/cymbal-air-toolbox-demo$

Executar o aplicativo assistente

Antes de iniciar o aplicativo, é preciso configurar algumas variáveis de ambiente. A funcionalidade básica do aplicativo, como consulta de voos e comodidades do aeroporto, exige apenas TOOLBOX_URL, que aponta o aplicativo para o serviço de recuperação. Podemos fazer isso usando o comando gcloud .

Na sessão SSH da VM, execute:

export TOOLBOX_URL=$(gcloud  run services list --filter="(toolbox)" --format="value(URL)")

Saída esperada (editada):

student@instance-1:~/cymbal-air-toolbox-demo$ export BASE_URL=$(gcloud  run services list --filter="(toolbox)" --format="value(URL)")

Para usar recursos mais avançados do aplicativo, como reservar e alterar voos, precisamos fazer login com nossa Conta do Google. Para isso, precisamos fornecer a variável de ambiente CLIENT_ID usando o ID do cliente OAuth do capítulo "Preparar ID do cliente":

export CLIENT_ID=215....apps.googleusercontent.com

Saída esperada (editada):

student@instance-1:~/cymbal-air-toolbox-demo$ export CLIENT_ID=215....apps.googleusercontent.com

Agora podemos executar o aplicativo:

python run_app.py

Saída esperada:

student@instance-1:~/cymbal-air-toolbox-demo/llm_demo$ python run_app.py
INFO:     Started server process [2900]
INFO:     Waiting for application startup.
Loading application...
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8081 (Press CTRL+C to quit)

Conectar-se ao aplicativo

Há várias maneiras de se conectar ao aplicativo em execução na VM. Por exemplo, é possível abrir a porta 8081 na VM pelas regras de firewall na VPC ou criar um balanceador de carga com IP público. Vamos usar um túnel SSH para a VM, ou seja, converter a porta local 8080 para a porta da VM 8081.

Como se conectar de uma máquina local

Quando queremos nos conectar de uma máquina local, precisamos executar um túnel SSH. Isso pode ser feito usando gcloud compute ssh:

gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8081:localhost:8081

Saída esperada:

student-macbookpro:~ student$ gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8080:localhost:8081
Warning: Permanently added 'compute.7064281075337367021' (ED25519) to the list of known hosts.
Linux instance-1.us-central1-c.c.gleb-test-001.internal 6.1.0-21-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.90-1 (2024-05-03) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
student@instance-1:~$

Agora podemos abrir o navegador e usar http://localhost:8081 para se conectar ao aplicativo. A tela do aplicativo vai aparecer.

Como se conectar usando o Cloud Shell

Como alternativa, podemos usar o Google Cloud Shell para se conectar. Abra outra guia do Cloud Shell pelo sinal "+" na parte superior.

Na nova guia, execute o comando gcloud para conseguir o URI de origem e de redirecionamento do seu cliente da Web:

echo "origin:"; echo "https://8080-$WEB_HOST"; echo "redirect:"; echo "https://8080-$WEB_HOST/login/google"

Esta é a saída esperada:

student@cloudshell:~ echo "origin:"; echo "https://8080-$WEB_HOST"; echo "redirect:"; echo "https://8080-$WEB_HOST/login/google"
origin:
https://8080-cs-35704030349-default.cs-us-east1-rtep.cloudshell.dev
redirect:
https://8080-cs-35704030349-default.cs-us-east1-rtep.cloudshell.dev/login/google

Use a origem e o redirecionamento de URIs como Origens JavaScript autorizadas e URIs de redirecionamento autorizados para as credenciais criadas no capítulo "Preparar ID do cliente", substituindo ou adicionando os valores http://localhost:8080 fornecidos originalmente.

Clique em "Cymbal Air" na página "IDs do cliente OAuth 2.0".

Coloque a origem e redirecione os URIs para o Cloud Shell e clique no botão "Salvar".

Na nova guia do Cloud Shell, inicie o túnel para a VM com este comando gcloud:

gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8080:localhost:8081

Ignore a mensagem de erro "Não é possível atribuir o endereço solicitado".

Esta é a saída esperada:

student@cloudshell:~ gcloud compute ssh instance-1 --zone=us-central1-a -- -L 8080:localhost:8081
bind [::1]:8081: Cannot assign requested address
inux instance-1.us-central1-a.c.gleb-codelive-01.internal 6.1.0-21-cloud-amd64 #1 SMP PREEMPT_DYNAMIC Debian 6.1.90-1 (2024-05-03) x86_64

The programs included with the Debian GNU/Linux system are free software;
the exact distribution terms for each program are described in the
individual files in /usr/share/doc/*/copyright.

Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
permitted by applicable law.
Last login: Sat May 25 19:15:46 2024 from 35.243.235.73
student@instance-1:~$

Isso abre a porta 8080 no Cloud Shell, que pode ser usada para "Visualização na Web".

Clique no botão "Visualização na Web" na parte superior direita do Cloud Shell e, no menu suspenso, escolha "Visualizar na porta 8080".

Uma nova guia vai ser aberta no navegador da Web com a interface do aplicativo. Você vai ver a página "Assistente de atendimento ao cliente da Cymbal Air".

Fazer login no aplicativo

Quando tudo estiver configurado e o aplicativo aberto, use o botão "Fazer login" no canto superior direito da tela do aplicativo para fornecer suas credenciais. Isso é opcional e necessário apenas se você quiser testar a funcionalidade de reserva do aplicativo.

Uma janela pop-up será aberta para que possamos escolher nossas credenciais.

Depois de fazer login, o aplicativo estará pronto, e você poderá começar a postar suas solicitações no campo na parte de baixo da janela.

Esta demonstração mostra o assistente de atendimento ao cliente da Cymbal Air. Cymbal Air é uma companhia aérea fictícia. O assistente é um chatbot de IA que ajuda viajantes a gerenciar voos e buscar informações sobre a central da Cymbal Air no Aeroporto Internacional de São Francisco (SFO).

Sem fazer login (sem CLIENT_ID), ele pode ajudar a responder perguntas como estas:

Quando é o próximo voo para Denver?

Tem alguma loja de luxo perto do portão C28?

Onde posso tomar um café perto do portão A6?

Onde posso comprar um presente?

Encontre um voo de SFO para Denver saindo hoje

Quando você faz login no aplicativo, pode testar outros recursos, como reservar voos ou verificar se o assento atribuído a você é na janela ou no corredor.

O aplicativo usa os modelos de fundação mais recentes do Google para gerar respostas e adicionar informações sobre voos e comodidades do banco de dados operacional do AlloyDB. Saiba mais sobre este aplicativo de demonstração na página do GitHub do projeto.

9. Limpar o ambiente

Agora que todas as tarefas estão concluídas, é possível limpar o ambiente.

Excluir serviço do Cloud Run

No Cloud Shell, execute:

gcloud run services delete toolbox --region us-central1

Saída esperada do console:

student@cloudshell:~ (gleb-test-short-004)$ gcloud run services delete retrieval-service --region us-central1
Service [retrieval-service] will be deleted.

Do you want to continue (Y/n)?  Y

Deleting [retrieval-service]...done.                                                                                                                                                                                                                 
Deleted service [retrieval-service].

Exclua a conta de serviço do serviço do Cloud Run.

No Cloud Shell, execute:

PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts delete toolbox-identity@$PROJECT_ID.iam.gserviceaccount.com --quiet

Saída esperada do console:

student@cloudshell:~ (gleb-test-short-004)$ PROJECT_ID=$(gcloud config get-value project)
Your active configuration is: [cloudshell-222]
student@cloudshell:~ (gleb-test-short-004)$ gcloud iam service-accounts delete retrieval-identity@$PROJECT_ID.iam.gserviceaccount.com --quiet
deleted service account [[e-mail]]
student@cloudshell:~ (gleb-test-short-004)$

Destrua as instâncias e o cluster do AlloyDB quando terminar o laboratório.

Excluir o cluster do AlloyDB e todas as instâncias

Se você usou a versão de teste do AlloyDB. Não exclua o cluster de teste se você planeja testar outros laboratórios e recursos usando esse cluster. Não será possível criar outro cluster de teste no mesmo projeto.

O cluster é destruído com a opção "force" que também exclui todas as instâncias pertencentes.

No Cloud Shell, defina o projeto e as variáveis de ambiente se tiver ocorrido uma desconexão e todas as configurações anteriores forem perdidas:

gcloud config set project <your project id>

export REGION=us-central1
export ADBCLUSTER=alloydb-aip-01
export PROJECT_ID=$(gcloud config get-value project)

Exclua o cluster:

gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force

Observação: o comando leva de 3 a 5 minutos para ser executado.

Saída esperada do console:

student@cloudshell:~ (test-project-001-402417)$ gcloud alloydb clusters delete $ADBCLUSTER --region=$REGION --force
All of the cluster data will be lost when the cluster is deleted.

Do you want to continue (Y/n)?  Y

Operation ID: operation-1697820178429-6082890a0b570-4a72f7e4-4c5df36f
Deleting cluster...done.   

Excluir backups do AlloyDB

Exclua todos os backups do AlloyDB do cluster:

Observação: o comando vai destruir todos os backups de dados do cluster com o nome especificado na variável de ambiente.

for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done

Saída esperada do console:

student@cloudshell:~ (test-project-001-402417)$ for i in $(gcloud alloydb backups list --filter="CLUSTER_NAME: projects/$PROJECT_ID/locations/$REGION/clusters/$ADBCLUSTER" --format="value(name)" --sort-by=~createTime) ; do gcloud alloydb backups delete $(basename $i) --region $REGION --quiet; done
Operation ID: operation-1697826266108-60829fb7b5258-7f99dc0b-99f3c35f
Deleting backup...done.                                                                                                                                                                                                                                                            

Agora você pode destruir a VM.

Excluir a VM do GCE

No Cloud Shell, execute:

export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet

Saída esperada do console:

student@cloudshell:~ (test-project-001-402417)$ export GCEVM=instance-1
export ZONE=us-central1-a
gcloud compute instances delete $GCEVM \
    --zone=$ZONE \
    --quiet
Deleted 

Exclua a conta de serviço da VM do GCE e do Serviço de recuperação.

No Cloud Shell, execute:

PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts delete compute-aip@$PROJECT_ID.iam.gserviceaccount.com --quiet

Saída esperada do console:

student@cloudshell:~ (gleb-test-short-004)$ PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts delete compute-aip@$PROJECT_ID.iam.gserviceaccount.com --quiet
Your active configuration is: [cloudshell-222]
deleted service account [[e-mail]]
student@cloudshell:~ (gleb-test-short-004)$ 

10. Parabéns

Parabéns por concluir o codelab.

O que vimos

• Como implantar um cluster do AlloyDB
• Como se conectar ao AlloyDB
• Como configurar e implantar o serviço da caixa de ferramentas do MCP
• Como implantar um aplicativo de amostra com o serviço implantado

11. Pesquisa

Saída:

Como você usará este tutorial?

Apenas leitura Leitura e exercícios