Deploy to Cloud Run¶

Supported in ADKPythonTypeScriptGoJava

Cloud Run is a fully managed platform that enables you to run your code directly on top of Google's scalable infrastructure.

To deploy your agent, you can use either the adk deploy cloud_run command (recommended for Python), or with gcloud run deploy command through Cloud Run.

Agent sample¶

For each of the commands, we will reference the Capital Agent sample defined on the LLM agent page. We will assume it's in a directory (eg: capital_agent).

To proceed, confirm that your agent code is configured as follows:

PythonTypeScriptGoJava

Agent code is in a file called agent.py within your agent directory.
Your agent variable is named root_agent.
__init__.py is within your agent directory and contains from . import agent.
Your requirements.txt file is present in the agent directory.

Agent code is in a file called agent.ts within your project directory.
Your agent variable is named rootAgent and is exported.
Your package.json file is present in the agent directory with @google/adk and other dependencies.

Your application's entry point (the main package and main() function) is in a single Go file. Using main.go is a strong convention.
Your agent instance is passed to a launcher configuration, typically using agent.NewSingleLoader(yourAgent). The adkgo tool uses this launcher to start your agent with the correct services.
Your go.mod and go.sum files are present in your project directory to manage dependencies.

Refer to the following section for more details. You can also find a sample app in the Github repo.

Agent code is in a file called CapitalAgent.java within your agent directory.
Your agent variable is global and follows the format public static final BaseAgent ROOT_AGENT.
Your agent definition is present in a static class method.

Refer to the following section for more details. You can also find a sample app in the Github repo.

Environment variables¶

Set your environment variables as described in the Setup and Installation guide.

export GOOGLE_CLOUD_PROJECT=your-project-id
export GOOGLE_CLOUD_LOCATION=us-central1 # Or your preferred location
export GOOGLE_GENAI_USE_ENTERPRISE=True

For more information on connecting to Google Cloud from ADK agents, see Connect to Google Cloud and Agent Platform.

Prerequisites¶

You should have a Google Cloud project. You need to know your:

Project name, for example: "my-project"
Project location, for example: "us-central1"
Service account, for example: "1234567890-compute@developer.gserviceaccount.com"
GOOGLE_API_KEY

Secret¶

Make sure you have created a secret which can be read by your service account.

Cloud Build permissions¶

Since the adk deploy command uses Google Cloud Build to automate the build process, you must set your default compute service account to have permission to use Cloud Build. The following command example shows how to grant this permission:

gcloud projects add-iam-policy-binding [PROJECT_ID] \
    --member="serviceAccount:[PROJECT_NUMBER]-compute@developer.gserviceaccount.com" \
    --role="roles/cloudbuild.builds.builder"

Entry for GOOGLE_API_KEY secret¶

You can create your secret manually or use CLI:

echo "<<put your GOOGLE_API_KEY here>>" | gcloud secrets create GOOGLE_API_KEY --project=my-project --data-file=-

Permissions to read¶

You should give appropriate permission for you service account to read this secret.

gcloud secrets add-iam-policy-binding GOOGLE_API_KEY --member="serviceAccount:1234567890-compute@developer.gserviceaccount.com" --role="roles/secretmanager.secretAccessor" --project=my-project

Deployment payload¶

When you deploy your ADK agent workflow to Google Cloud Run, the following content is uploaded to the service:

Your ADK agent code
Any dependencies declared in your ADK agent code
ADK API server code version used by your agent

The default deployment does not include the ADK web user interface libraries, unless you specify it as deployment setting, such as the --with_ui option for adk deploy cloud_run command.

Deployment commands¶

Python - adk CLIPython - gcloud CLITypeScript - adk CLIGo - adkgo CLIJava - gcloud CLI

adk CLI¶

The adk deploy cloud_run command deploys your agent code to Google Cloud Run.

Ensure you have authenticated with Google Cloud: gcloud auth login and gcloud config set project <your-project-id>.

Setup environment variables¶

Optional but recommended: Setting environment variables can make the deployment commands cleaner.

# Set your Google Cloud Project ID
export GOOGLE_CLOUD_PROJECT="your-gcp-project-id"

# Set your desired Google Cloud Location
export GOOGLE_CLOUD_LOCATION="us-central1" # Example location

# Set the path to your agent code directory
export AGENT_PATH="./capital_agent" # Assuming capital_agent is in the current directory

# Set a name for your Cloud Run service (optional)
export SERVICE_NAME="capital-agent-service"

# Set an application name (optional)
export APP_NAME="capital_agent_app"

Command usage¶

Minimal command¶

adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
$AGENT_PATH

Full command with optional flags¶

adk deploy cloud_run \
--project=$GOOGLE_CLOUD_PROJECT \
--region=$GOOGLE_CLOUD_LOCATION \
--service_name=$SERVICE_NAME \
--app_name=$APP_NAME \
--with_ui \
$AGENT_PATH

Arguments¶

AGENT_PATH: (Required) Positional argument specifying the path to the directory containing your agent's source code, for example: $AGENT_PATH or capital_agent/. This directory must contain at least an __init__.py and your main agent file, for example: agent.py.

Options¶

--project TEXT: (Required) Your Google Cloud project ID, for example: $GOOGLE_CLOUD_PROJECT.
--region TEXT: (Required) The Google Cloud location for deployment, for example: $GOOGLE_CLOUD_LOCATION, us-central1.
--allow_origins: (Optional) A comma-separated list of origins for CORS (Cross-Origin Sharing). To allow a regular expression pattern, prefix the origin with regex. For example: http://localhost:8000,regex:https://.*\.example\.com.
--service_name TEXT: (Optional) The name for the Cloud Run service, for example: $SERVICE_NAME, defaults to adk-default-service-name.
--app_name TEXT: (Optional) The application name for the ADK API server, for example: $APP_NAME. Defaults to the name of the directory specified by AGENT_PATH, for example: capital_agent if AGENT_PATH is ./capital_agent.
--session_service_uri TEXT: (Optional) The URI of the session service. If you are using a managed session service via Agent Runtime, pass agentengine://<agent_engine>, where <agent_engine> is either the resource ID or the full projects/*/locations/*/reasoningEngines/* resource name. Other supported forms are memory:// and any SQLAlchemy database URL, for example: sqlite://<path>.
--artifact_service_uri TEXT: (Optional) The URI of the artifact service, for example: gs://<bucket_name> for Cloud Storage, file://<path>, or memory://.
--memory_service_uri TEXT: (Optional) The URI of the memory service, for example: rag://<rag_corpus_id>, agentengine://<agent_engine>, or memory://.
--port INTEGER: (Optional) The port number the ADK API server will listen on within the container. Defaults to 8000.
--with_ui: (Optional) If included, deploys the ADK dev UI alongside the agent API server. By default, only the API server is deployed.
--temp_folder TEXT: (Optional) Specifies a directory for storing intermediate files generated during the deployment process. Defaults to a timestamped folder in the system's temporary directory. (Note: This option is generally not needed unless troubleshooting issues).
--help: Show the help message and exit.

When --session_service_uri and --artifact_service_uri are not set, the deployed container falls back to the in-memory session and artifact services, and sessions and artifacts are lost whenever a Cloud Run instance is recycled. Set both options for any deployment that must retain this data.

Passing gcloud CLI Arguments¶

To pass specific gcloud flags through the adk deploy cloud_run command, use the double-dash separator (--) after the ADK arguments. Any flags (except ADK-managed) following the -- will be passed directly to the underlying gcloud command.

Syntax example:¶

adk deploy cloud_run [ADK_FLAGS] -- [GCLOUD_FLAGS]

Example:¶

adk deploy cloud_run --project=[PROJECT_ID] --region=[REGION] path/to/my_agent    -- --no-allow-unauthenticated --min-instances=2

Authenticated access¶

During the deployment process, you might be prompted: Allow unauthenticated invocations to [your-service-name] (y/N)?.

Enter y to allow public access to your agent's API endpoint without authentication.
Enter N (or press Enter for the default) to require authentication, for example: using an identity token as shown in the "Testing your agent" section.

Upon successful execution, the command deploys your agent to Cloud Run and provide the URL of the deployed service.

gcloud CLI for Python¶

Alternatively, you can deploy using the standard gcloud run deploy command with a Dockerfile. This method requires more manual setup compared to the adk command but offers flexibility, particularly if you want to embed your agent within a custom FastAPI application.

Ensure you have authenticated with Google Cloud (gcloud auth login and gcloud config set project <your-project-id>).

Project structure¶

Organize your project files as follows:

your-project-directory/
├── capital_agent/
│   ├── __init__.py
│   └── agent.py       # Your agent code (see "Agent sample" tab)
├── main.py            # FastAPI application entry point
├── requirements.txt   # Python dependencies
└── Dockerfile         # Container build instructions

Create the following files (main.py, requirements.txt, Dockerfile) in the root of your-project-directory/.

Code files¶

This file sets up the FastAPI application using get_fast_api_app() from ADK:

main.py

import os

import uvicorn
from fastapi import FastAPI
from google.adk.cli.fast_api import get_fast_api_app

# Get the directory where main.py is located
AGENT_DIR = os.path.dirname(os.path.abspath(__file__))
# Example session service URI, for example, SQLite
# Note: Use 'sqlite+aiosqlite' instead of 'sqlite' because DatabaseSessionService requires an async driver
SESSION_SERVICE_URI = "sqlite+aiosqlite:///./sessions.db"
# Example allowed origins for CORS
ALLOWED_ORIGINS = ["http://localhost", "http://localhost:8080", "*"]
# Set web=True if you intend to serve a web interface, False otherwise
SERVE_WEB_INTERFACE = True

# Call the function to get the FastAPI app instance
# Ensure the agent directory name ('capital_agent') matches your agent folder
app: FastAPI = get_fast_api_app(
    agents_dir=AGENT_DIR,
    session_service_uri=SESSION_SERVICE_URI,
    allow_origins=ALLOWED_ORIGINS,
    web=SERVE_WEB_INTERFACE,
)

# You can add more FastAPI routes or configurations below if needed
# Example:
# @app.get("/hello")
# async def read_root():
#     return {"Hello": "World"}

if __name__ == "__main__":
    # Use the PORT environment variable provided by Cloud Run, defaulting to 8080
    uvicorn.run