🚀One-Click Deployment of Your Multi-Agent System to Cloud Run with Google ADK

Huey Bai — Fri, 20 Jun 2025 06:04:19 +0000

Are you exploring Google's Agent Development Kit (ADK) to build powerful multi-agent systems? Do you want to quickly bring your hard-built agents online but feel intimidated by complex containerization and deployment processes? Don't worry! This article will guide you step-by-step on how to use the adk deploy command to seamlessly deploy your ADK project to Google Cloud Run, all without writing a single line of Dockerfile!

Ready? Let's unlock the superpower of agent deployment!

This blog was created while participating in the Agent Development Kit Hackathon.

📘 What is Google ADK?

Before diving into deployment, let's briefly understand ADK. The ADK (Agent Development Kit) is a powerful open-source framework from Google, designed for building, testing, and deploying multi-agent systems based on Large Language Models (LLMs). It provides a core set of capabilities that allow you to:

Define LLM Agents with reasoning and task capabilities: Easily create agents that can understand instructions and execute tasks.
Extend Agent behavior with Tools: Equip your agents with the ability to perform complex tasks by integrating custom tool functions (e.g., searching, calculating, calling external APIs).
Control flow with Workflow Agents: Orchestrate multiple agents to implement complex business processes like sequences, parallel execution, or loops.
Persist context with State and Memory Systems: Enable agents to maintain context across multiple turns of conversation, providing a more coherent interaction experience.

ADK comes with deep integration for Gemini models by default and also supports connecting to other major LLM models like OpenAI and Anthropic via LiteLLM, giving you great flexibility.

🧭 Why Deploy to Cloud Run?

Deploying your ADK project to Google Cloud Run is an ideal choice for several reasons:

Fully Managed Serverless Platform: You don't need to manage underlying servers, operating systems, or clusters; Google Cloud Run handles all the infrastructure for you.
On-Demand Start / Auto-Scaling: Services only start when requested and automatically scale down to zero when there's no traffic, significantly saving costs. During traffic peaks, it also auto-scales horizontally to ensure your service remains highly available.
Built-in HTTPS and IAM Security Controls: Cloud Run automatically provides an HTTPS endpoint for your service and integrates deeply with Google Cloud IAM for easy, fine-grained access control.
Supports Containerized Applications (Perfect for ADK's API Server Mode): ADK projects can run in API Server mode, which perfectly fits Cloud Run's containerized deployment environment.
One-Click Deployment with adk deploy: Most importantly, ADK provides the adk deploy command, allowing you to deploy your project to Cloud Run with minimal effort, skipping the tedious Docker build and push steps.

📂 Project Structure (Must Follow Official Guidelines)

For the adk deploy command to correctly identify and deploy your project, your ADK project must follow a specific structure. For a Python project, your directory should look something like this:

your-adk-project/
├── multi_tool_agent/            # Your agent project directory; this name will be the Cloud Run service name
│   ├── __init__.py              # Can be empty, but must exist to signify a Python package
│   └── agent.py                 # Your core agent logic file, must contain the root_agent definition
├── requirements.txt             # Your Python project dependencies; `adk deploy` will install these automatically
└── .env                         # (Optional) Environment variables for local testing or cloud deployment

In your agent.py file, you must define an Agent instance named root_agent; this will be the default entry point that ADK automatically looks for:

from google.adk.agents import Agent

root_agent = Agent(
    name="weather_agent",
    model="gemini-2.0-pro",
    instruction="You are a helpful assistant that provides weather information.",
    tools=[],  # Define your tool functions here, like a tool to query a weather API
)

Important Note: The variable name root_agent is fixed and cannot be changed. The ADK deployment tool looks for this specific name to start your agent service.

🧪 Local Testing (Optional but Highly Recommended)

Before deploying your project to the cloud, it's highly recommended to thoroughly test it locally to ensure everything works as expected. This helps you quickly identify and resolve issues, avoiding unnecessary deployment failures.

First, create an .env file in your project's root directory (if it doesn't already exist) and configure it as follows to enable local testing using a Gemini API Key:

# .env file for local testing
GOOGLE_GENAI_USE_VERTEXAI=False
GOOGLE_API_KEY= PASTE_YOUR_ACTUAL_API_KEY_HERE

Note: The GOOGLE_API_KEY here is the API key you obtained from Google AI Studio.

Then, from your project's root directory, run the following command to start ADK in local run mode:

adk run multi_tool_agent

You can immediately test conversations with your agent in the terminal. This will simulate how your agent behaves after deployment.

☁️ Cloud Run Automatic Deployment

Now, for the exciting part! Let's get your ADK project deployed to Cloud Run.

