Google ADK Production Guide (Python)
Deploying Google ADK agents with the adk CLI and the Agent Platform SDK: Agent Engine, Cloud Run and GKE, plus persistent sessions, authentication, telemetry, cost controls, guardrails and testing.
Checked against google-adk 2.13.0 on 2026-11-19. The adk deploy options below are taken from the CLI’s own --help and source, the Python examples were run locally against a stub model, and the Agent Platform SDK calls were checked against google-cloud-aiplatform 2.6. Nothing here was deployed to a live project, so treat the cloud commands as a starting point and read the output of the first run.
This page covers what ADK itself gives you for production. For IAM roles and credentials see IAM, auth and credentials; for the command line as a whole see Project layout and the adk CLI.
Deployment targets
Section titled “Deployment targets”ADK deploys an agent folder: a Python package whose agent.py defines root_agent (an agent, or a Workflow), or that holds a root_agent.yaml. Every target runs the same FastAPI server as adk api_server.
| Target | Command | What you get |
|---|---|---|
| Vertex AI Agent Engine | adk deploy agent_engine | Managed runtime with Agent Platform Sessions and Memory Bank wired in, scaling and IAM handled by Google Cloud |
| Cloud Run | adk deploy cloud_run | A container built by Cloud Build from source (gcloud run deploy --source), stored in Artifact Registry |
| GKE | adk deploy gke | A container built by Cloud Build, plus a Deployment and a ClusterIP Service applied with kubectl |
| Local Docker | adk deploy docker | The same image, run locally, for testing the container |
| Your own server | get_fast_api_app(...) | The ADK app as a FastAPI object you can add routes and middleware to, then deploy however you like |
Pick Agent Engine when you want managed sessions and memory and no container to run. Pick Cloud Run or GKE when the agent has to sit next to your other services, in your VPC, behind your own authentication.
Prepare the agent folder
Section titled “Prepare the agent folder”my_agent/├── __init__.py # from . import agent├── agent.py # defines root_agent├── requirements.txt # your dependencies; google-adk is added by the deployer├── .env # local development only (listed in .gitignore)└── .gitignoreadk create my_agent produces this layout. Two things to know before the first deploy:
- Ignored files stay behind.
adk deploycopies the folder but skips anything matched by its.gitignore,.gcloudignoreor.ae_ignore, and always skips the local.adk/folder of development sessions. .envis read byadk deploy agent_engine. Its values (apart from the project, region and service account, which become deploy settings) are forwarded to the deployed agent as plain environment variables. Keep API keys and passwords out of.envfor deployment and use Secret Manager instead (see Secrets below).
Pin the ADK version you tested with. Each deploy command takes --adk_version, which defaults to the version installed where you run it.
Agent Engine with adk deploy
Section titled “Agent Engine with adk deploy”gcloud services enable aiplatform.googleapis.com cloudbuild.googleapis.com
adk deploy agent_engine \ --project "$PROJECT_ID" \ --region europe-west2 \ --display_name "support-agent" \ --service_account "support-agent@$PROJECT_ID.iam.gserviceaccount.com" \ --otel_to_cloud \ my_agentWhat this does (from cli/cli_deploy.py):
- Stages the folder, adds
google-cloud-aiplatform[adk,agent_engines]andgoogle-adktorequirements.txt, and writes a Dockerfile that runsadk api_server. - Creates an Agent Engine instance (a
reasoningEnginesresource) and uploads the source; Cloud Build builds the image. - Points sessions and memory at the instance itself (
agentengine://<resource>), so conversations and memories persist without extra configuration. - Prints the resource name. Pass it back as
--agent_engine_idto update the same instance instead of creating a new one.
Useful options:
| Option | Purpose |
|---|---|
--service_account | Runtime identity (new in 2.12.0). Without it Agent Engine uses its default service agent. Give the account only the roles the agent needs. |
--agent_engine_id | Update an existing instance in place. |
--otel_to_cloud | Export traces, metrics and logs to Cloud Observability. Prompt and response text is not captured in spans unless you set ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS. |
--worker_pool | Build with a private Cloud Build pool (VPC Service Controls, private networks). |
--extra_packages | Ship local packages that live outside the agent folder. |
--trigger_sources pubsub,eventarc | Register /apps/{app}/trigger/* endpoints for event-driven runs; restrict callers with --trigger_oidc_audience and --trigger_oidc_service_accounts. |
--agent_engine_config_file | Read settings such as scaling and labels from .agent_engine_config.json; command-line flags override it. |
--staging_bucket, --adk_app, --env_file, --requirements_file and --trace_to_cloud are accepted but deprecated and ignored or due for removal.
Agent Engine from Python
Section titled “Agent Engine from Python”When the deployment is part of a larger script or pipeline, use the Agent Platform SDK (the agentplatform package in google-cloud-aiplatform 2.x; the older vertexai.Client still works but warns that it is deprecated). AdkApp wraps an agent or an App and is also how you test the deployed behaviour locally:
import asyncio
from google.adk.agents import Agentfrom agentplatform.frameworks import AdkApp
root_agent = Agent( name="support", model="gemini-3.8-flash", instruction="Answer briefly and politely.",)
app = AdkApp(agent=root_agent)
async def main(): # Locally, AdkApp uses in-memory sessions; on Agent Engine it uses Agent Platform Sessions. session = await app.async_create_session(user_id="u1") async for event in app.async_stream_query( user_id="u1", session_id=session["id"], message="Where is my order?" ): print(event["content"]["parts"][0]["text"])
asyncio.run(main())Events come back as dictionaries, not Event objects, because they are the same JSON the remote service returns. To deploy the same object:
import agentplatform
client = agentplatform.Client(project="my-project", location="europe-west2")
remote = client.runtimes.create( agent=app, # the AdkApp from above config={ "display_name": "support-agent", "staging_bucket": "gs://my-project-agent-staging", # required when passing an object "requirements": ["google-cloud-aiplatform[adk,agent_engines]>=2.2,<3"], "service_account": "support-agent@my-project.iam.gserviceaccount.com", "env_vars": { "SUPPORT_API_KEY": {"secret": "support-api-key", "version": "latest"}, # Secret Manager }, "min_instances": 1, },)print(remote.api_resource.name) # projects/.../locations/.../reasoningEngines/...client.runtimes.get(name=...) returns a handle with async_stream_query, async_create_session and the other AdkApp methods, now running remotely. client.runtimes.update(...) and client.runtimes.delete(...) manage the instance. A value in env_vars that is a dictionary becomes a Secret Manager reference rather than a plain variable.
Cloud Run
Section titled “Cloud Run”gcloud services enable run.googleapis.com cloudbuild.googleapis.com artifactregistry.googleapis.com
adk deploy cloud_run \ --project "$PROJECT_ID" \ --region europe-west2 \ --service_name support-agent \ --session_service_uri "postgresql+asyncpg://agent@/sessions?host=/cloudsql/$PROJECT_ID:europe-west2:agents" \ --artifact_service_uri "gs://$PROJECT_ID-agent-artifacts" \ --otel_to_cloud \ my_agent \ -- --no-allow-unauthenticated \ --service-account "support-agent@$PROJECT_ID.iam.gserviceaccount.com" \ --add-cloudsql-instances "$PROJECT_ID:europe-west2:agents" \ --set-secrets "DB_PASSWORD=agent-db-password:latest" \ --min-instances 1- Everything after
--goes togcloud run deploy(--provider-argsdoes the same, one flag per use, and--env KEY=valuesets environment variables). ADK does not choose an authentication mode for you; without--no-allow-unauthenticated(or--allow-unauthenticated) gcloud asks interactively. Keep the service private unless it really is public. - The image is built from source by Cloud Build and stored in Artifact Registry (the
cloud-run-source-deployrepository in the region). - Choose session storage. With no
--session_service_uri, Cloud Run gets in-memory sessions (the container’s folder is not writable), so conversations are lost when an instance stops and are not shared between instances. Use a database URI (postgresql+asyncpg://…,mysql+aiomysql://…) oragentengine://<resource>to use Agent Platform Sessions. Artifacts default to in-memory too;gs://bucketstores them in Cloud Storage. --with_uialso deploys the Dev UI. It is a development tool; leave it off in production.--a2aadds the A2A endpoint; see MCP and A2A.
Callers need roles/run.invoker and an identity token:
gcloud run services add-iam-policy-binding support-agent --region europe-west2 \ --member "serviceAccount:frontend@$PROJECT_ID.iam.gserviceaccount.com" --role roles/run.invoker
URL=$(gcloud run services describe support-agent --region europe-west2 --format 'value(status.url)')TOKEN=$(gcloud auth print-identity-token)curl -s -X POST "$URL/apps/my_agent/users/u1/sessions" -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" -d '{}'The runtime service account needs roles/aiplatform.user for Gemini on Vertex AI, plus whatever the session and artifact stores need (roles/cloudsql.client, roles/storage.objectUser, roles/secretmanager.secretAccessor).
adk deploy gke \ --project "$PROJECT_ID" \ --region europe-west2 \ --cluster_name agents \ --service_name support-agent \ --session_service_uri "postgresql+asyncpg://..." \ --otel_to_cloud \ my_agentadk deploy gke builds the image with Cloud Build, fetches cluster credentials, and applies a Deployment and Service. The Service is ClusterIP by default, so the agent is reachable only inside the cluster; --service_type LoadBalancer exposes a public IP, with no authentication in front of it, so put an authenticating gateway or Identity-Aware Proxy in front instead.
The command tags the image as gcr.io/PROJECT/SERVICE:TIMESTAMP. Since Container Registry was shut down, gcr.io paths only work in projects that have gcr.io repositories in Artifact Registry. If yours does not, or if you need your own manifests (Workload Identity, resource limits, a PodDisruptionBudget), build the image yourself and push it to an Artifact Registry repository (REGION-docker.pkg.dev/PROJECT/REPO/IMAGE). The image ADK generates is simple: a python:3.11-slim base, your folder under /app/agents, pip install google-adk plus your requirements.txt, a non-root user, the development-only dev_server module removed, and adk api_server with the service URIs as its command. The generated files are deleted after each deploy.
Your own server
Section titled “Your own server”adk api_server and every deploy target serve get_fast_api_app(). Call it yourself when you need extra routes or middleware, such as your own authentication:
# main.py, next to the my_agent/ folderimport os
from google.adk.cli.fast_api import get_fast_api_app
AGENTS_DIR = os.path.dirname(os.path.abspath(__file__))
app = get_fast_api_app( agents_dir=AGENTS_DIR, session_service_uri=os.environ.get("SESSION_SERVICE_URI", "sqlite:///./sessions.db"), allow_origins=["https://app.example.com"], web=False, # API only; the Dev UI is for local development)
@app.get("/healthz")def healthz() -> dict: return {"status": "ok"}Run it with uvicorn main:app --host 0.0.0.0 --port 8080. The main endpoints are POST /apps/{app}/users/{user}/sessions to create a session, POST /run for a complete turn and POST /run_sse to stream events (the run is cancelled if the client disconnects). The server’s endpoints are unauthenticated: put it behind Cloud Run IAM, IAP or your own middleware. Other useful arguments: memory_service_uri, artifact_service_uri, otel_to_cloud, a2a, max_llm_calls and auto_create_session.
Sessions, memory and artifacts
Section titled “Sessions, memory and artifacts”The --*_service_uri options (and the matching get_fast_api_app arguments) choose the storage:
| Service | URI | Notes |
|---|---|---|
| Sessions | postgresql+asyncpg://…, mysql+aiomysql://… | DatabaseSessionService; needs google-adk[db] and the async driver |
| Sessions | sqlite:///path.db | SqliteSessionService (single process; no extra install) |
| Sessions | agentengine://<resource or id> | Agent Platform Sessions; the default on Agent Engine |
| Memory | agentengine://<resource or id> | Memory Bank; the default on Agent Engine |
| Memory | rag://<corpus> | Vertex AI RAG memory |
| Artifacts | gs://bucket | GcsArtifactService |
| Any | memory:// | In-memory, for tests |
In code, the same services are constructor arguments on Runner (see Runner, App and Sessions).
Secrets
Section titled “Secrets”- Cloud Run:
--set-secrets NAME=secret:versionafter--; the value arrives as an environment variable or a mounted file. - Agent Engine from Python: a dictionary value in
env_vars, as above. - Inside tools: ADK’s Secret Manager client (
google.adk.integrations.secret_manager) and authenticated tools are covered in IAM, auth and credentials.
Never put keys in instruction text or session state: both are sent to the model and stored with the session.
Observability
Section titled “Observability”--otel_to_cloud(all deploy targets,adk web,adk api_server) exports OpenTelemetry traces, metrics and logs to Cloud Trace, Cloud Monitoring and Cloud Logging. Installgoogle-adk[gcp]for the exporters when you run your own server.- ADK emits spans for each invocation, agent run, model call and tool call, and
gen_ai.client.*metrics for token usage and latency. From 2.13.0 the default span schema follows the OpenTelemetry GenAI conventions (root spaninvoke_workflow, nocall_llmspan); see Observability before you update dashboards or alerts. - In your own process,
google.adk.telemetry.setup.maybe_set_otel_providers(otel_hooks_to_setup=[hooks]), withhooks = google.adk.telemetry.google_cloud.get_gcp_exporters(enable_cloud_tracing=True, enable_cloud_metrics=True, enable_cloud_logging=True), sets the same thing up by hand.
For your own usage log, a runner plugin sees every model call across all agents:
import logging
from google.adk.agents import Agentfrom google.adk.agents.callback_context import CallbackContextfrom google.adk.apps import Appfrom google.adk.models.llm_response import LlmResponsefrom google.adk.plugins.base_plugin import BasePlugin
log = logging.getLogger("agent.usage")
class UsagePlugin(BasePlugin): """Logs one structured line per completed model call."""
def __init__(self) -> None: super().__init__(name="usage")
async def after_model_callback( self, *, callback_context: CallbackContext, llm_response: LlmResponse ) -> LlmResponse | None: usage = llm_response.usage_metadata if usage and not llm_response.partial: log.info( "model_call", extra={ "agent": callback_context.agent_name, "invocation_id": callback_context.invocation_id, "prompt_tokens": usage.prompt_token_count, "output_tokens": usage.candidates_token_count, "cached_tokens": usage.cached_content_token_count, }, ) return None # leave the response unchanged
root_agent = Agent(name="support", model="gemini-3.8-flash", instruction="Answer briefly.")app = App(name="support", root_agent=root_agent, plugins=[UsagePlugin()])BigQueryAgentAnalyticsPlugin (google-adk[bigquery-analytics]) writes the full event stream to BigQuery instead; see Callbacks and plugins.
Cost and context controls
Section titled “Cost and context controls”These live on the App and RunConfig, not in your infrastructure:
from google.adk.agents import Agentfrom google.adk.agents.context_cache_config import ContextCacheConfigfrom google.adk.agents.run_config import RunConfigfrom google.adk.apps import Appfrom google.adk.apps.app import EventsCompactionConfig
root_agent = Agent( name="support", model="gemini-3.8-flash", static_instruction="You are the support agent for Example Ltd. ...", # stable prefix, cache-friendly instruction="The customer's tier is {user:tier?}.",)
app = App( name="support", root_agent=root_agent, # Summarise older events so long sessions do not resend the whole history. events_compaction_config=EventsCompactionConfig(compaction_interval=10, overlap_size=2), # Explicit Gemini context caching for the stable part of the prompt. context_cache_config=ContextCacheConfig(ttl_seconds=1800, min_tokens=4096),)
run_config = RunConfig(max_llm_calls=20) # hard cap on model calls per invocation- Compaction (
EventsCompactionConfig) replaces older events with an LLM-written summary everycompaction_intervalinvocations, or once the prompt passestoken_threshold. - Context caching (
ContextCacheConfig) creates Gemini cached content for the stable prefix. Gemini applies its own minimum size, so short prompts are not cached; checkcached_content_token_countin the usage log above. Implicit caching works without configuration if stable text comes first, which is whatstatic_instructionis for. max_llm_callsstops runaway tool loops.adk api_serverandget_fast_api_appalso acceptmax_llm_calls, and theADK_MAX_LLM_CALLSenvironment variable sets a process-wide default.- Model choice per agent. Give routers and classifiers a small model (
gemini-3.5-flash-lite) and keep the larger one for the agents that need it.
Details and the exact trigger rules are in Runner, App and Sessions.
Reliability
Section titled “Reliability”from google.adk.agents import Agentfrom google.adk.apps import Appfrom google.adk.models import FallbackModelfrom google.adk.models.google_llm import Geminifrom google.adk.plugins import ReflectAndRetryToolPluginfrom google.genai import types
primary = Gemini( model="gemini-3.8-flash", retry_options=types.HttpRetryOptions(attempts=4, initial_delay=1.0, max_delay=20.0),)
root_agent = Agent( name="support", # Try the primary model (with its retries), then the backup on 429/5xx. model=FallbackModel(models=[primary, "gemini-3.5-flash-lite"]), instruction="Answer briefly.",)
app = App( name="support", root_agent=root_agent, # When a tool raises, show the error to the model and let it correct its call. plugins=[ReflectAndRetryToolPlugin(max_retries=2)],)Gemini(retry_options=...)retries one model on transient HTTP errors.FallbackModel(2.9.0, experimental) moves to the next model only on 429 and 5xx, and only before the first response chunk, so a streamed turn is never stitched together from two models.ReflectAndRetryToolPluginhandles tool failures;on_tool_error_callbackgives you full control.- For long, multi-step runs,
App(resumability_config=ResumabilityConfig(is_resumable=True))lets an interrupted invocation resume from where it stopped. Workflow nodes that fail are re-run on resume, so make their side effects idempotent.
Guardrails
Section titled “Guardrails”The Model Armor plugin (2.8.0, google-adk[gcp]) screens user input, model output and tool output with Model Armor templates you create in the console or with gcloud model-armor templates create:
from google.adk.agents import Agentfrom google.adk.apps import Appfrom google.adk.integrations.model_armor import ModelArmorConfig, ModelArmorPlugin
TEMPLATE = "projects/my-project/locations/europe-west2/templates/agent-default"
root_agent = Agent(name="support", model="gemini-3.8-flash", instruction="Answer briefly.")
app = App( name="support", root_agent=root_agent, plugins=[ ModelArmorPlugin( config=ModelArmorConfig( prompt_template_name=TEMPLATE, response_template_name=TEMPLATE, tool_output_template_name=TEMPLATE, deidentify_sensitive_data=True, # pass on de-identified text when only SDP matched ) ) ],)Blocked content is replaced with the configured message, and by default a screening failure blocks too (block_on_screening_failure=True). For rules of your own, a plugin’s before_tool_callback can refuse a call by returning a result dictionary, and after_tool_callback can filter what a tool returns before the model sees it (2.12.0). Gemini’s own safety_settings go in the agent’s generate_content_config.
Testing and CI
Section titled “Testing and CI”- Unit tests without a model. Register a
BaseLlmsubclass for test model names, or pass a stub model instance to the agent, and drive it withInMemoryRunner(...).run_debug(...). - Behaviour tests.
adk eval my_agent my_agent/tests/smoke.evalset.json --config_file_path my_agent/test_config.jsonruns eval sets and prints a pass/fail summary (the exit status is non-zero on any failure from 2.13.0, so it can gate a CI step);AgentEvaluatordoes the same from pytest. See Evaluation. - Deploy from CI by running the same
adk deploy …command in Cloud Build or GitHub Actions, authenticated with Workload Identity Federation rather than a key file. Pass--agent_engine_id(Agent Engine) or a fixed--service_name(Cloud Run, GKE) so each run updates the existing deployment.
A minimal Cloud Build step:
steps: - name: python:3.13-slim entrypoint: bash args: - -c - | pip install "google-adk[eval]==2.13.0" pytest adk eval my_agent my_agent/tests/smoke.evalset.json --config_file_path my_agent/test_config.json - name: gcr.io/google.com/cloudsdktool/google-cloud-cli:slim entrypoint: bash args: - -c - | pip install "google-adk==2.13.0" adk deploy cloud_run --project "$PROJECT_ID" --region europe-west2 \ --service_name support-agent my_agent -- --no-allow-unauthenticatedCheck that the build image has the Python version ADK needs (3.11 or later) before relying on the second step.