Set up assistant actions

With assistant actions, the assistant can take actions on behalf of your users in connected applications.

For example, users can ask the assistant to perform actions such as creating calendar events in Google Calendar or editing issues in Jira Cloud.

Your end users can accomplish tasks in your connected applications by chatting with the assistant through the app. When an end user asks the assistant to do something, the assistant automatically determines whether this can be done using an available action that the administrator has enabled. If needed, the assistant asks the user follow-up questions about the task, then performs the requested action with confirmation from the user.

You can turn on assistant actions for the following connectors:

  • Jira Cloud
  • Workday
  • Gmail
  • Google Calendar
  • Outlook email
  • Outlook calendar

To add actions for a connector, you must configure an OAuth 2.0 (3LO) app with action-specific scopes and redirect URIs. This process is similar to configuring Oauth 2.0 (3LO) apps for search. However, because some configuration settings for actions are different from settings used for search, actions require a separate connector and OAuth 2.0 (3LO) app setup from search.

Add Jira Cloud actions

When Jira actions are turned on, end users can ask the assistant to perform the following Jira Cloud actions:

  • Create Jira issues
  • Edit Jira issues

For example, a user could enter "create a jira story called 'Launch Project Y' in project ABC" or "update the title for jira ticket JCD-1 to 'Launch Project Y'" into your app. The assistant asks for additional details if necessary, then asks the user to confirm the create or edit request.

The assistant can read and edit the following Jira fields through actions:

Field Description
Issue ID Required. ID of the issue to be modified, for example KAN-123.
Title Issue title.
Issue type Issue type.
Priority Issue priority.
Status Issue status.
Description Issue description in Markdown format.
Component Issue component.
Assignee Assignee of the issue, for example user@google.com.

Set up authentication and permissions in Jira

Before turning on Jira actions, a Jira administrator must set up authentication and permissions in Jira. This is required to connect your Jira integration and allow read and write permission for actions.

