Google Agents Cli Deploy
Deploy a scaffolded ADK agent to Vertex AI Agent Runtime with deploy.py and Terraform—no Docker image required.
Overview
Google Agents CLI Deploy is an agent skill most often used in Ship (also Operate) that packages and releases scaffolded ADK agents to Vertex AI Agent Runtime using deploy.py and Terraform.
Install
npx skills add https://github.com/google/agents-cli --skill google-agents-cli-deployWhat is this skill?
- Source-based Vertex deployment: base64 tarball to Agent Runtime—no Dockerfile in the default path
- deploy.py flow via uv run -m app.app_utils.deploy with lockfile-exported .requirements.txt
- AdkApp hooks: set_up, register_operations, register_feedback, async_stream_query
- Terraform google_vertex_ai_reasoning_engine with lifecycle ignore on source_code_spec for CI updates
- Writes deployment_metadata.json with engine resource ID after create or update
- 3-step deployment flow: uv export requirements, deploy.py package and upsert runtime, write deployment_metadata.json
- 4 highlighted AdkApp surface areas: set_up, register_operations, register_feedback, async_stream_query
Adoption & trust: 12.4k installs on skills.sh; 2.7k GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
You have a working local ADK agent but no clear path to a managed Vertex runtime without inventing your own container pipeline.
Who is it for?
Solo builders already on google-agents-cli-scaffold who want GCP-managed agent hosting with Terraform-aligned infra.
Skip if: Custom non-ADK stacks or teams that require Docker-only deployment targets outside Vertex Agent Runtime.
When should I use this skill?
Your agents-cli scaffold project is ready to go live on Vertex AI Agent Runtime and you need the deploy.py and Terraform deployment path.
What do I get? / Deliverables
You run the scaffolded deploy CLI, get a live Reasoning Engine instance, and capture deployment_metadata.json for CI and downstream monitoring hooks.
- Deployed Vertex AI Reasoning Engine instance
- deployment_metadata.json with engine resource identifier
Recommended Skills
Journey fit
Spans multiple journey phases - primary shelf plus alternate fits below.
Ship/Launch is the primary shelf because the skill walks through packaging source and promoting the agent to managed Vertex Agent Runtime. Launch covers go-live deployment mechanics, metadata files, and runtime registration—not local coding alone.
Where it fits
You finalize agent_runtime_app.py AdkApp methods before the first remote smoke deploy.
You run deploy.py after uv lock export to flip on a managed Reasoning Engine for beta users.
CI pushes new source bundles while Terraform keeps concurrency limits stable across releases.
How it compares
Vertex source-deploy workflow for AdkApp—not a generic Cloud Run Dockerfile tutorial.
Common Questions / FAQ
Who is google-agents-cli-deploy for?
Indie developers with agents-cli scaffold projects who need to push agent code to Vertex AI Agent Runtime without hand-rolling packaging scripts.
When should I use google-agents-cli-deploy?
Use it in Ship when launching to production; in Operate when updating engine source via CI while Terraform holds scaling and infra; after Build when the agent locally streams correctly.
Is google-agents-cli-deploy safe to install?
Deploy touches production GCP APIs and IAM; review Terraform plans, service accounts, and the Security Audits panel on this page before applying to shared projects.
Workflow Chain
Requires first: google agents cli scaffold
Then invoke: google agents cli observability
SKILL.md
READMESKILL.md - Google Agents Cli Deploy
# Agent Runtime Infrastructure > **Assumes `/google-agents-cli-scaffold` scaffolding.** If your project isn't scaffolded yet, see `/google-agents-cli-scaffold` first. ## Deployment Architecture Agent Runtime uses **source-based deployment** — no Docker container or Dockerfile. Your agent code is packaged as a base64-encoded tarball and deployed directly to the managed Vertex AI service. **App class:** Your agent extends `AdkApp` (from `vertexai.agent_engines.templates.adk`). Check `agent_runtime_app.py` for the exact implementation. Key methods: - `set_up()` — Initialization (Vertex AI client, telemetry) - `register_operations()` — Declare operations exposed to Agent Runtime - `register_feedback()` — Collect and log user feedback - `async_stream_query()` — Streaming response method ## deploy.py CLI Scaffolded projects deploy via `uv run -m app.app_utils.deploy`. Run `uv run -m app.app_utils.deploy --help` for the full flag reference. **Deployment flow:** 1. `uv export` generates `.requirements.txt` from lockfile 2. `deploy.py` packages source, creates/updates the Agent Runtime instance 3. Writes `deployment_metadata.json` with the engine resource ID ## Terraform Resource Agent Runtime uses `google_vertex_ai_reasoning_engine` in `deployment/terraform/service.tf`. Check that file for current scaling, concurrency, and resource limit settings. Key difference from Cloud Run: the `lifecycle.ignore_changes` on `source_code_spec` is critical — source code is updated by CI/CD, not Terraform. ## deployment_metadata.json Written by `deploy.py` after successful deployment: ```json { "remote_agent_runtime_id": "projects/PROJECT/locations/LOCATION/reasoningEngines/ENGINE_ID", "deployment_target": "agent_runtime", "is_a2a": false, "deployment_timestamp": "2025-02-25T10:30:00.000Z" } ``` Used by: subsequent deploys (update vs create), testing notebook, `agents-cli run --url`. Cloud Run does not use this file. If deployment times out but the engine was created, manually populate this file with the engine resource ID. ## CI/CD Differences from Cloud Run | Aspect | Agent Runtime | Cloud Run | |--------|-------------|-----------| | **Build** | `uv export` → requirements file | Docker build → container image | | **Deploy command** | `uv run -m app.app_utils.deploy` | `gcloud run deploy --image ...` | | **Artifact** | Base64 source tarball | Container image in Artifact Registry | | **Python version** | Fixed at 3.12 (Terraform) | Configurable in Dockerfile | | **Load testing** | Via `locust` against Agent Runtime endpoint | Direct HTTP to Cloud Run URL | ## Playground & Remote Testing ```bash # Local mode (uses local agent instance) agents-cli playground # Query your deployed Agent Runtime remotely (ADK agent) agents-cli run --url https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT/locations/LOCATION/reasoningEngines/ID --mode adk "Hello, what can you do?" ``` `--mode` is required with `--url`: use `adk` for the ADK streaming API (`:streamQuery`) or `a2a` for the A2A protocol. Add `-v` for full JSON event payloads. Auth is auto-detected via Google Cloud credentials. To query Agent Runtime programmatically: ```python import vertexai client = vertexai.Client(location="us-east1") agent = client.agent_engines.get(name="projects/PROJECT/locations/LOCATION/reasoningEngines/ENGINE_ID") async for event in agent.async_stream_query(message="Hello!", user_id="test"): print(event) ``` ## Session & Artifact Services | Service | Configuration | Notes | |---------|--------------|-------| | **Sessions** | `InMemorySessionService` (default) | Stateless; state per connection | | **Sessions** | `VertexAiSessionService` | Native managed sessions (persistent) | | **Artifacts** | `GcsArtifactService` | Uses `LOGS_BUCKET_NAME` env var | | **Artifacts** | `InMemoryArtifactService` | Fallback when no bucket configured | Environment variables set during deployment are configured in `deploy.py` and `deployment/terraform/ser