Skip to content

Connect to Google Cloud and Agent Platform

This guide explains how to connect and authenticate your ADK agents with Google Cloud Platform (GCP) services, models running on Google Cloud Agent Platform, and Agent Platform services.

Setup Google Cloud Agent Platform

Before attempting to connect an agent with Google Cloud or Agent Platform services, make sure you have completed the following prerequisites:

  • Google Cloud Project with the Agent Platform API (aiplatform.googleapis.com) enabled.
  • Install the gcloud CLI tool.

Google Cloud authentication options

You have a few options for authentication when connecting your ADK agent to Google Cloud, as described in the table below.

Method Best Used For Authentication Mechanism Environment
User Credentials Local development and testing Application Default Credentials via gcloud Local workstation
Agent Identity Production deployment and CI/CD Google IAM Service Account Key / Workload Identity Google Cloud (Agent Runtime, Cloud Run, GKE)
Service Account Production deployment and CI/CD Google IAM Service Account Key / Workload Identity Google Cloud (Agent Runtime, Cloud Run, GKE) or external servers
Express Mode Rapid prototyping and testing API Key Local or cloud environments

Warning: Protect your credentials

User credentials, service account credentials, and API keys are highly sensitive. Never commit credential files or keys directly to your codebase. Whenever possible use secure secret managers such as Google Cloud Agent Identity, Google Cloud Secret Manager or other similar products.

User credentials for local development

Connect to Google Cloud with user credentials authentication method working with local development environments.

  1. Authenticate your local workstation using Application Default Credentials (ADC) before running your ADK agent application : 
    gcloud auth application-default login

  2. Set your environment variables to enable Agent Platform and specify your project details:

    # Add to ADK code project but NOT source control
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=cloud-location   # example: us-central1

    export GOOGLE_GENAI_USE_VERTEXAI=TRUE
export GOOGLE_CLOUD_PROJECT="your-project-id"
export GOOGLE_CLOUD_LOCATION="cloud-location"   # example: us-central1

Service account for production

When deploying to secure hosted environments, use a service account for connection authentication:

  1. Create a Service Account and grant it the Agent Platform User role.
  2. Provide the credentials to your agent application according to your deployment strategy:
    • Deployed on Google Cloud (Agent Runtime, Cloud Run, GKE): The environment automatically provides the credentials. No key file configuration is necessary.
    • Running externally: Generate a service account key file (.json) and configure the GOOGLE_APPLICATION_CREDENTIALS environment variable: 
      export GOOGLE_APPLICATION_CREDENTIALS="/path/to/your/service-account-key.json"

Workload Identity option

Instead of the key file, you can also authenticate the service account using Workload Identity.

Agent Platform express mode for testing

Express Mode offers a simplified, API-key-based setup for prototyping without full gcloud authentication.

  1. Sign up for express mode to get an API key.

  2. Set the following environment variables:

    # Add to ADK code project but NOT source control
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_GENAI_API_KEY=PASTE_YOUR_ACTUAL_EXPRESS_MODE_API_KEY_HERE

    export GOOGLE_GENAI_USE_VERTEXAI=TRUE
export GOOGLE_GENAI_API_KEY="PASTE_YOUR_EXPRESS_MODE_API_KEY_HERE"

Google Cloud hosted models

Google Cloud Agent Platform hosts a wide array of AI model you can connect to your ADK agents, including Gemini models, third-party AI models, open weight models, and models custom-tuned for your organization. Check out these resources to explore and find the model that's right for your project:

  • Get more information about using Gemini models with ADK agents.
  • Explore third party and custom model options in Agent Platform hosted models for use with ADK agents.
  • Find available models and model IDs from Google Cloud in the Agent Platform documentation.

Additional Google Cloud services connections

Many Google Cloud services provide ADK integrations with authentication helpers for accessing GCP APIs or resources with an ADK agent. For more information, see the following pages: