Set up Proactive Mode

Set up Proactive Mode to allow Gemini Cloud Assist to run autonomously in the background, continuously investigating alerts and analyzing cost anomalies.

Enabling Proactive Mode provisions a dedicated service account for Gemini Cloud Assist. By configuring this account, you grant Gemini Cloud Assist the access it needs to analyze your environment's telemetry and logs without requiring active user intervention.

Enable the required APIs

Ensure the following APIs are enabled in your project:

  • Gemini Cloud Assist: geminicloudassist.googleapis.com
  • App Optimize API: appoptimize.googleapis.com

For more information on how to enable these APIs, see Set up Gemini Cloud Assist and Enable the App Optimize API.

To generate proactive cost insights, Gemini Cloud Assist relies on cost anomaly alerts generated by Billing. These alerts are turned on by default for all projects.

Enable proactive mode

A project administrator needs to explicitly enable Proactive Mode. When you enable Proactive Mode, Gemini Cloud Assist automatically provisions a dedicated service account called an agent identity.

  1. In the Google Cloud console, navigate to Cloud Assist Settings in the Cloud Assist chat panel.
  2. In the Proactive Agents section, select Enable proactive agents, and then click Grant access.
  3. Click Save on the Grant access panel.
  4. Click Save at the bottom of the Manage Gemini Cloud Assist panel.

Configure permissions

To set up Proactive Mode, you need to grant IAM roles to users and to the agent identity.

Agent identity roles

When an agent runs autonomously in the background, it uses an agent identity. The agent identity is automatically provisioned when you enable Proactive Mode, so no action is needed to create it. However, you must grant this agent identity the IAM roles it needs to perform background tasks; Gemini Cloud Assist only accesses the data that you explicitly authorize through the IAM roles granted to its agent identity.

This is limited to read-only access for services like Cloud Monitoring, Cloud Logging, and Cloud Asset Inventory. It cannot access data in your databases or storage buckets unless you explicitly grant those permissions.

For explainability, every insight generated by Gemini Cloud Assist includes citations that link back to the source data, such as the alert or a specific log.

The agent identity principal has the following format:

agents.global.org-ORG_NUMBER.system.id.goog/resources/geminicloudassist/projects/PROJECT_NUMBER/locations/global/agents/cloud

Where ORG_NUMBER is the numeric identifier of your Google Cloud organization, and PROJECT_NUMBER is the numeric identifier of your Google Cloud project.

The permissions required by the agent identity depend on which Proactive Mode features you plan to use. The following roles provide a good starting point based on your use case, but you may need to grant additional roles depending on the specifics of your environment and the tasks you expect Proactive Mode to perform.

For more guidance on task-specific roles, see Roles for job functions. For additional guidance on permissions and roles for Gemini Cloud Assist, see IAM requirements.

Grant the following roles to the agent identity principal based on your use case:

  • Proactive Troubleshooting: Grant Support User (roles/iam.supportUser) and Service Usage Consumer (roles/serviceusage.serviceUsageConsumer).
  • Proactive Cost Optimization: In addition to roles for proactive troubleshooting, grant the following roles:
    • Cloud Hub Operator (roles/cloudhub.operator) to access resource costs.
    • App Optimize Admin (roles/appoptimize.admin) to generate cost optimization research.

You can use the Google Cloud CLI to grant these roles. To install and initialize the gcloud CLI to use it with Proactive Mode, see Install the Google Cloud CLI.

Run the following gcloud CLI commands to grant the agent identity roles:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role='roles/iam.supportUser' \
    --member='principal://agents.global.org-ORG_NUMBER.system.id.goog/resources/geminicloudassist/projects/PROJECT_NUMBER/locations/global/agents/cloud'
gcloud projects add-iam-policy-binding PROJECT_ID \
    --role='roles/cloudhub.operator' \
    --member='principal://agents.global.org-ORG_NUMBER.system.id.goog/resources/geminicloudassist/projects/PROJECT_NUMBER/locations/global/agents/cloud'
gcloud projects add-iam-policy-binding PROJECT_ID \
    --role='roles/appoptimize.admin' \
    --member='principal://agents.global.org-ORG_NUMBER.system.id.goog/resources/geminicloudassist/projects/PROJECT_NUMBER/locations/global/agents/cloud'
gcloud projects add-iam-policy-binding PROJECT_ID \
    --role='roles/serviceusage.serviceUsageConsumer' \
    --member='principal://agents.global.org-ORG_NUMBER.system.id.goog/resources/geminicloudassist/projects/PROJECT_NUMBER/locations/global/agents/cloud'

Replace the following:

  • PROJECT_ID: The ID of your Google Cloud project.
  • ORG_NUMBER: The numeric identifier of your Google Cloud organization.
  • PROJECT_NUMBER: The numeric identifier of your Google Cloud project.

These identifiers are available from the Google Cloud console.

User roles

Users interacting with proactive results need the following roles:

  • roles/geminicloudassist.user (to chat with agents)
  • roles/geminicloudassist.viewer (to view proactive investigations and cost optimization research).

Use the following gcloud CLI commands to grant these roles:

gcloud projects add-iam-policy-binding PROJECT_ID \
    --role='roles/geminicloudassist.user' \
    --member='user:EMAIL_ADDRESS'
gcloud projects add-iam-policy-binding PROJECT_ID \
    --role='roles/geminicloudassist.viewer' \
    --member='user:EMAIL_ADDRESS'

Replace EMAIL_ADDRESS with the email address of the user who needs permission to chat with the agents and view the proactive investigation results.

What's next