Plan travels with an AI agent accessible across Google Workspace

Coding level: Advanced
Duration: 45 minutes
Project type: Google Workspace add-on extending Chat, Gmail, Calendar, Drive, Docs, Sheets, and Slides.

This tutorial shows you how to publish AI agents to Google Workspace as Google Workspace add-ons, using Apps Script or HTTP endpoints. After your publish your add-on, your users can interact with the AI agents within their workflows.

Overview

In this tutorial, you deploy the Travel Concierge sample from the Agent Development Kit (ADK). The Travel Concierge is a conversational multi-agent AI that uses tools like the Google Maps Platform Places API, Google Search Grounding, and a Model Context Protocol (MCP) server.

The ADK provides chat and text interfaces for developers by default. In this tutorial, you add a Graphical User Interface (GUI) to Google Workspace applications that your users can access directly in Chat, Gmail, Calendar, Drive, Docs, Sheets, and Slides.

• 

  Figure 1. Using the AI agent from Chat to brainstorm travel ideas.

• 

  Figure 2. Using the AI agent from Gmail to plan a travel from the context in the selected email.

Objectives

• Set up the environment.
• Deploy the AI agent.
• Set up the project.
• Deploy to Gmail, Calendar, Drive, Docs, Sheets, Slides.
• Deploy to Chat.
• Test the solution.

About this solution

This solution relies on the following core technologies: the ADK, Google Cloud & Google Workspace APIs, Vertex AI Agent Engine, and Card framework.

The GUIs are designed differently for Chat and non-Chat (Gmail, Calendar, Drive, Docs, Sheets, Slides) applications to take into account their specific features and limitations.

Features

The following features of the Travel Concierge application are common across all Google Workspace applications:

• Persistent user sessions: Sessions are managed by Vertex AI for persistence. Each user shares one session across all Workspace applications. Users can manually reset their session to start a new conversation.

• Rich messaging: Users send text messages and receive responses with rich text and card widgets.

• Error handling: Unexpected errors are gracefully handled using configurable retries and statuses in responses.

The Chat app has the following additional features:

• Multimodal user messaging: Users can send messages with attachments, including audio and video recorded directly from the Chat space.

• More visually-advanced responses: Responses can be generated with more advanced widgets such as carousels with images by relying on Chat-only features of the Card framework and more rendering space.

Other applications have these additional features:

• Google profile context: Users can send messages with their profile information (limited to birthdays in this sample).

• Gmail context: Users can send messages with emails (limited to one subject and body in this sample).

• Agent's Chat space access: Users can open the Chat app direct message (DM) space in a new tab with one button click.

Architecture

The Travel Concierge application receives and processes Google Workspace add-on interaction events from Google Workspace applications, uses Vertex AI to prompt the ADK AI agent and manage user sessions, and relies on Google Cloud and Google Workspace APIs to gather context and display responses.

The following diagrams shows the main user flow: send a message to the AI agent.

HTTP

• 

  Figure 3. The Chat app completes the context with attachments from the user message, and sends a set of messages with the history of the sub-agent interactions and the final overall answer in chronological order.

• 

  Figure 4. The non-Chat applications completes the context with the user's Google profile and item selection, and displays a set of sections with the history of the sub-agent interactions and the final overall answer in reverse chronological order.

Apps Script

• 

  Figure 3. The Chat app completes the context with attachments from the user message, and sends a set of messages with the history of the sub-agent interactions and the final overall answer in chronological order.

• 

  Figure 4. The non-Chat applications completes the context with the user's Google profile and item selection, and displays a set of sections with the history of the sub-agent interactions and the final overall answer in reverse chronological order.

Prerequisites

• A Business or Enterprise Google Workspace account with access to Google Chat.

• A web browser with access to the internet.

• Prerequisites specific to the Travel Concierge ADK AI agent

  • Python 3.10+: For installation, follow instructions on the official Python website.
  • uv: For installation, follow instructions on the official uv website.
  • Google Cloud CLI: For installation, follow instructions on the official Google Cloud website.

Prepare the environment

This section shows how to create and configure a Google Cloud project.

Create a Google Cloud project

Google Cloud console

1. In the Google Cloud console, go to Menu > IAM & Admin > Create a Project.

   Go to Create a Project