🔧 Step 1: Prepare Your Google Cloud Environment

Before deploying, ensure you have the gcloud CLI installed and configured:

Log in to your GCP account:
```
gcloud auth login
```
This will open your browser and guide you through the Google account login process.
Set your default project:
```
gcloud config set project YOUR_PROJECT_ID
```
Replace YOUR_PROJECT_ID with your Google Cloud project ID. It's highly recommended to create a new, separate Cloud Project for testing your ADK project to better manage resources and permissions.
Set your deployment region:
```
gcloud config set run/region us-central1
```
Choose a region closest to your users, such as us-central1 (Central US), europe-west1 (Western Europe), or asia-southeast1 (Southeast Asia).
Enable the Cloud Run API:
```
gcloud services enable run.googleapis.com
```
Ensure the Cloud Run API is enabled for your project; otherwise, deployment will fail.

🚀 Step 2: Configure Your `.env` File for Cloud Run Deployment

Before deploying to Cloud Run, you need to modify the .env file in your project's root directory to configure ADK to use the Gemini model on Vertex AI. Change the file content to:

# .env file for Cloud Run deployment
GOOGLE_GENAI_USE_VERTEXAI=TRUE
GOOGLE_CLOUD_PROJECT=YOUR_CLOUD_PROJECT_ID # Replace with your actual GCP Project ID
GOOGLE_CLOUD_LOCATION=global # Keep this as global

Important Note: GOOGLE_CLOUD_PROJECT needs to be replaced with your GCP project ID, while GOOGLE_CLOUD_LOCATION should remain global. With this configuration, your Cloud Run service account will automatically gain permission to access Vertex AI, and you won't need a separate GOOGLE_API_KEY.

🚀 Step 3: Deploy with the `adk deploy` Command

Make sure you've saved your modified .env file, then navigate to your ADK project's root directory (where multi_tool_agent is located) and run the following command:

adk deploy cloud_run \
  --project=YOUR_CLOUD_PROJECT_ID \
  --region=YOUR_CLOUD_LOCATION \
  --service_name=multi-tool-agent-service \
  --with_ui \
  ./multi_tool_agent

Again, replace YOUR_CLOUD_PROJECT_ID and YOUR_CLOUD_LOCATION with your actual GCP project ID and region (e.g., us-central1). The --service_name parameter allows you to specify the name of your Cloud Run service after deployment.

Here's the highlight: The --with_ui parameter will deploy a Cloud Run service with an interactive UI. This will greatly simplify interacting with and debugging your agent.

The adk deploy command will automatically handle these complex operations for you:

Package your project into a Docker image: ADK intelligently analyzes your project's dependencies and structure to automatically generate a Docker image suitable for Cloud Run.
Push the image to Artifact Registry: The generated Docker image will be pushed to your Google Cloud project's Artifact Registry, a secure and efficient image repository service.
Create and deploy the Cloud Run service: Finally, ADK uses this image to create a new service on Cloud Run and completes the deployment.

Upon successful deployment, you'll see output in your terminal similar to this:

Deployment successful!
Service URL: https://multi-tool-agent-service-xxxxx.a.run.app
UI URL: https://multi-tool-agent-service-xxxxx.a.run.app/ui

Here:

The Service URL is the API endpoint for your agent service.
The UI URL is a browser-based interactive user interface where you can directly chat with your agent and view its thought process (Event Trace). This is incredibly useful for debugging and demonstrations!

📮 Interactive Interface and API Access

Once deployed, you'll have two primary ways to interact with your agent:

🚀 Method 1: Experience Your Agent via the Interactive UI (Recommended!)