This procedure is similar to creating a Jira Cloud connector for searching across data, but grants write permissions and uses a different callback URL configuration. (For more information about Jira Cloud connectors for searching data, see Connect Jira Cloud.

These instructions explain how to create a client ID and client secret through the Atlassian Developer Console, configure the required OAuth 2.0 scopes, and set up permissions for users. Finally, retrieve your instance URL and ID, configure roles, and authenticate to read and write data between Jira Cloud and Google.

Create client ID and client secret

NOTE: For more information about enabling OAuth 2.0 and obtaining the client ID and secret, see OAuth 2.0 (3LO) apps in the Atlassian Developer documentation.

  1. Sign in to developer.atlassian.com.
  2. Click the profile icon in the top right corner and select Developer Console.
  3. Click Create and select OAuth 2.0 Integration.
  4. Enter a name for the app.
    • Check the terms and conditions checkbox.
    • Click Create.
  5. Click Authorization.
  6. In the Authorization type table, select Add for OAuth 2.0 (3LO).
  7. In the Callback URL field, enter https://vertexaisearch.cloud.google.com/oauth-redirect, and then click Save changes.

  8. Click Permissions:

    1. Go to Jira API, click Add, then click Configure.

    2. Go to the Classic scopes tab and click Edit Scopes. Select the following scopes, then save your changes:

      • Classic scopes:

        • read:jira-work
        • read:jira-user

      • write:jira-work

      • Granular scopes:

        • read:user:jira

  9. Click Distribution, select Edit, and do the following:

    • Select the Sharing radio button first to enable editing other fields.
    • Fill out the remaining fields.
    • Select Yes when asked: Does your app store personal data?

  10. Select Settings to copy your Client ID and Client Secret.

Retrieve instance URL and instance ID

To get the instance URL:

  1. Go to atlassian.net and sign in with your administrator account.
  2. Select the app you want to sync. For example, sync the first app.
  3. Find the instance URL, which is the subdomain in the address bar.

To get the instance ID:

  1. Open a new tab, copy the instance URL, and append /_edge/tenant_info to the instance URL. For example, https://YOUR-INSTANCE.atlassian.net/_edge/tenant_info.
  2. Navigate to the link to find the cloudId value. The cloudId is your Instance ID.

Set up permissions and roles

  1. Sign in to atlassian.com with your administrator account.
  2. Click the menu icon on the top left or go to admin.atlassian.com.
  3. On the Admin page, click Manage users and go to the Groups page.
  4. Click Create group. Enter a name for the group and create it.
  5. In the Group product access section of your new group's page, click Add products to group.
  6. For Jira, select User access admin as the product role.
  7. For Jira Admin, select Product admin as the product role and save your changes.
  8. On the Groups page, click Add group members and add users or accounts that the connector will authenticate as.

Obtain a refresh token

If you plan to configure Jira actions using the Google Cloud console, you don't need to obtain a refresh token.

If you need to use the API to configure your Jira actions, then a refresh token is required. To obtain a refresh token:

  1. Go to your app in the developer console.
  2. Select Authorization.
  3. Select Configure next to OAuth 2.0 (3LO).
  4. For redirect URL, use a placeholder such as https://example.com.
  5. To get a refresh token in your initial authorization flow, add offline_access to the scope parameter of the authorization URL. For example: https://auth.atlassian.com/authorize?audience=api.atlassian.com&client_id=your_client_id**&scope=offline_access**%20read%3Ajira-user&redirect_uri=https%3A%2F%2Fyour-redirect-url&state=%24%7BYOUR_USER_BOUND_VALUE%7D&response_type=code&prompt=consent
  6. After you're authorized, you will be redirected back to the redirect URL. On the address bar, you should see a query parameter called "code". Keep a note of its value.

  7. Use tools such as curl or postman to send a POST request to https://auth.atlassian.com/oauth/token, with a JSON object with the following keys:

    1. grant_type: authorization_code
    2. client_id: your client ID
    3. client_secret: your client secret
    4. code: The code you got from step 6
    5. redirect_uri: your redirect URI

  8. You will get refresh_token in the response

For more about refresh tokens, see Implementing the refresh token flow in the Atlassian documentation.

Configure a Jira action

This section describes how to create a Jira connector for actions and enable Jira actions for your assistant.

Before you begin

Before you configure your actions, make sure the following steps are complete:

  • Your project must be added to the allowlist for assistant actions
  • A Jira administrator has completed the steps in Set up authentication and permissions in Jira and provided you with the following information:
    • Client ID
    • Client secret
    • Instance ID
    • Refresh token. Only required for creating Jira actions through the API instead of through the Google Cloud console. Google recommends creating actions through the Google Cloud console.

Configure Jira actions in the Google Cloud console

Google recommends creating actions through the Google Cloud console.

To add actions to your app using the console, do the following:

  1. In the Google Cloud console, go to the **Agentspace page.
  2. Go to your app.
  3. Go to the Actions page.
  4. For Jira, click Connect.
  5. Select a Jira instance.
  6. If prompted, enter authorization information for your connector. This is only required if the instance has not been configured for an action yet.
  7. Select which actions to enable.
  8. Click Finish setup. Your action is displayed on the Actions page.

Create and enable Jira actions using the API

Google recommends that you create actions through the Google Cloud console. If you need to create actions using the API, do the following:

  1. Create a Jira connector and configure it for search: 

    SERVER=https://discoveryengine.googleapis.com

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-GFE-SSL: yes" \
-H "X-Goog-User-Project: YOUR_COLLECTION_DISPLAY_NAME" \
"$SERVER/v1alpha/projects/PROJECT_NUMBER/locations/global:setUpDataConnector" \
-d '{
  "collectionId": "PROJECT_NUMBER",
  "collectionDisplayName": "YOUR_COLLECTION_DISPLAY_NAME",
  "dataConnector": {
    "dataSource": "jira",
    "params": {
      "client_id": "{Client ID of your Jira integration}",
      "client_secret": "{Client Secret of your Jira integration}",
      "refresh_token": "{Refresh Token of your Jira integration}",
      "instance_id": "{Your Jira Cloud instance ID}"
    },
    "refreshInterval": "{ >1800 }s",
    "entities": [
      {
        "entityName" : "project",
        "params" : {
          "inclusion_filters" : {}
        }
      }
      {
        "entityName": "{attachment/comment/issue/worklog}" // Optional, you can build up to 4 different entities 
      }
    ],
    "syncMode": "PERIODIC"
  }
}

  2. Include action configurations in your Jira connector:

    SERVER=https://discoveryengine.googleapis.com
PROJECT_NUMBER={YOUR PROJECT_NUMBER}
COLLECTION_ID="{YOUR COLLECTION ID}"

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token --project "${PROJECT_NUMBER}")" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: ${PROJECT_NUMBER}" \
  "$SERVER/v1alpha/projects/${PROJECT_NUMBER}/locations/global/collections/${COLLECTION_ID}/dataConnector?update_mask=action_config" \
  -d '{
    "name": "projects/${PROJECT_NUMBER}/locations/global/collections/${COLLECTION_ID}/dataConnector",
  "action_config": {
    "is_action_configured": true,
    "action_params": {
        "client_id": "{Client id from Jira integration}",
        "client_secret": "{Client secret from Jira integration}",
        "instance_uri": "{instance URI of your Jira instance}"
      }
    }
  }'

  3. Enable Jira actions for your assistant:

    SERVER=https://discoveryengine.googleapis.com