2. In the Project Name field, enter a descriptive name for your project.

   Optional: To edit the Project ID, click Edit. The project ID can't be changed after the project is created, so choose an ID that meets your needs for the lifetime of the project.

3. In the Location field, click Browse to display potential locations for your project. Then, click Select.
   Caution: Can't find your Google Workspace organization?
   This means you aren't signed in to a Google Workspace account. Some of the features described in Google Workspace developer documentation are only available to projects associated with an organization.
4. Click Create. The Google Cloud console navigates to the Dashboard page and your project is created within a few minutes.

gcloud CLI

In one of the following development environments, access the Google Cloud CLI (gcloud):

• Cloud Shell: To use an online terminal with the gcloud CLI already set up, activate Cloud Shell.
  Activate Cloud Shell
• Local Shell: To use a local development environment, install and initialize the gcloud CLI.
  To create a Cloud project, use the gcloud projects create command:

  gcloud projects create PROJECT_ID

  Replace PROJECT_ID by setting the ID for the project you want to create.

Enable billing for the Cloud project

If you're unable to link a billing account, you don't have the permissions needed to make this change. For more information, see Permissions required to enable billing.

Google Cloud console

1. In the Google Cloud console, go to Billing. Click Menu > Billing > My Projects.

   Go to Billing for My Projects

2. In Select an organization, choose the organization associated with your Google Cloud project.
3. In the project row, open the Actions menu (), click Change billing, and choose the Cloud Billing account.
4. Click Set account.

gcloud CLI

1. To list available billing accounts, run:

   gcloud billing accounts list

2. Link a billing account with a Google Cloud project:

   gcloud billing projects link PROJECT_ID --billing-account=BILLING_ACCOUNT_ID

   Replace the following:

   • PROJECT_ID is the Project ID for the Cloud project for which you want to enable billing.
   • BILLING_ACCOUNT_ID is the billing account ID to link with the Google Cloud project.

Enable the Google Cloud APIs

HTTP

1. In the Google Cloud console, enable the Vertex AI, Places, People, Google Chat, Gmail, Cloud Build, Cloud Functions, Cloud Pub/Sub, Cloud Logging, Artifact Registry, Cloud Run, and Google Workspace add-ons APIs.

   Enable the APIs

2. Confirm that you're enabling the APIs in the correct Cloud project, then click Next.

3. Confirm that you're enabling the correct APIs, then click Enable.

Apps Script

1. In the Google Cloud console, enable the Vertex AI, Places, People, Google Chat APIs.

   Enable the APIs

2. Confirm that you're enabling the APIs in the correct Cloud project, then click Next.

3. Confirm that you're enabling the correct APIs, then click Enable.

Get a Google Maps Platform Places API key

1. In the Google Cloud console, go to the Google Maps Platform > Keys & Credentials page.

   Go to Keys & Credentials

2. The Get Started on Google Maps Platform dialog displays your newly created API key, an alphanumeric string. You'll need this string in the next sections.

Note: If you already have a suitable API key, the list of API keys is displayed, not the Get Started on Google Maps Platform dialog. Select Show key for the key to display it.

Create a service account in Google Cloud console

Create a new service account with the role Vertex AI User by following these steps:

Google Cloud console

1. In the Google Cloud console, go to Menu > IAM & Admin > Service Accounts.

   Go to Service Accounts

2. Click Create service account.
3. Fill in the service account details, then click Create and continue.
   Note: By default, Google creates a unique service account ID. If you would like to change the ID, modify the ID in the service account ID field.
4. Optional: Assign roles to your service account to grant access to your Google Cloud project's resources. For more details, refer to Granting, changing, and revoking access to resources.
5. Click Continue.
6. Optional: Enter users or groups that can manage and perform actions with this service account. For more details, refer to Managing service account impersonation.
7. Click Done. Make a note of the email address for the service account.

gcloud CLI

1. Create the service account:

   gcloud iam service-accounts create SERVICE_ACCOUNT_NAME \
     --display-name="SERVICE_ACCOUNT_NAME"

2. Optional: Assign roles to your service account to grant access to your Google Cloud project's resources. For more details, refer to Granting, changing, and revoking access to resources.

