Deploy ADK Google AI Agent on Cloud Run (2026 Guide)

A few weeks ago a junior engineer pushed a brand‑new Google AI Agent to production. Within minutes the service threw Out‑of‑Memory errors, cold‑starts spiked to > 10 seconds, and the team spent days chasing a silent Docker layer that was pulling in a 2 GB TensorFlow wheel. The root cause? Skipping the disciplined Docker‑and‑Cloud‑Run checklist that turns a prototype into a reliable, server‑less workload.

Deploy Google AI Agent (ADK) on Cloud Run – Complete Docker Guide

This guide details deploying a Google AI Agent (ADK) on Google Cloud Run using Docker. It covers containerizing your ADK agent, configuring Cloud Run for optimal performance, managing dependencies and secrets, and implementing advanced patterns like VPC connectivity and scaling.

What is the Google AI Development Kit (ADK)?

The ADK bundles libraries, CLI tools, and sample scaffolding that let you turn a LLM‑backed prompt into a callable “agent” with function‑calling, memory, and tool integration. It supports Python 3.11 and Node 20, exposing a run() entry point that Cloud Run can invoke via HTTP.

“Containerizing AI agents on serverless platforms requires careful resource tuning; underestimating memory needs is the most common deployment failure.” – GCP Solutions Architect

Why Cloud Run for AI Agent Deployment?

Cloud Run offers true container‑level isolation while handling autoscaling, traffic routing, and HTTPS termination. For bursty conversational traffic it can spin up dozens of instances in seconds, and you only pay for the exact CPU‑seconds used.

Prerequisites at a glance

Item	Version / Requirement
GCP Project	Billing enabled
gcloud CLI	456.0.0 or later
Docker Engine	20.10+
ADK SDK	adk==2.4.1 (Python) / @google/ai-adk@2.4.1 (Node)
Optional	Cloud Build, Secret Manager

—

Step 1: Setting Up Your Google AI Agent Project

Initializing the ADK Project Structure

# Python example – ADK 2.4.1
adk init my_adk_agent --lang python
cd my_adk_agent

The command scaffolds a src/ folder with agent.py, a requirements.txt, and a minimal Dockerfile placeholder.

Core Agent Logic & Capabilities

Edit src/agent.py to expose the run(request: dict) -> dict function. Here’s a tiny Gemini‑based example:

# agent.py (Python 3.11)
# adk==2.4.1
import os
from google.generativeai import GenerativeModel

model = GenerativeModel(os.getenv("GEMINI_MODEL", "gemini-1.5-flash"))

def run(request):
    prompt = request.get("prompt", "")
    response = model.generate_content(prompt)
    return {"reply": response.text}

My take: Keep the agent stateless. Store any conversation context elsewhere; Cloud Run containers that spin up fresh won’t have memory of prior requests.

Local Testing and Validation

python -m pip install -r requirements.txt
python -c "import src.agent as a; print(a.run({'prompt':'Hello'}))"

You should see a JSON response with the Gemini reply. If the call fails, verify GOOGLE_APPLICATION_CREDENTIALS points at a service‑account key with generativeai scope.

—

Step 2: Dockerizing Your AI Agent

Creating the Dockerfile for ADK Agents

A lean multi‑stage build keeps the final image under 500 MB.

# Dockerfile (Python 3.11) – ADK 2.4.1
# syntax=docker/dockerfile:1.4
FROM python:3.11-slim AS builder
WORKDIR /app
COPY requirements.txt .
RUN --mount=type=cache,target=/root/.cache \
    pip install --upgrade pip && \
    pip install --no-warn-script-location -r requirements.txt

FROM python:3.11-slim
WORKDIR /app
COPY --from=builder /usr/local/lib/python3.11/site-packages /usr/local/lib/python3.11/site-packages
COPY src/ ./src/
ENV PORT=8080
EXPOSE 8080
CMD ["python", "-m", "src.agent"]

Why multi‑stage? The builder stage pulls heavy wheels (e.g., TensorFlow) into a cache layer that is discarded in the final stage, dramatically shrinking the runtime image.

Managing Dependencies & Environment Variables

• Pin versions in requirements.txt (google-generativeai==0.4.0).
• Keep secrets out of the image. Use Secret Manager and inject them at runtime:

gcloud secrets create gemini-key --data-file=key.txt
gcloud run services update my-agent \
  --update-secrets=GEMINI_KEY=gemini-key:latest

Building and Testing the Container Locally

docker build -t my-adk-agent:latest .
docker run -p 8080:8080 -e GEMINI_KEY=$(cat key.txt) my-adk-agent
curl -X POST http://localhost:8080 -d '{"prompt":"Hi"}' -H "Content-Type: application/json"

You should receive a JSON payload with the model’s reply. If the container crashes, inspect docker logs for missing libraries.

Hint: Use the article “[Optimizing Docker Layers for Python Applications]” for deeper layer‑caching tricks.

—

Step 3: Configuring Google Cloud Run