PROJECT_NUMBER={YOUR PROJECT_NUMBER}
ENGINE_ID="{YOUR ENGINE ID}"
CONNECTOR_ID="{THE CONNECTOR'S COLLECTION ID YOU GENERATED IN PREVIOUS STEP}"

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token --project "${PROJECT_NUMBER}")" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: ${PROJECT_NUMBER}" \
  "$SERVER/v1alpha/projects/${PROJECT_NUMBER}/locations/global/collections/default_collection/engines/${ENGINE_ID}/assistants/default_assistant?update_mask=enabledActions" \
  -d '{
    "name": "projects/'"${PROJECT_NUMBER}"'/locations/global/collections/default_collection/engines/'"${ENGINE_ID}"'/assistants/default_assistant",
    "enabledActions": {
      "projects/'"${PROJECT_NUMBER}"'/locations/global/collections/'"${CONNECTOR_ID}"'/dataConnector": {
        "actionInfo": [
          {
            "actionName": "create_jira_issue",
            "actionDisplayName": "Create Jira Issue"
          }
        ]
      }
    }
  }'

After you add actions, the assistant can perform those actions on behalf of your end users in the app. The first time a user asks the assistant to perform a Jira Cloud action, they are prompted to authorize access to their Atlassian account.

Add Workday actions

When Workday actions are turned on, end users can ask the assistant to create time off requests.

For example, a user could enter "schedule time off for next wed" into your app. The assistant asks for additional details if necessary, then asks the user to confirm the time off request.

When Workday actions are turned on, end users can ask the assistant to perform the following Workday actions:

  • Create time off requests

The assistant can read and edit the following Workday fields through actions:

Field Description
Start date Required. First day of the time off request, inclusive.
End date Required. Last day of the time off request, inclusive.
Type Type of time off requested. Defaults to vacation.
Description Description of the time off request.

Set up authentication and permissions in Workday

Before turning on Workday actions, a Workday administrator must authorize and set up a Workday connector for actions. This is required to connect your Workday integration and allow read and write permission for actions.

  1. In Workday, enter Register API Client task into the search bar and select that task. The Register API Client form appears.
  2. Enter a name for your new client.
  3. For the client grant type, select Authorization Code Grant.
  4. For the address token type, select Bearer.
  5. Enter a refresh token timeout in days.
  6. Enter the following redirect URI: https://vertexaisearch.cloud.google.com/oauth-redirect
  7. Select the following scopes:
    • Staffing
    • Time Off and Leave
  8. Click OK.
  9. Workday shows the details of your new client. Save the following information:
    • Client ID
    • Client secret
    • Authorization endpoint
  10. Next to the client name, click the three-dot icon (...) and select Manage Refresh Tokens for Integrations.
  11. Enter an authorized Workday account and click OK.
  12. On the Delete or Regenerate Refresh Token page, select Generate New Refresh Token and click OK.
  13. Take note of the refresh token.

Configure a Workday action

Before you begin, make sure the following is completed:

  • Your project is on the allowlist for assistant.
  • You have a app with the assistant tier enabled.
  • A Workday administrator has completed the steps in Set up authentication and permissions in Workday and provided you with the following:
    • Client ID
    • Client secret
    • Authorization endpoint URI

Configure Workday actions in the Google Cloud console

Google recommends that you create actions through the Google Cloud console. To add actions to your app using the console, do the following:

  1. In the Agentspace, go to the Agentspace page.
  2. Go to your app.
  3. Go to the Actions page.
  4. For Workday, click Connect.
  5. Select a Workday instance.
  6. If prompted, enter authorization information for your connector. This is only required if the instance has not been configured for an action yet.
  7. Select which actions to enable.
  8. Click Finish setup. Your action is displayed on the Actions page.

Configure Workday actions using the API

Google recommends that you create actions through the Agentspace. If you need to create actions using the API, do the following:

  1. Create a workday connector:

    SERVER=https://discoveryengine.googleapis.com

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-GFE-SSL: yes" \
-H "X-Goog-User-Project: YOUR_COLLECTION_DISPLAY_NAME" \
"$SERVER/v1alpha/projects/PROJECT_NUMBER/locations/global:setUpDataConnector" \
-d '{
  "collectionId": "PROJECT_NUMBER",
  "collectionDisplayName": "YOUR_COLLECTION_DISPLAY_NAME",
  "dataConnector": {
    "dataSource": "workday",
    "params": {
      "client_id": "{client id from workday oauth 2.0 app}",
      "client_secret": "{client id from workday oauth 2.0 app}",
      "refresh_token": "{refresh token from workday oauth 2.0 app}",
      "tenant": "{tenant from workday oauth 2.0 app}"
    },
    "refreshInterval": "{ >1800 }s",
    "entities": [
      {
        "entityName": "{workers/customers/jobs/organizations}"
      },
      {
        "entityName": "{workers/customers/jobs/organizations}" // Optional, you can build up to 4 different entities 
      }
    ],
    "syncMode": "PERIODIC",
    "destinationConfigs": [
      {
        "key": "host",
        "destinations": [
          {
            "host": "destination-config"
          }
        ]
      }
    ],
  }
}'

  2. Update the connector to include the action configurations created that you created:

    PROJECT_NUMBER={YOUR PROJECT_NUMBER}
