Deployment

Deploy your agent to a development environment or production with a CI/CD pipeline.

Prototype to Production

Infrastructure vs deployment#

Infrastructure (agents-cli infra) provisions the cloud resources your agent needs: service accounts, IAM bindings, APIs, telemetry buckets, and Terraform state. It doesn't run your agent.

Deployment (agents-cli deploy) takes your agent code and puts it on the provisioned infrastructure. It builds a container, pushes it to a registry, and starts the service.

A dev deployment doesn't need provisioned infrastructure: agents-cli deploy works on its own. Run agents-cli infra single-project --apply first only when you want Terraform to manage resources such as prompt-response logging and BigQuery Agent Analytics.

Deploy to a dev environment#

To get a running deployment in two steps:

1. Set your dev project:

gcloud config set project YOUR_DEV_PROJECT_ID

2. Deploy the agent:

agents-cli deploy --project YOUR_DEV_PROJECT_ID

Without --project, the deploy reads the project from gcloud config and stops to ask you to confirm it. Pass --no-confirm-project to skip the check, or -i to answer a prompt.

The command reads your deployment_target from agents-cli-manifest.yaml (under create_params) and dispatches to the right flow:

`deployment_target`	What happens
`agent_runtime`	Deployment to Agent Runtime in Gemini platform (fully managed)
`cloud_run`	`gcloud run deploy` (container on Cloud Run)
`gke`	Terraform + `gcloud builds submit` + `kubectl set image`

To override the manifest, or to deploy without one (for example, from CI), pass -d or --deployment-target.

The deployment target is set when you create your project:

agents-cli create my-agent -a adk_python -d cloud_run    # or agent_runtime, gke

To change the deployment target for an existing project, use scaffold enhance:

agents-cli scaffold enhance -d cloud_run

Run agents-cli scaffold enhance --help to see all available options.

Terraform-managed observability

For prompt-response logging and BigQuery Agent Analytics, run agents-cli infra single-project --apply before your first deploy, never after, because Terraform can't take over a resource that agents-cli deploy already created. On Cloud Run, and on Agent Runtime projects that run as a service account, pass the Terraform-created account with --service-account SA_EMAIL. See the Observability guide.

Verify it works:

agents-cli deploy --list    # List deployments
agents-cli deploy --status  # Check a pending --no-wait deployment

Deployment targets#

Agent Runtime#

Selected with agents-cli create my-agent -a <template> -d agent_runtime, or create_params.deployment_target: agent_runtime in agents-cli-manifest.yaml.

Agent Runtime is fully managed. You provide a Dockerfile (scaffolded for you), and Agent Runtime builds and runs the container. There is no cluster or service to operate. The LangChain and Claude templates are experimental on Agent Runtime and have limits, such as publish gemini being refused. See First-party frameworks. Deploy with:

agents-cli deploy --project my-gcp-project --region us-east1

You can pass Docker build args or a container port:

agents-cli deploy --project my-gcp-project --build-args KEY=VALUE --port 8080

Or deploy a prebuilt Artifact Registry image instead of building from the Dockerfile. The Agent Runtime service agent (service-PROJECT_NUMBER@gcp-sa-aiplatform-re.iam.gserviceaccount.com) needs roles/artifactregistry.reader on the repository:

agents-cli deploy --project my-gcp-project --image us-docker.pkg.dev/my-project/my-repo/my-agent:v1

An existing agent can't switch between a source build and --image, in either direction. Agents provisioned by the scaffolded Terraform count as source builds. On the first deploy of a new agent with Agent Identity, the image starts once before its env vars and secrets are applied, so it must start without them.

Check on an async deployment:

agents-cli deploy --project my-gcp-project --no-wait  # Start and return immediately
agents-cli deploy --status      # Check progress later

Cloud Run#

Selected with agents-cli create my-agent -a <template> -d cloud_run, or create_params.deployment_target: cloud_run in agents-cli-manifest.yaml.

Builds a container from source and deploys as a Cloud Run service:

agents-cli deploy --project my-gcp-project --region us-east1

Override resource limits:

agents-cli deploy --project my-gcp-project --memory 8Gi --port 8080

Deploy a pre-built image instead of building from source:

agents-cli deploy --project my-gcp-project --image gcr.io/my-project/my-agent:v1

The service is private by default. The deploy command always passes --no-allow-unauthenticated, and the CLI has no flag to make the service public. Callers need an identity token, and agents-cli run "PROMPT" --url SERVICE_URL --mode a2a adds one for you. Use --mode a2a for any template and --mode adk for ADK templates. Add --iap to put Identity-Aware Proxy in front of it, or pass --ingress internal (or internal-and-cloud-load-balancing) to limit which networks can reach it.

New projects run the service as its own Agent Identity principal, and --service-account is then ignored. Opt out at scaffold time with --cloud-run-identity-default service_account. A project created before Agent Identity became the default opts in with --agent-identity on the first deploy. You can't turn it off later without deleting the service. Grant secret access to the service account (app_sa) even then, because Cloud Run checks that account when it deploys.

Tip

If you need Cloud Run features that agents-cli flags don't expose, use --dry-run (or -n) to print the full gcloud command. Then copy it and add the arguments you need.

The dry run first runs read-only checks on Google Cloud. They run as your gcloud account, which the deploy uses, or as your Application Default Credentials when gcloud's token does not work for direct API calls. The output names the account. If it is not the account gcloud deploys as, failed checks only warn (⚠️). It still prints the command when a check fails (❌), but then exits with code 1.

GKE#

Selected with agents-cli create my-agent -a <template> -d gke, or create_params.deployment_target: gke in agents-cli-manifest.yaml.

Deploys to a GKE cluster using Terraform and kubectl:

agents-cli deploy --project my-gcp-project

The deploy targets the cluster that Terraform creates, which has the same name as your agent project. To deploy to an existing cluster with a different name, add --cluster-name CLUSTER_NAME.

Tip

Use --dry-run (or -n) to see the Terraform, Cloud Build and kubectl steps without running them. The dry run first runs read-only checks on Google Cloud: the APIs, the cluster and your IAM permissions.

gcloud and kubectl steps are checked as your gcloud account. Terraform steps are checked as your Application Default Credentials.
kubectl is checked as your Application Default Credentials instead when CLOUDSDK_CONTAINER_USE_APPLICATION_DEFAULT_CREDENTIALS is true.
If gcloud's token does not work for direct API calls (for example, it is bound to a client certificate), the gcloud steps are checked as your Application Default Credentials instead, and if those are a different account from the one gcloud deploys as, their failed checks only warn (⚠️).
If your Application Default Credentials do not work, the Terraform permissions are not checked, and kubectl is checked as your gcloud account. The output says so (⚠️).
If Terraform reads other credentials, for example from GOOGLE_CREDENTIALS or a provider setting, the Terraform permissions are not checked, and the output says so (⚠️).

The dry run still prints the steps when a check fails (❌), but then exits with code 1.

Next steps#

CI/CD and production: set up automated pipelines for staging and production
Observability: monitor your deployed agent