A sample Google Workspace add-on for Google Drive and Gmail using Node.js and demonstrating how to use various Generative AI APIs.
Here is a diagram that shows the different components in this sample solution:
flowchart LR
A[Google Workspace Add-on\nfor Google Drive and Gmail]<-->B[Backend hosted on\nGoogle Cloud Run]
B-->C[Google Drive APIs]
B-->D[Generative AI APIs\ne.g. Google Cloud Vertex AI APIs]
- A Google Cloud Project.
- Make sure that you turn on billing for your Cloud project. Learn how to verify the billing status of your projects.
- The Cloud SDK configured with the Cloud project. You can skip this step if using Cloud Shell.
Follows the steps in this guide to setup your environment before proceeding with the next steps.
Once completed, you can use the gcloud command (for example in Cloud Shell) to proceed.
Run the following command and note the ACCOUNT value that is provided.
gcloud auth listSet active account using the account provided in the previous step.
gcloud config set account <ACCOUNT>Set the project ID to the project you are using.
gcloud config set project <PROJECT_ID>gcloud services enable \
appsmarket-component.googleapis.com \
artifactregistry.googleapis.com \
cloudbuild.googleapis.com \
cloudresourcemanager.googleapis.com \
drive.googleapis.com \
gmail.googleapis.com \
gsuiteaddons.googleapis.com \
run.googleapis.comWe will deploy the backend that handles requests from the add-on to Cloud Run.
For the next steps you need a local copy of the source code in this repository.
You can either use git clone to clone the repository, or download a copy from the repository view page.
NOTE: Before continuing with the next step, make sure to change into the directory containing your local copy of the repository.
Make a copy of the config/default-template.json file in the config folder and name it default.json.
This file will be used later for configuring the add-on code. You will first deploy the code with the basic template configuration, and once you retrieve the deployment URL you will configure the add-on and deploy the code again.
PROJECT_ID=$(gcloud config list --format='value(core.project)')
PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format='value(projectNumber)')
gcloud projects add-iam-policy-binding $PROJECT_ID \
--member=serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com \
--role=roles/run.admin
gcloud iam service-accounts add-iam-policy-binding \
$PROJECT_NUMBER-compute@developer.gserviceaccount.com \
--member=serviceAccount:$PROJECT_NUMBER@cloudbuild.gserviceaccount.com \
--role=roles/iam.serviceAccountUsergcloud builds submitgcloud run services list --platform managedNote the URL value in the response, as this will be your deployment URL to be used later in configuring the add-on.
The configuration below should be made inside the config/default.json file that is deployed with the code.
We verify all requests that hits the endpoints are coming from the add-on. We do this by comparing the service account email in the request against the configured value in serviceAccountEmail under the addOnConfig section.
To get your service account email for the add-on, follow the steps here or run the following command:
gcloud workspace-add-ons get-authorizationWe verify the user ID token and extract their profile name. In order to do that, we need the OAuth client ID for the add-on.
To get the client ID, follow the steps here and then add the value to the oauthClientId variable in the addOnConfig section.
Configure all the variables under urls in the addOnConfig section to point to the correct endpoints.
Update the <DEPLOYMENT_URL> variable with the deployment URL you retrieved when you deployed your Cloud Run service.
For example, if you deployed your code to http://www.mydeployment.com/ then the value of generateReplyUrl will be https://www.mydeployment.com/generateReplyUrl
These function URLs are used for interactions between cards in the add-on.
This add-on can be used with the list of providers below. For each provider, you can configure the enabled flag to show in the add-on, and any applicable configuration (i.e. API key) for that provider.
Make sure to set the defaultProvider variable to an enabled provider that you want to be selected by default.
The add-on can use Google Cloud Vertex AI Gemini API to generate and summarize text.
To use this provider, you first need to enable the service in your Google Cloud project.
gcloud services enable aiplatform.googleapis.comThe code uses the service account attached to the Cloud Run deployment to generate access tokens to use the Vertex AI Gemini API. This service account by default is the the default Comptue Engine service account.
You need to grant this service account the following role in order to access the Vertex AI APIs:
Vertex AI User (roles/aiplatform.user)
You can either do this via the Google Cloud Console, or by using the following command (make sure to update PROJECT_NUMBER and PROJECT_ID with the relevant values for your project):
gcloud projects add-iam-policy-binding PROJECT_ID \
--member='serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com' \
--role='roles/aiplatform.user'Learn more on service account best practices and other ways to authenticate here.
You should configure the following parameters in the relevant section for vertexGeminiProTextApi in the add-on configuration file:
project: The Google Cloud project ID where the add-on code will run.region: The region used for the Gemini API (default isus-central1). Make sure the value corresponds to one of the available regions for Gemini API.
Additional provider configurations are available in the modules/gen_ai_providers/vertex_ai_gemini_pro_text_api.js file, including the model used, maximum tokens returned, and other configuration.
Vertex AI Gemini API is a Preview offering, subject to the "Pre-GA Offerings Terms" in the General Service Terms section of the Service Specific Terms. Pre-GA products and features are available "as is" and might have limited support, and changes to pre-GA products and features may not be compatible with other pre-GA versions. For more information, see the launch stage descriptions. Further, by using Vertex AI Gemini API, you agree to the Additional Terms for Generative AI Preview Products.
Check Google Cloud's Terms for more information on how your data is processed.
The add-on can use Google Cloud Vertex AI PaLM API to generate and summarize text.
To use this provider, you first need to enable the service in your Google Cloud project.
gcloud services enable aiplatform.googleapis.comThe code uses the service account attached to the Cloud Run deployment to generate access tokens to use the Vertex AI PaLM APIs. This service account by default is the default Comptue Engine service account.
You need to grant this service account the following role in order to access the Vertex AI APIs:
Vertex AI User (roles/aiplatform.user)
You can either do this via the Google Cloud Console, or by using the following command (make sure to update PROJECT_NUMBER and PROJECT_ID with the relevant values for your project):
gcloud projects add-iam-policy-binding PROJECT_ID \
--member='serviceAccount:PROJECT_NUMBER-compute@developer.gserviceaccount.com' \
--role='roles/aiplatform.user'Learn more on service account best practices and other ways to authenticate here.
You can configure the region for the API in the region parameter (default is us-central1) in the relevant section for vertexAiPalmApi in the add-on configuration file. Please make sure the value you select corresponds to one of the Vertex AI service endpoint listed here.
Additional configurations for the provider are found in the modules/gen_ai_providers/vertex_ai_palm_api.js file, including the models used, maximum tokens returned, and other configuration.
Please check Google Cloud's Terms for more information on how your data is processed.
The add-on can use Google AI Gemini API to generate and summarize text.
Check the list of available languages and regions for Google AI Studio and Gemini API to confirm that Gemini API is available in your region before you continue with the next step.
To use this provider, you need to create an API key in Google AI Studio and save it in the apiKey parameter in the relevant section for geminiApi in the add-on configuration file. Additional configurations for the provider are found in the modules/gen_ai_providers/gemini_api.js file, including the model used, maximum tokens returned, and other configuration.
The Gemini API is currently in public preview. Production applications are not supported yet.
Please check Google's Terms of Use, Privacy Policy for more information on how your data is processed.
The add-on can also use Cohere.ai. To setup this provider, login to your Cohere.ai account and generate an API key, then you can save it in the apiKey parameter in the add-on configuration file.
Please note that we use the specialized summarization endpoint for the sumamrization feature.
Additional configurations for the provider are found in the modules/gen_ai_providers/cohere.js file, including the models used, maximum tokens returned, and other configuration.
Please check Cohere.ai's Terms of Use, Privacy Policy and Data Usage Policy for more information on how your data is processed.
Once you have finished configuring the code, you must redeploy the Cloud Run service again.
To do so, run the following command:
You will have to redeploy your code once you've made the changes to the file using the following command:
gcloud builds submitOnce the service is deployed, you can use the add-on.
Make a copy of the sample_deployment_file/deployment.json in the main directory, and then edit the file to replace
the <DEPLOYMENT_URL> variables with the deployment URL for the Cloud Run service above.
gcloud workspace-add-ons deployments create genai-gmail-companion --deployment-file=deployment.jsonSERVICE_ACCOUNT_EMAIL=$(gcloud workspace-add-ons get-authorization --format="value(serviceAccountEmail)")
gcloud run services add-iam-policy-binding \
genai-gmail-companion \
--member=serviceAccount:$SERVICE_ACCOUNT_EMAIL \
--role=roles/run.invoker \
--region=us-west1 \
--platform=managedgcloud workspace-add-ons deployments install genai-gmail-companionIf you later make any changes to the deployment descriptor deployment.json file (i.e. update logo, name of the add-on, supported integrations), use the following command to update the add-on:
gcloud workspace-add-ons deployments replace genai-gmail-companion --deployment-file=deployment.json