COLLECTION_ID="{YOUR COLLECTION ID}

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token --project "${PROJECT_NUMBER}")" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: ${PROJECT_NUMBER}" \
  "$SERVER/v1alpha/projects/${PROJECT_NUMBER}/locations/global/collections/${COLLECTION_ID}/dataConnector?update_mask=action_config" \
  -d '{
    "name": "projects/${PROJECT_NUMBER}/locations/global/collections/${COLLECTION_ID}/dataConnector",
    "action_config": {
      "is_action_configured": true,
      "action_params": {
        ""client_id": "{client id from workday action oauth 2.0 app}",
        "client_secret": "{client secret from workday action oauth 2.0 app}",
        "auth_uri": "{Authorization endpoint from workdy action oauth 2.0 app}"
      }
    }
  }'

  3. Enable Workday actions for your assistant:

    SERVER=https://discoveryengine.googleapis.com
PROJECT_NUMBER={YOUR PROJECT_NUMBER}
ENGINE_ID="{YOUR ENGINE ID}"
CONNECTOR_ID="{THE CONNECTOR'S COLLECTION ID YOU GENERATED IN PREVIOUS STEP}"

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token --project "${PROJECT_NUMBER}")" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: ${PROJECT_NUMBER}" \
  "$SERVER/v1alpha/projects/${PROJECT_NUMBER}/locations/global/collections/default_collection/engines/${ENGINE_ID}/assistants/default_assistant?update_mask=enabledActions" \
  -d '{
    "name": "projects/'"${PROJECT_NUMBER}"'/locations/global/collections/default_collection/engines/'"${ENGINE_ID}"'/assistants/default_assistant",
    "enabledActions": {
      "projects/'"${PROJECT_NUMBER}"'/locations/global/collections/'"${CONNECTOR_ID}"'/dataConnector": {
        "actionInfo": [
          {
            "actionName": "request_time_off",
            "actionDisplayName": "Request time off"
          }
        ]
      }
    }
  }'

After you add actions, the assistant can perform those actions on behalf of your end users in the app. The first time a user asks the assistant to perform a Workday action, they are asked to authorize access to their Workday account.

Add Google Calendar actions

When Google Calendar actions are turned on, end users can ask the assistant to create Google Calendar events for them.

For example, a user could enter "schedule a meeting with user1@example.com at 3pm tomorrow". The assistant asks for additional details if necessary, then asks the user to confirm creating the event.

The assistant can read and edit the following Google Calendar fields through actions:

Field Description
Attendees Required. List of attendee email addresses. The requesting user is automatically added to the list.
Title Title of the meeting.
Start time Start time of the meeting.
Duration Duration of the meeting. Default is 30 minutes.
Time zone Time zone for meeting. If not provided the user's time zone is used.
Description Description of the meeting.

Set up authentication and permissions for Google Calendar

Before turning on Google Calendar actions, an administrator must enable the Google Calendar API and set up authorization.

Enable the Google Calendar API

In the Agentspace, enable the following APIs:

Create an OAuth app and add scopes

  1. Go to the APIs & Services > OAuth consent screen: **Go to the OAuth consent screen**
  2. Select Internal and then click Create.
  3. Enter a name for your OAuth app.
  4. Enter a user support email.
  5. Enter developer contact information.
  6. Click Save and continue.

Create an OAuth client ID

This procedure describes how to create a new OAuth client ID for Google Cloud actions. This OAuth client ID and secret can also be used for other Google Cloud actions. If you have an existing Google Cloud OAuth client ID for Google Cloud actions, you can use that client ID and secret for Google Calendar actions instead of creating a new client ID.

  1. Go to the Credentials page and click Create credentials > OAuth client ID.
  2. Select Web application.
  3. Enter a name for your client ID.
  4. Click Add URI and enter the following URI: https://vertexaisearch.cloud.google.com/oauth-redirect
  5. Click Create and copy the following information:
    • Client ID
    • Client secret

Add a Google Calendar action

Before you begin, make sure the following is completed:

Configure Google Calendar actions in the Google Cloud console

To add actions to your app using the console, do the following:

  1. In the Agentspace, go to the **Agentspace** page.
  2. Go to your app.
  3. Go to the Actions page.
  4. For Google Calendar, click Connect.
  5. Enter a name for your connector.
  6. Enter authorization information for your connector
  7. Select which actions to enable.
  8. Click Finish setup. Your action is displayed on the Actions page. It takes 5 to 15 minutes for actions to begin to work in your app.