The service account appears on the service account page. Next, create a private key for the service account.

Create a private key

Warning: This example uses an exported service account key for simplicity's sake. Exporting a private key is not recommended in production because it shouldn't be stored in an insecure location, such as source control.

To learn more about secure service account implementations and best practices, see Choose when to use service accounts.

To create and download a private key for the service account, follow these steps:

1. In the Google Cloud console, go to Menu > IAM & Admin > Service Accounts.

   Go to Service Accounts

2. Select your service account.
3. Click Keys > Add key > Create new key.
4. Select JSON, then click Create.

   Your new public/private key pair is generated and downloaded to your machine as a new file. Save the downloaded JSON file as credentials.json in your working directory. This file is the only copy of this key. For information about how to store your key securely, see Managing service account keys.

5. Click Close.

For more information about service accounts, see service accounts in the Google Cloud IAM documentation.

Configure the OAuth consent screen

Google Workspace add-ons require a consent screen configuration. Configuring your add-on's OAuth consent screen defines what Google displays to users.

1. In the Google Cloud console, go to Menu > Google Auth platform > Branding.

   Go to Branding

2. If you have already configured the Google Auth platform, you can configure the following OAuth Consent Screen settings in Branding, Audience, and Data Access. If you see a message that says Google Auth platform not configured yet, click Get Started:
1. Under App Information, in App name, enter a name for the app.
2. In User support email, choose a support email address where users can contact you if they have questions about their consent.
3. Click Next.
4. Under Audience, select Internal.
5. Click Next.
6. Under Contact Information, enter an Email address where you can be notified about any changes to your project.
7. Click Next.
8. Under Finish, review the Google API Services User Data Policy and if you agree, select I agree to the Google API Services: User Data Policy.
9. Click Continue.
10. Click Create.
3. For now, you can skip adding scopes. In the future, when you create an app for use outside of your Google Workspace organization, you must change the User type to External. Then add the authorization scopes that your app requires. To learn more, see the full Configure OAuth consent guide.

Deploy the Travel Concierge ADK AI Agent

1. If not done already, authenticate with your Google Cloud account and configure Google Cloud CLI to use your Google Cloud project.

   gcloud auth application-default login
   gcloud config set project PROJECT_ID
   gcloud auth application-default set-quota-project PROJECT_ID

   Replace PROJECT_ID with the ID of the Cloud project you created.

2. Download this GitHub repository

   Download

3. In your preferred local development environment, extract the downloaded archive file and open the adk-samples/python/agents/travel-concierge directory.

   unzip adk-samples-main.zip
   cd adk-samples-main/python/agents/travel-concierge

4. Create a new Cloud Storage bucket dedicated to the ADK AI agent.

   gcloud storage buckets create gs://CLOUD_STORAGE_BUCKET_NAME --project=PROJECT_ID --location=PROJECT_LOCATION

   Replace the following:

   1. CLOUD_STORAGE_BUCKET_NAME with a unique bucket name you want to use.
   2. PROJECT_ID with the ID of the Cloud project you created.
   3. PROJECT_LOCATION with the location of the Cloud project you created.

5. Set the following environment variables:

   export GOOGLE_GENAI_USE_VERTEXAI=1
   export GOOGLE_CLOUD_PROJECT=PROJECT_ID
   export GOOGLE_CLOUD_LOCATION=PROJECT_LOCATION
   export GOOGLE_PLACES_API_KEY=PLACES_API_KEY
   export GOOGLE_CLOUD_STORAGE_BUCKET=CLOUD_STORAGE_BUCKET_NAME
   export TRAVEL_CONCIERGE_SCENARIO=travel_concierge/profiles/itinerary_empty_default.json

   Replace the following:

   1. PROJECT_ID with the ID of the Cloud project you created.
   2. PROJECT_LOCATION with the location of the Cloud project you created.
   3. PLACES_API_KEY with the string of the API key you created.
   4. CLOUD_STORAGE_BUCKET_NAME with the name of the bucket you created.

6. Install and deploy ADK AI agent.

   uv sync --group deployment
   uv run python deployment/deploy.py --create