Creating a Cloud Run Service vs Job

For interactive agents use Service (HTTP‑triggered). Jobs are appropriate for batch inference pipelines.

gcloud run deploy adk-agent \
  --image gcr.io/$PROJECT_ID/my-adk-agent:latest \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated

CPU & Memory Allocation for AI Workloads

Workload	CPU	Memory
Light (text‑only)	1	512 MiB
Medium (image‑heavy)	2	1 GiB
Heavy (large model)	4	2 GiB+

Google Cloud Run currently caps memory at 8 GiB per instance. Pick the smallest tier that passes your latency benchmark; you can always adjust later.

Warning: Undersizing memory often triggers “Container killed (Out of memory)” errors that appear as generic 500 responses.

Setting Environment Variables and Secrets

gcloud run services update adk-agent \
  --set-env-vars=GEMINI_MODEL=gemini-1.5-pro \
  --update-secrets=GEMINI_KEY=gemini-key:latest

If you need a VPC connector for private Google APIs, create it first:

gcloud compute networks vpc-access connectors create my-connector \
  --region us-central1 --range 10.8.0.0/28

Then attach:

gcloud run services update adk-agent \
  --vpc-connector=my-connector \
  --vpc-egress=all-traffic

—

Step 4: Building & Deploying to Production

Pushing to Google Container Registry (GCR)

docker tag my-adk-agent:latest gcr.io/$PROJECT_ID/my-adk-agent:stable
docker push gcr.io/$PROJECT_ID/my-adk-agent:stable

You can also let Cloud Build handle it:

gcloud builds submit --tag gcr.io/$PROJECT_ID/my-adk-agent:stable .

Deployment via Cloud Run GUI and gcloud CLI

The console lets you toggle min‑instances to keep one warm container:

gcloud run services update adk-agent \
  --min-instances=1 --max-instances=10

Set concurrency based on your latency target; --concurrency=80 works well for most chat‑style agents.

Verifying Deployment & Checking Logs

gcloud run services describe adk-agent --format="value(status.url)"
curl -X POST $(gcloud run services describe adk-agent --format="value(status.url)") \
  -d '{"prompt":"What is serverless?"}' -H "Content-Type: application/json"

Head to Logging → Cloud Run revisions to view request latency, memory usage, and any stack traces. If you see “Request timeout”, consider raising --timeout (default 300 s) or optimizing the model call.

—

Advanced Configuration & System Design

Scaling: Concurrency & Traffic Management

Cloud Run’s autoscaler balances instance count against request concurrency. A typical setup for chat agents:

gcloud run services update adk-agent \
  --concurrency=50 \
  --max-instances=50 \
  --cpu=2

Lower concurrency reduces latency per request but may increase cost. Our companion post “[Cost vs. Performance: Autoscaling on Cloud Run]” walks through the trade‑offs.

Integrating with Vertex AI & Other GCP Services

If you want to host a custom model on Vertex AI, expose it via an endpoint and call it from your ADK agent:

from google.cloud import aiplatform

endpoint = aiplatform.Endpoint("projects/../locations/us-central1/endpoints/1234567890")
def run(request):
    resp = endpoint.predict(instances=[request["prompt"]])
    return {"reply": resp.predictions[0]}

Remember to grant the Cloud Run service account the Vertex AI Viewer role.

Networking: VPC, Cloud Armor & Endpoint Security

A typical secure topology:

flowchart TD
    A[Client] --> B[Cloud Run Service]
    B --> C[VPC Connector]
    C --> D[Vertex AI Endpoint]
    B --> E[Secret Manager]
    B --> F[Cloud Armor]

• VPC Connector gives private egress to Vertex AI.
• Cloud Armor protects the public endpoint from DDoS.
• Secret Manager supplies API keys at runtime.

—

Common Errors & Fixes

Symptom	Why it Happens	Fix
“Container killed (Out of memory)”	Memory limit lower than model’s runtime need.	Increase Cloud Run memory to at least 1 GiB or swap a smaller model.
Cold start latency > 5 s	No min‑instances configured; image size > 800 MB.	Set --min-instances=1 and shrink Docker image (multi‑stage, strip dev wheels).
401 Unauthorized on Gemini API	Service account missing generativeai scope.	Grant roles/aiplatform.user and re‑authenticate the service account.
Failed to resolve external API hostname	No VPC egress or blocked by firewall.	Attach a VPC Connector and ensure egress is set to all-traffic.
Logs show “ImportError: No module named …”	Dependencies not copied into final stage.	Verify Dockerfile copies the site-packages folder from builder stage.

—

—

Wrapping Up

Deploying a Google AI Agent with Docker on Cloud Run blends the agility of serverless with the control of containers. By following the checklist above—minimal image, right memory, secret‑driven config, and optional VPC connectivity—you turn a fragile prototype into a production‑grade, auto‑scaling conversational service.

If you ran into a snag, drop a comment below or share your own deployment pattern. Happy scaling!