Configure Google Calendar actions using the API

To add actions to your app using the API, do the following.

  1. Create a Google Calendar connector for actions.

    SERVER=https://discoveryengine.googleapis.com

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-GFE-SSL: yes" \
-H "X-Goog-User-Project: YOUR_COLLECTION_DISPLAY_NAME" \
"$SERVER/v1alpha/projects/PROJECT_NUMBER/locations/global:setUpDataConnector" \
-d '{
  "collectionId": "PROJECT_NUMBER",
  "collectionDisplayName": "YOUR_COLLECTION_DISPLAY_NAME",
  "dataConnector": {
    "dataSource": "google_calendar",
    "entities": [
      {
        "entityName": "google_calendar"
      }
    ],
    "syncMode": "PERIODIC",
  }
}'

  2. Update the connector to include the action that you configured.

    SERVER=https://discoveryengine.googleapis.com
PROJECT_NUMBER={YOUR PROJECT_NUMBER}
COLLECTION_ID="{YOUR COLLECTION ID}"

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token --project "${PROJECT_NUMBER}")" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: ${PROJECT_NUMBER}" \
  "$SERVER/v1alpha/projects/${PROJECT_NUMBER}/locations/global/collections/${COLLECTION_ID}/dataConnector?update_mask=action_config" \
  -d '{
    "name": "projects/${PROJECT_NUMBER}/locations/global/collections/${COLLECTION_ID}/dataConnector",
  "action_config": {
    "is_action_configured": true,
    "action_params": {
        "client_id": "{client id from Google Calendar OAuth API}",
        "client_secret": "{client secret from Google Calendar OAuth API}"
      }
    }
  }'

  3. Enable Google Calendar actions for your assistant.

    SERVER=https://discoveryengine.googleapis.com
PROJECT_NUMBER={YOUR PROJECT_NUMBER}
ENGINE_ID="{YOUR ENGINE ID}"
CONNECTOR_ID="{THE CONNECTOR'S COLLECTION ID YOU GENERATED IN PREVIOUS STEP}"

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token --project "${PROJECT_NUMBER}")" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: ${PROJECT_NUMBER}" \
  "$SERVER/v1alpha/projects/${PROJECT_NUMBER}/locations/global/collections/default_collection/engines/${ENGINE_ID}/assistants/default_assistant?update_mask=enabledActions" \
  -d '{
    "name": "projects/'"${PROJECT_NUMBER}"'/locations/global/collections/default_collection/engines/'"${ENGINE_ID}"'/assistants/default_assistant",
    "enabledActions": {
      "projects/'"${PROJECT_NUMBER}"'/locations/global/collections/'"${CONNECTOR_ID}"'/dataConnector": {
        "actionInfo": [
          {
            "actionName": "create_calendar_event",
            "actionDisplayName": "Create Calendar Event"
          }
        ]
      }
    }
  }'

After you add actions, the assistant can perform those actions on behalf of your end users in the app. The first time a user asks the assistant to perform a Google Calendar action, they are asked to authorize access to their Google Calendar account.

Add Gmail actions

When Gmail actions are turned on, end users can ask the assistant to send emails for them.

For example, a user could enter "send an email to user1@example.com with title 'Hi there' and content 'how are you doing?'". The assistant asks for additional details if necessary, then asks the user to confirm sending the email.

The assistant can read and edit the following Gmail fields through actions:

Field Description
To Required. Recipients email list.
Subject Required. Subject of the email
Content Required. Contents of the email in Markdown format.
CC Email's CC list.
BCC Email's BCC list.

Set up authentication and permissions for Gmail

Before turning on Google Calendar actions, an administrator must enable the Google Calendar API and set up authorization.

Enable the Gmail API

In the Agentspace, enable the following APIs:

  • The Gmail API: Enable the API at https://console.cloud.google.com/marketplace/product/google/gmail.googleapis.com

  • The Google People API: Enable the API** **at https://console.cloud.google.com/marketplace/product/google/people.googleapis.com

Create an OAuth app and add scopes

  1. Go to the APIs & Services > OAuth consent screen: **Go to the OAuth consent screen**
  2. Select Internal and then click Create.
  3. Enter a name for your OAuth app.
  4. Enter a user support email.
  5. Enter developer contact information.
  6. Click Save and continue.

Create an OAuth client ID

This procedure describes how to create a new OAuth client ID for Google Cloud actions. This OAuth client ID and secret can also be used for other Google Cloud actions. If you have an existing Google Cloud OAuth client ID for Google Cloud actions, you can use that client ID and secret for Gmail actions instead of creating a new client ID.

  1. Go to the Credentials page and click Create credentials > OAuth client ID.
  2. Select Web application.
  3. Enter a name for your client ID.
  4. Click Add URI and enter the following URI: https://vertexaisearch.cloud.google.com/oauth-redirect
  5. Click Create and copy the following information:
    • Client ID
    • Client secret