7. Retrieve the project number and engine ID from the last printed log as PROJECT_NUMBER and ENGINE_ID respectively, you'll need both of them later to configure your project.

   Created remote agent: projects/PROJECT_NUMBER/locations/us-central1/reasoningEngines/ENGINE_ID

Review the sample code

Optionally, before setting up the project, take a moment to review and familiarize yourself with the sample code hosted on GitHub.

Python

View on GitHub

Apps Script

View on GitHub

Create and configure the project

Python

1. Download this GitHub repository

   Download

2. In your preferred local development environment, extract the downloaded archive file and open the add-ons-samples/python/travel-adk-ai-agent directory.

   unzip add-ons-samples-main.zip
   cd add-ons-samples-main/python/travel-adk-ai-agent

3. Move the JSON key file credentials.json from the service account downloaded in previous steps to the project directory.

4. In the Google Cloud console, go to Cloud Run:

   Go to Cloud Run

5. Click Write a function.

6. On the Create service page, set up your function:

   1. In the Service name field, enter travel-concierge-app.
   2. In the Region list, select the location of the Cloud project you created, PROJECT_LOCATION.
   3. Under Endpoint URL, click .
   4. In the Runtime list, select the most recent version of Python.
   5. In the Authentication section, select Allow public access.
   6. In the Containers, Volumes, Networking, Security section, under Resources:
      1. In the Memory field, select 1 GiB.
      2. In the CPU field, select 2.
   7. Click Create, and wait for Cloud Run to create the service. The console redirects you to the Source tab.

7. In your preferred local development environment, deploy the source of the project:

   gcloud run deploy travel-concierge-app --quiet --source . \
       --region PROJECT_LOCATION  \
       --function adk_ai_agent  \
       --set-env-vars LOCATION=LOCATION,PROJECT_NUMBER=PROJECT_NUMBER,ENGINE_ID=ENGINE_ID,BASE_URL=BASE_URL

   Replace the following:

   1. PROJECT_LOCATION with the location of the Cloud Run function you previously created.
   2. LOCATION with the location of the Google Cloud project created in previous steps, PROJECT_LOCATION.
   3. PROJECT_NUMBER with the project number of the Travel Concierge ADK AI Agent deployed in previous steps.
   4. ENGINE_ID with the engine ID of the Travel Concierge ADK AI Agent deployed in previous steps.
   5. BASE_URL with the Endpoint URL that you previously copied.

Apps Script

To create an Apps Script project and configure it to use your deployed Travel Concierge ADK AI agent:

1. Click the following button to open the Travel Concierge ADK AI Agent Apps Script project.
   Open the project

2. Click Overview, then Make a copy.

3. Name your copy of the Apps Script project:

   1. Click Copy of Travel Concierge ADK AI Agent.
   2. In Project title, type Travel Concierge ADK AI Agent.
   3. Click Rename.

4. In your Apps Script project, click Editor and move the file VertexAi.gs up until it's above the file AgentHandler.gs by using the file action Move file up.

5. In your Apps Script project, click Project Settings, click Edit script properties, then click Add script property to add the following script properties:

6. ENGINE_ID with the engine ID of the Travel Concierge ADK AI Agent deployed in previous steps, ENGINE_ID.

7. LOCATION with the location of the Google Cloud project created in previous steps, PROJECT_LOCATION.

8. PROJECT_NUMBER with the project number of the Travel Concierge ADK AI Agent deployed in previous steps, PROJECT_NUMBER.

9. SERVICE_ACCOUNT_KEY with the JSON key from the service account downloaded in previous steps such as { ... }.

10. Click Save script properties

11. In your Apps Script project, click Project Settings.

12. Under Google Cloud Platform (GCP) Project, click Change project.

13. In GCP project number, paste the project number of the Travel Concierge ADK AI Agent deployed in previous steps, PROJECT_NUMBER.

14. Click Set project. The Cloud project and Apps Script project are now connected.

Deploy to Gmail, Calendar, Drive, Docs, Sheets, Slides

Python

Use a Google Workspace add-on deployment to install the sample project to all Google Workspace applications (but Google Chat) to enable testing.

1. In your preferred local development environment, open the file deployment.json from the code source of the project and replace all occurrences of $BASE_URL with the value of BASE_URL, the Endpoint URL that you copied in previous steps.