Simply open the UI URL (e.g., https://multi-tool-agent-service-xxxxx.a.run.app/ui) directly in your browser.

You'll see a chat-like console where you can directly type questions to interact with your agent. This UI not only provides a convenient way to interact but also often displays the agent's internal execution flow (such as tool calls, LLM calls, state changes), which is crucial for understanding and debugging agent behavior.

💻 Method 2: Programmatic Access via the API Interface

Your Cloud Run service exposes a /run endpoint that accepts JSON requests from clients. You can use curl or other programming languages (like Python, JavaScript) to call this API.

API Request Example:

curl -X POST https://multi-tool-agent-service-xxxxx.a.run.app/run \
  -H "Content-Type: application/json" \
  -d '{"query": "What’s the weather like in Tokyo?"}'

If all goes well, you'll receive a response from your agent, such as:

{
  "response": "The weather in Tokyo is sunny and 23°C."
}

🛠️ Common Issues and Solutions

Issue	Solution
`GOOGLE_API_KEY` not set (local)	Ensure your `.env` file is correctly configured with `GOOGLE_GENAI_USE_VERTEXAI=False` and your `GOOGLE_API_KEY`.
LLM authentication issues during Cloud Run deployment	When deploying to Cloud Run, ensure you have modified your `.env` file to include `GOOGLE_GENAI_USE_VERTEXAI=TRUE`, `GOOGLE_CLOUD_PROJECT=YOUR_CLOUD_PROJECT_ID`, and `GOOGLE_CLOUD_LOCATION=global`. The Cloud Run service account typically automatically gets permissions to access Vertex AI, so a separate API Key isn't needed. If you still encounter issues, check if your Cloud Run service account has the necessary Vertex AI permissions (e.g., `Vertex AI User` role).
Service deploys but returns 403 Forbidden	By default, Cloud Run services are private. If you want external access, ensure you add the `--allow-unauthenticated` flag during deployment, e.g., `adk deploy cloud_run ... --allow-unauthenticated`. Alternatively, check your Cloud IAM permissions to ensure the caller has the `Cloud Run Invoker` role.
`root_agent` not defined	Your `agent.py` file must contain the definition `root_agent = Agent(...)`. Double-check that the variable name is `root_agent`, as this is the convention ADK uses to find the agent's entry point.
Need to pass multiple environment variables	ADK automatically reads environment variables from your `.env` file and passes them to the Cloud Run service. Therefore, you only need to add all required environment variables to your `.env` file. For sensitive variables, it's highly recommended to use Secret Manager.
Deployment times out or fails with insufficient memory	Your agent or tools might require more memory. Try specifying a larger memory limit in the `adk deploy` command, e.g., `adk deploy cloud_run ... --memory=2Gi`. The default memory is typically 512 MiB.
Deployment fails, missing dependencies	Ensure your `requirements.txt` file includes all necessary Python dependencies for your project. `adk deploy` automatically reads and installs these dependencies. If deployment fails, check the build logs for any `pip install` related errors.
My tool functions need to access external services (e.g., database, other APIs) but can't after deployment	Ensure your Cloud Run service has network access to these external services. For example, if you need to access Cloud SQL, ensure your Cloud Run service account has the appropriate Cloud SQL Client role, and the Cloud Run service is connected to a VPC Access Connector. If accessing external APIs, check firewall rules or proxy settings. Never hardcode sensitive credentials in your code. Use Secret Manager or IAM credentials to securely manage these access tokens.

🧠 Advanced Tips

Once you've mastered basic deployment, consider these advanced tips to make your ADK development and debugging even more efficient:

adk web: Launch a local development UI that supports real-time agent debugging and event tracing, giving you a visual understanding of your agent's thought process and tool calls.
adk api_server: Start a local API service similar to the Cloud Run service for REST API integration testing, allowing you to simulate the cloud environment locally.
Use .adkignore: Similar to .gitignore, you can create an .adkignore file to exclude unnecessary files or directories during packaging, which speeds up image build times and reduces image size. For example, you can ignore local test logs or virtual environment directories.

📌 Best Practices

To build robust, efficient, and maintainable ADK agent systems, consider the following best practices:

Clear Tool Function Docstrings: Write clear and accurate docstrings for your tool functions. LLMs use these docs to understand the tool's functionality, enabling them to call it correctly when needed. Good documentation is the foundation of agent reliability.
Strategic Use of output_key: Save key outputs from your agents to the state using output_key for naming. This helps persist context across multi-turn conversations and makes state information accessible to subsequent agents or workflows.
Organize Workflows with SequentialAgent: For complex business logic, use SequentialAgent to chain multiple agents. This creates a clear, logical structure for your agent pipeline and makes each step easier to test independently.
Security First: Avoid hardcoding API keys or sensitive information directly in your code. For production environments, it's highly recommended to use Google Cloud Secret Manager to securely store and manage these credentials and mount them as environment variables in your Cloud Run service.
Logging and Monitoring: After deployment, closely monitor your Cloud Run logs and metrics. Google Cloud Logging and Monitoring provide powerful tools to help you debug issues and analyze performance.

✅ Summary

In just a few simple steps, you should now be able to:

Build a well-structured ADK project.
Flexibly configure your .env file based on your deployment target (local or cloud).
Deploy with a single adk deploy command.
Get a fully functional Cloud Run service online!

This greatly simplifies the deployment process for multi-agent systems, allowing you to bring your agent systems online quickly without needing to master complex container packaging, Kubernetes, or other low-level knowledge. Your agent is now ready to serve the world from the cloud!

DEV Community: Huey Bai