Configure a Gmail action

Before you begin, make sure the following is completed:

  • Your project is allowlisted for assistant.
  • You have an app with the assistant tier enabled.
  • A Google Cloud administrator has completed the steps in Set up authentication and permissions for Gmail and provided you with the following:
    • Client ID
    • Client secret

Configure Gmail actions in the Agentspace

To add actions to your app using the console, do the following:

  1. In the Agentspace, go to the **Agentspace page.
  2. Go to the Actions page.
  3. For Gmail, click Connect.
  4. Enter a name for your connector.
  5. Enter authorization information for your connector
  6. Select which actions to enable.
  7. Click Finish setup. Your action is displayed on the Actions page. It takes 5 to 15 minutes for actions to begin to work in your app.

Configure Gmail actions using the API

To add actions to your app using the API, do the following.

  1. Create a Gmail connector for actions:

    SERVER=https://discoveryengine.googleapis.com

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-GFE-SSL: yes" \
-H "X-Goog-User-Project: YOUR_COLLECTION_DISPLAY_NAME" \
"$SERVER/v1alpha/projects/PROJECT_NUMBER/locations/global:setUpDataConnector" \
-d '{
  "collectionId": "PROJECT_NUMBER",
  "collectionDisplayName": "YOUR_COLLECTION_DISPLAY_NAME",
  "dataConnector": {
    "dataSource": "google_mail",
    "entities": [
      {
        "entityName": "google_mail"
      }
    ],
    "syncMode": "PERIODIC",
  }
}'

  2. Update the connector to include action configurations.

    SERVER=https://discoveryengine.googleapis.com
PROJECT_NUMBER={YOUR PROJECT_NUMBER}
COLLECTION_ID="{YOUR COLLECTION ID}"

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token --project "${PROJECT_NUMBER}")" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: ${PROJECT_NUMBER}" \
  "$SERVER/v1alpha/projects/${PROJECT_NUMBER}/locations/global/collections/${COLLECTION_ID}/dataConnector?update_mask=action_config" \
  -d '{
    "name": "projects/${PROJECT_NUMBER}/locations/global/collections/${COLLECTION_ID}/dataConnector",
  "action_config": {
    "is_action_configured": true,
    "action_params": {
        "client_id": "{client id from Google Mail OAuth API}",
        "client_secret": "{client secret from Google Mail OAuth API}"
      }
    }
  }'

  3. Enable Gmail actions for your assistant.

    SERVER=https://discoveryengine.googleapis.com
PROJECT_NUMBER={YOUR PROJECT_NUMBER}
ENGINE_ID="{YOUR ENGINE ID}"
CONNECTOR_ID="{THE CONNECTOR'S COLLECTION ID YOU GENERATED IN PREVIOUS STEP}"

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token --project "${PROJECT_NUMBER}")" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: ${PROJECT_NUMBER}" \
  "$SERVER/v1alpha/projects/${PROJECT_NUMBER}/locations/global/collections/default_collection/engines/${ENGINE_ID}/assistants/default_assistant?update_mask=enabledActions" \
  -d '{
    "name": "projects/'"${PROJECT_NUMBER}"'/locations/global/collections/default_collection/engines/'"${ENGINE_ID}"'/assistants/default_assistant",
    "enabledActions": {
      "projects/'"${PROJECT_NUMBER}"'/locations/global/collections/'"${CONNECTOR_ID}"'/dataConnector": {
        "actionInfo": [
          {
            "actionName": "send_email",
            "actionDisplayName": "Send Email"
          }
        ]
      }
    }
  }'

After you add actions, the assistant can perform those actions on behalf of your end users in the app. The first time a user asks the assistant to perform a Gmail action, they are asked to authorize access to their Gmail account.

Add Outlook email actions

When Outlook email actions are turned on, end users can ask the assistant to send emails for them.

For example, a user could enter "send an email to userA@example.com with title 'Today's meeting' and content 'What's the agenda?'". The assistant asks for additional details if necessary, then asks the user to confirm sending the email.

The assistant can read and edit the following Outlook fields through actions:

Field Description
To Required. Recipients email list.
Subject Required. Subject of the email
Content Required. Contents of the email in Markdown format.
CC Email's CC list.
BCC Email's BCC list.

Set up authentication and permissions for Outlook email

Before turning on Outlook actions, an administrator must set up authentication and permissions for Outlook.

The following procedure applies to both Outlook email and Outlook calendar actions. If you plan to use both email and calendar actions, then enable scopes for both during the scope enabling procedure.