2. Create a Google Workspace add-on deployment named travel-concierge-addon:

   gcloud workspace-add-ons deployments create travel-concierge-addon \
       --deployment-file=deployment.json

3. Install the Google Workspace add-on deployment:

   gcloud workspace-add-ons deployments install travel-concierge-addon

Apps Script

Install the Apps Script project to all Google Workspace applications (but Google Chat) to enable testing.

1. In your Apps Script project, click Deploy > Test deployments, then Install.

The add-on is now accessible from Google Workspace application's sidebars.

Deploy to Chat

Python

Install the sample project to Chat using the Endpoint URL to enable testing.

1. In the console, search for Google Chat API, click Google Chat API, then Manage, and Configuration.

   Go to the Google Chat API Configuration page

2. Set up the Chat app:

   1. In the App name field, enter Travel ADK AI Agent.
   2. In the Avatar URL field, enter https://goo.gle/3SfMkjb.
   3. In the Description field, enter Travel ADK AI Agent.
   4. Under Connection settings, select HTTP endpoint URL.
   5. Under Triggers, select Use a common HTTP endpoint URL for all triggers.
   6. In the HTTP endpoint URL field, paste the Endpoint URL that you previously copied, BASE_URL.
   7. Register a Quick command that the fully implemented Chat app uses:
      1. Under Commands, click Add a command.
      2. In Command ID, type 1.
      3. In Description, type Reset session.
      4. Under Command type, select Quick command.
      5. In Name, type Reset session.
      6. Click Done. The quick command is registered and listed.
   8. Under Visibility, select Make this Chat app available to specific people and groups in Your Workspace Domain and enter your email address.
   9. Under Logs, select Log errors to Logging.
   10. Click Save.

Apps Script

Install the Apps Script project to Chat using the Head Deployment ID to enable testing.

1. In your Apps Script project, click Deploy > Test deployments, then Copy under Head Deployment ID.

2. In the console, search for Google Chat API, click Google Chat API, then Manage, and Configuration.

   Go to the Google Chat API Configuration page

3. Set up the Chat app:

   1. In the App name field, enter Travel ADK AI Agent.
   2. In the Avatar URL field, enter https://goo.gle/3SfMkjb.
   3. In the Description field, enter Travel ADK AI Agent.
   4. Under Connection settings, select Apps Script.
   5. In the Deployment ID field, paste the Head deployment ID that you previously copied.
   6. Register a Quick command that the fully implemented Chat app uses:
      1. Under Commands, click Add a command.
      2. In Command ID, type 1.
      3. In Description, type Reset session.
      4. Under Command type, select Quick command.
      5. In Name, type Reset session.
      6. Click Done. The quick command is registered and listed.
   7. Under Visibility, select Make this Chat app available to specific people and groups in Your Workspace Domain and enter your email address.
   8. Under Logs, select Log errors to Logging.
   9. Click Save.

The app is now accessible from Google Chat.

1. Open Google Chat.

   Go to Google Chat

2. Create the Chat DM space:

   1. Click New Chat.
   2. Type and select the app Travel ADK AI Agent in the search.
   3. In the Install app dialog, click Install app.
   4. The Install app dialog closes and the newly created Chat DM space is selected.

The Chat app is ready to respond to messages.

Test the agent

1. Open Gmail.

   Go to Gmail

2. Send the following email to yourself:

   • Subject: You need to travel to Paris
   • Body: Please be there between 11/25/2025 and 11/30/2025!

3. Open the Travel ADK AI Agent add-on from the sidebar.

4. Click Grant permissions to complete the set up of the add-on.

5. Click Send after configuring the following request to the agent:

   • Message: Please help me plan this travel!
   • Context: select Current email

   The sidebar is updated with the agent's response.

   

6. Click Open Chat to be redirected to the Chat DM space.

7. Click + > Reset session.

   You receive a new message that confirms it's done: OK, let's start from the beginning, what can I help you with?

8. Send the message Give me ideas.

   You receive new messages with the agent's response.

   

9. Send the message I want to go there! after uploading a picture of any location such as the Eiffel Tower.

   You receive new messages with the agent's response.

   

Note: The Travel ADK AI Agent add-on can also be opened from the sidebar in Calendar, Drive, Docs, Sheets, and Slides, similar to how it's done in Gmail.