Create an OAuth app and add scopes

  1. Sign in to https://portal.azure.com/ and navigate to the App registrations page.

  2. Click New registration.

    1. Name your app.
    2. For redirect URI:
      • For platform type, select Web.
      • Add the following redirect URI: https://vertexaisearch.cloud.google.com/oauth-redirect

  3. Under Certificates & Secrets, create a new client secret. Take a note of the client secret. It is displayed only immediately after creation.

To enable required scopes:

  1. Go to the API Permissions settings page in your Azure App.
  2. Click Add a permission.
  3. Select Microsoft Graph.
  4. Select Delegated Permissions.
  5. Add the following scopes:
    1. offline_access
    2. User.Read
    3. Calendars.ReadWrite (if calendar actions are needed)
    4. Mail.Send (if email actions are needed)

Depending on the type of your Organizational settings in Azure (https://learn.microsoft.com/en-us/entra/identity-platform/delegated-access-primer#requesting-scopes-as-a-client-app), this last step of enabling scopes may be omitted.

Configure an Outlook email action

Before you begin, make sure the following is completed:

  • Your project is added to the allowlist for assistant.
  • You have an app with the assistant tier enabled.
  • A Google Cloud administrator has completed the steps in Set up authentication and permissions for Outlook email and provided you with the following:
    • Client ID
    • Client secret
    • Tenant ID (called Instance ID on the API)

Configure Outlook email actions using the API

To add actions to your app using the API, do the following.

The following instructions can be used to configure both Outlook email and calendar actions. If you've already configured Outlook calendar actions, then you don't need to perform these steps again.

  1. Create an Outlook connector for actions:

    SERVER=https://discoveryengine.googleapis.com
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-GFE-SSL: yes" \
-H "X-Goog-User-Project: PROJECT_NUMBER" \
"$SERVER/v1alpha/projects/PROJECT_NUMBER/locations/global:setUpDataConnector" \
-d '{
  "collectionId": "PROJECT_NUMBER",
  "collectionDisplayName": "YOUR_COLLECTION_DISPLAY_NAME",
  "dataConnector": {
    "dataSource": "outlook",
    "params": {
      "instance_id": "INSTANCE_ID",
      "client_id": "CLIENT_ID",
      "client_secret": "CLIENT_SECRET"
    },
    "actionConfig": {
      "isActionConfigured": true,
      "actionParams": {
        "client_id": "CLIENT_ID",
        "client_secret": "CLIENT_SECRET",
        "instance_id": "INSTANCE_ID",
      }
    },
    "refreshInterval": "86400s",
    "entities": [
      {
        "entityName": "mail"
      },
      {
        "entityName": "mail-attachment"
      },
{
        "entityName": "calendar"
      },
  {
        "entityName": "contact"
      }
    ],
    "syncMode": "PERIODIC",
  }
}'

  2. Enable Outlook actions for your assistant. Leave out the entry for calendar if you only need the email action.

    SERVER=https://discoveryengine.googleapis.com
PROJECT_NUMBER={PROJECT_NUMBER}
ENGINE_ID="{YOUR ENGINE ID}"
CONNECTOR_ID="{THE CONNECTOR'S COLLECTION ID YOU GENERATED IN PREVIOUS STEP}"

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token --project "${PROJECT_NUMBER}")" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: ${PROJECT_NUMBER}" \
  "$SERVER/v1alpha/projects/${PROJECT_NUMBER}/locations/global/collections/default_collection/engines/${ENGINE_ID}/assistants/default_assistant?update_mask=enabledActions" \
  -d '{
    "name": "projects/'"${PROJECT_NUMBER}"'/locations/global/collections/default_collection/engines/'"${ENGINE_ID}"'/assistants/default_assistant",
    "enabledActions": {
      "projects/'"${PROJECT_NUMBER}"'/locations/global/collections/'"${CONNECTOR_ID}"'/dataConnector": {
        "actionInfo": [
          {
            "actionName": "send_email",
            "actionDisplayName": "Send Email"
          },
          {
            "actionName": "create_calendar_event",
            "actionDisplayName": "Create Calendar Event"
          }
        ]
      }
    }
  }'

After you add actions, the assistant can perform those actions on behalf of your end users in the app. The first time a user asks the assistant to perform an Outlook action, they are asked to authorize access to their Outlook account.

Add Outlook calendar actions

When Outlook calendar actions are turned on, end users can ask the assistant to create calendar events for them.

For example, a user could enter "schedule a meeting with userA@example.com at 11am on Friday November 4". The assistant asks for additional details if necessary, then asks the user to confirm creating the event.

The assistant can read and edit the following Outlook calendar fields through actions:

Field Description
Attendees Required. List of attendee email addresses. The requesting user is automatically added to the list.
Title Title of the meeting.
Start time Start time of the meeting.
Duration Duration of the meeting. Default is 30 minutes.
Time zone Time zone for meeting. If not provided the user's time zone is used.
Description Description of the meeting.

Set up authentication and permissions for Outlook calendar

Before turning on Outlook actions, an administrator must set up authentication and permissions for Outlook.

The following procedure applies to both Outlook email and Outlook calendar actions. If you plan to use both email and calendar actions, then enable scopes for both during the scope enabling procedure.

Create an OAuth app and add scopes

  1. Sign in to https://portal.azure.com/ and navigate to the App registrations page.

  2. Click New registration.

    1. Name your app.
    2. For redirect URI:
      • For platform type, select Web.
      • Add the following redirect URI: https://vertexaisearch.cloud.google.com/oauth-redirect

  3. Under Certificates & Secrets, create a new client secret. Take a note of the client secret. It is displayed only immediately after creation.

To enable required scopes:

  1. Go to the API Permissions settings page in your Azure App.
  2. Click Add a permission.
  3. Select Microsoft Graph.
  4. Select Delegated Permissions.
  5. Add the following scopes:
    1. offline_access
    2. User.Read
    3. Calendars.ReadWrite (if calendar actions are needed)
    4. Mail.Send (if email actions are needed)

Depending on the type of your Organizational settings in Azure (https://learn.microsoft.com/en-us/entra/identity-platform/delegated-access-primer#requesting-scopes-as-a-client-app), this last step of enabling scopes may be omitted.

Configure an Outlook calendar action

Before you begin, make sure the following is completed:

  • Your project is on the allowlist for assistant.
  • You have a app with the assistant tier enabled.
  • A Google Cloud administrator has completed the steps in Set up authentication and permissions for Outlook email and provided you with the following:
    • Client ID
    • Client secret
    • Tenant ID (called Instance ID on the API)

Configure Outlook email actions using the API

The following instructions can be used to configure both Outlook email and calendar actions. If you've already configured Outlook email actions, then you don't need to perform these steps again.

To add actions to your app using the API, do the following.

  1. Create an Outlook connector for actions:

    SERVER=https://discoveryengine.googleapis.com
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-GFE-SSL: yes" \
-H "X-Goog-User-Project: PROJECT_NUMBER" \
"$SERVER/v1alpha/projects/PROJECT_NUMBER/locations/global:setUpDataConnector" \
-d '{
  "collectionId": "PROJECT_NUMBER",
  "collectionDisplayName": "YOUR_COLLECTION_DISPLAY_NAME",
  "dataConnector": {
    "dataSource": "outlook",
    "params": {
      "instance_id": "INSTANCE_ID",
    "client_id": "CLIENT_ID",
    "client_secret": "CLIENT_SECRET"
    },
    "actionConfig": {
      "isActionConfigured": true,
      "actionParams": {
        "client_id": "CLIENT_ID",
        "client_secret": "CLIENT_SECRET",
        "instance_id": "INSTANCE_ID",      }
    },
    "refreshInterval": "86400s",
    "entities": [
      {
        "entityName": "mail"
      },
      {
        "entityName": "mail-attachment"
      },
{
        "entityName": "calendar"
      },
  {
        "entityName": "contact"
      }
    ],
    "syncMode": "PERIODIC",
  }
}'

  2. Enable Outlook actions for your assistant.

    You can associate the new data connector with your assistant on the UI. You need the following API command to enable your Outlook actions:

    SERVER=https://discoveryengine.googleapis.com
PROJECT_NUMBER={YOUR PROJECT_NUMBER}
ENGINE_ID="{YOUR ENGINE ID}"
CONNECTOR_ID="{THE CONNECTOR'S COLLECTION ID YOU GENERATED IN PREVIOUS STEP}"

curl -X PATCH \
  -H "Authorization: Bearer $(gcloud auth print-access-token --project "${PROJECT_NUMBER}")" \
  -H "Content-Type: application/json" \
  -H "X-Goog-User-Project: ${PROJECT_NUMBER}" \
  "$SERVER/v1alpha/projects/${PROJECT_NUMBER}/locations/global/collections/default_collection/engines/${ENGINE_ID}/assistants/default_assistant?update_mask=enabledActions" \
  -d '{
    "name": "projects/'"${PROJECT_NUMBER}"'/locations/global/collections/default_collection/engines/'"${ENGINE_ID}"'/assistants/default_assistant",
    "enabledActions": {
      "projects/'"${PROJECT_NUMBER}"'/locations/global/collections/'"${CONNECTOR_ID}"'/dataConnector": {
        "actionInfo": [
          {
            "actionName": "send_email",
            "actionDisplayName": "Send Email"
          },
          {
            "actionName": "create_calendar_event",
            "actionDisplayName": "Create Calendar Event"
          }
        ]
      }
    }
  }'

After you add actions, the assistant can perform those actions on behalf of your end users in the app. The first time a user asks the assistant to perform an Outlook action, they are asked to authorize access to their Outlook account.