Limitations

HTTP

In Google Workspace applications other than Chat, the AI agent has the following limitations:

• It's synchronous: Sidebars can only be updated in response to user interactions, so the AI agent responses are displayed only after full completion (no streaming).

• It can time out: The sidebar updates time out when they take more than a few minutes to complete.

These limitations don't exist in Chat.

Apps Script

In all Google Workspace applications, the AI agent calls Vertex AI REST APIs using UrlFetchApp, which causes the following limitations:

• It's synchronous: The AI agent responses are returned only after full completion (no streaming).

• It can time out: The AI agent requests time out when they take roughly more than a minute to complete.

Customization

This solution supports ADK AI agents hosted in Vertex AI Agent Engine, a subset of Google Workspace application UIs, and response renderings specific to responses of the Travel Concierge sample. The solution uses an extensible framework, so you can customize it by modifying the following files:

Python

• main.py: Defines the main UIs and user interactions logic (Google Workspace event handlers). A typical extension would be to enable Drive documents as context feature for the Drive application, similar to what's done with Gmail messages for the Gmail application.

• vertex_ai.py: Manages the AI agent sessions, responses, errors, and defines Vertex AI-specific interfaces to implement to support agent interactions and response renderings. Typical extensions would be to add support for multi-sessions for separate user conversations, and other AI agent management platforms.

• agent_handler.py: Implements Vertex AI-specific interfaces defined in vertex_ai.py in the specific cases of Chat and non-Chat applications. A typical extension would be to add buttons for users to send feedback about AI agent responses.

• google_workspace.py: Implements non AI agent management-platform interactions using API calls. Only Google Workspace APIs are used in this sample to gather context details and take actions. A typical extension would be to add functions to retrieve business data from Google Calendar or a Customer Relationship Management (CRM).

• travel_agent_ui_render.gs: Implements Travel Concierge-specific response renderings for the sub-agents and Workspace applications. Typical extensions would be to add support for new response renderings to graphically display flight options, and other AI agents.

Apps Script

• Code.gs: Defines the main UIs and user interactions logic (Google Workspace event handlers). A typical extension would be to enable Drive documents as context feature for the Drive application, similar to what's done with Gmail messages for the Gmail application.

• VertexAi.gs: Manages the AI agent sessions, responses, errors, and defines Vertex AI-specific interfaces to implement to support agent interactions and response renderings. Typical extensions would be to add support for multi-sessions for separate user conversations, and other AI agent management platforms.

• AgentHandler.gs: Implements Vertex AI-specific interfaces defined in VertexAi.gs in the specific cases of Chat and non-Chat applications. A typical extension would be to add buttons for users to send feedback about AI agent responses.

• GoogleWorkspace.gs: Implements non AI agent management-platform interactions using API calls. Only Google Workspace APIs are used in this sample to gather context details and take actions. A typical extension would be to add functions to retrieve business data from Google Calendar or a Customer Relationship Management (CRM).

• TravelAgentUiRender.gs: Implements Travel Concierge-specific response renderings for the sub-agents and Workspace applications. Typical extensions would be to add support for new response renderings to graphically display flight options, and other AI agents.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this tutorial, we recommend that you delete the Cloud project.

Caution: Deleting a project has the following effects:

• Everything in the project is deleted. If you used an existing project for this tutorial, when you delete it, you also delete any other work you've done in the project.
• Custom project IDs are lost. When you created this project, you might have created a custom project ID that you want to use in the future. To preserve the URLs that use the project ID, such as a URL on appspot.com, delete the selected resources inside the project instead of deleting the whole project.

If you plan to explore multiple tutorials and quickstarts, reusing projects can help you avoid exceeding project quota limits.

1. In the Google Cloud console, go to the Manage resources page. Click Menu > IAM & Admin > Manage Resources.

   Go to Resource Manager

2. In the project list, select the project you want to delete and then click Delete .
3. In the dialog, type the project ID and then click Shut down to delete the project.

Related topics

• Fact-check statements with an ADK AI agent and Gemini model
• Integrate fundamental AI concepts in Chat apps
• Build a Chat app as a Google Workspace add-on with Apps Script