How to Deploy AI Agents to Google Cloud Using the Google Agent CLI

What the Google Agent CLI Actually Does

Deploying an AI agent to production has traditionally involved a lot of scaffolding, configuration, and manual wiring. Google’s Agent Development Kit (ADK) CLI changes that. It lets you go from a blank slate to a running agent on Google Cloud Platform in a single session — and when you pair it with Claude Code, most of the agent logic writes itself.

This guide covers the full workflow: installing the ADK CLI, scaffolding a project, building agent logic with Claude Code, evaluating performance, and deploying to GCP. It’s written for developers who want a reproducible, practical path from idea to production without fighting infrastructure.

---

Prerequisites Before You Start

Before running any commands, make sure you have the following in place.

Google Cloud Setup

You’ll need:

• A Google Cloud project with billing enabled
• The Google Cloud CLI installed and authenticated (gcloud auth login)
• The following APIs enabled in your project: Vertex AI, Cloud Run, Artifact Registry, and Cloud Build

Enable them in one shot:

gcloud services enable \
  aiplatform.googleapis.com \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com

Local Environment

You’ll need Python 3.10 or higher. The ADK CLI runs inside a Python virtual environment, so it’s a good idea to create one before installing:

python -m venv .venv
source .venv/bin/activate  # on Windows: .venv\Scripts\activate

You’ll also want Claude Code installed — this is Anthropic’s terminal-based coding agent. Install it via npm:

npm install -g @anthropic-ai/claude-code

Once installed, authenticate with your Anthropic API key:

claude auth

---

Installing the Google Agent Development Kit CLI

The ADK CLI is available via pip:

pip install google-adk

Verify the install:

adk --version

You should see the version number printed. If you get a “command not found” error, make sure your virtual environment is active and your Python environment’s bin directory is in your PATH.

The ADK CLI has a small set of focused commands:

Command	What it does
adk create	Scaffolds a new agent project
adk run	Runs the agent locally in the terminal
adk web	Opens a browser-based chat UI for testing
adk eval	Runs evaluation test cases against the agent
adk deploy	Deploys the agent to Google Cloud

That’s it. The simplicity is intentional — ADK tries to stay out of your way until you actually need it.

---

Scaffold Your Agent Project

Run the create command to generate a project skeleton:

adk create my-agent

You’ll be prompted to choose:

• A model — typically a Gemini model via Vertex AI, though you can configure other backends
• A template — options include a basic agent, a multi-tool agent, or a multi-agent setup

For a first deploy, choose the basic single-agent template. The CLI generates a directory with this structure:

my-agent/
├── agent.py          # Main agent logic
├── tools.py          # Tool definitions
├── eval/             # Evaluation test cases
│   └── test_case_1.evalset.json
├── requirements.txt
└── .env

The .env file holds your project configuration:

GOOGLE_CLOUD_PROJECT=your-project-id
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_VERTEXAI=TRUE

Set these values before moving on. The GOOGLE_CLOUD_LOCATION defaults to us-central1 — use whatever region is closest to your users or already in use for your project.

---

Use Claude Code to Build the Agent Logic

This is where the workflow gets efficient. Open the scaffolded project in Claude Code:

cd my-agent
claude

Claude Code will index your project and give you a chat interface to work from. From here, you can describe what you want the agent to do, and Claude will write the implementation directly into your files.

Example Prompt

Say you want to build a support triage agent that classifies incoming tickets and routes them to the right team. You’d prompt Claude something like:

Read agent.py and tools.py. I want this agent to:
1. Accept a customer support message as input
2. Classify it as billing, technical, or general
3. Summarize the issue in one sentence
4. Return the category and summary as structured output

Write the agent logic and any tools needed.

Claude Code will:

• Read the existing files for context
• Write the agent loop in agent.py
• Add any classification tools to tools.py
• Update requirements.txt if it pulls in new dependencies

You don’t need to specify the exact Vertex AI API syntax — Claude knows it. And because it’s editing the actual files, you can review the diff, ask for changes, and iterate in plain language.

Iterating with Claude Code

A few prompts that tend to work well during agent development:

• "Add input validation that rejects empty messages" — Claude adds guard logic to the agent
• "Rewrite the classification tool to use few-shot prompting with these examples: [examples]" — Claude refactors the specific function
• "Add error handling for Vertex AI timeout errors" — Claude wraps the API call in proper try/except logic

This loop — scaffold, describe intent, review output, refine — typically gets a working agent in 20–40 minutes for a moderately complex task.

---

Test Locally Before Deploying

Once the agent logic looks right, run it locally:

adk run my-agent

This starts the agent in the terminal and lets you send messages directly. It’s a quick sanity check that the code runs without errors before you spin up the web UI.

For a more interactive testing experience:

adk web

This opens a browser-based chat interface at localhost:8000. You can send test messages, see the agent’s responses, inspect the full reasoning trace, and check what tool calls were made in each turn.

The web UI is useful for catching issues that don’t show up in basic terminal testing — things like multi-turn context handling, tool output formatting, and edge cases in the classification logic.

---

Run Evaluations Against Test Cases

The ADK CLI includes a built-in evaluation system. The eval/ directory created during scaffolding holds .evalset.json files — structured test cases that define an input and the expected output.

Writing an Eval Set

A test case file looks like this:

[
  {
    "name": "billing_classification",
    "input": "I was charged twice for my subscription this month",
    "expected": {
      "category": "billing",
      "summary": "Customer reports a duplicate charge for their subscription"
    }
  },
  {
    "name": "technical_classification",
    "input": "My dashboard keeps showing a 500 error when I try to log in",
    "expected": {
      "category": "technical",
      "summary": "Customer is experiencing a 500 error on login"
    }
  }
]

You can write these by hand, or prompt Claude Code to generate a set of test cases based on the agent’s expected behavior.

Running the Evaluations

adk eval my-agent eval/test_cases.evalset.json

The CLI runs each test case, compares the output against expected values, and prints a pass/fail report. For structured output agents, it checks exact field matching. For free-text agents, it uses an LLM-based judge to score response quality.

Eval scores give you a baseline before deploy. If something breaks in a future update, running the same eval set will tell you immediately.

---

Deploy to Google Cloud

Once local tests and evals pass, deployment is one command:

adk deploy cloud_run \
  --project your-project-id \
  --region us-central1 \
  --service-name my-agent

What this does behind the scenes:

1. Builds a Docker container from your agent code
2. Pushes the container to Artifact Registry
3. Deploys it as a Cloud Run service
4. Returns the public URL for the agent endpoint

The entire process typically takes 3–6 minutes on the first deploy. Subsequent deploys are faster because the base layers are already cached.

Deployment Output

After a successful deploy, you’ll see something like:

✓ Building container image...
✓ Pushing to Artifact Registry...
✓ Deploying to Cloud Run...

Service URL: https://my-agent-xxxx-uc.a.run.app

Your agent is now accessible via HTTPS. Send a POST request to the /run endpoint with your input payload, and the agent responds.

Vertex AI Agent Engine (Alternative Deployment Target)

For teams that want tighter integration with Google’s managed agent infrastructure, you can also deploy to Vertex AI Agent Engine:

adk deploy vertex_ai \
  --project your-project-id \
  --region us-central1 \
  --display-name "Support Triage Agent"

This deploys the agent to Vertex AI’s managed runtime, which handles autoscaling, monitoring, and integration with other Vertex AI services like evaluation pipelines and model monitoring. It’s a better fit for enterprise deployments that need audit logging and VPC controls.

---

Common Issues and How to Fix Them

Authentication Errors on Deploy

If you see Permission denied or 403 errors during deployment, check that your active gcloud account has the right IAM roles:

gcloud projects add-iam-policy-binding your-project-id \
  --member="user:you@email.com" \
  --role="roles/run.admin"

You’ll also need roles/artifactregistry.writer and roles/cloudbuild.builds.editor for the full deploy pipeline.

Vertex AI Quota Errors

New GCP projects have default quota limits on Vertex AI requests per minute. If your agent hits these limits during testing, request a quota increase in the Google Cloud Console under IAM & Admin → Quotas.

Cold Start Latency on Cloud Run

Cloud Run scales to zero by default, meaning the first request after a period of inactivity incurs a cold start (typically 2–5 seconds). If that’s unacceptable for your use case, set a minimum instance count:

gcloud run services update my-agent \
  --min-instances=1 \
  --region us-central1

This keeps one instance warm at all times. It adds a small ongoing cost but eliminates the cold start.

Agent Returns Unexpected Output Format

If the agent’s output doesn’t match your expected schema, check whether the output schema is defined in agent.py. ADK supports Pydantic models for structured output — passing the model class to the agent constructor enforces the schema at runtime and raises clear validation errors instead of silently returning malformed data.

---

Where MindStudio Fits in This Workflow

The ADK CLI is a solid path for developers who want full control over their agent’s logic and infrastructure. But there’s a meaningful gap it doesn’t cover: what happens after the agent is deployed?

Most deployed agents don’t live in isolation. They need to trigger emails, write to spreadsheets, update CRM records, post to Slack, or feed into other workflows. Wiring all of that up manually — API by API — adds significant development overhead on top of the deployment work you’ve already done.

This is where MindStudio fills in. MindStudio’s Agent Skills Plugin is an npm SDK that gives any AI agent — including agents deployed via ADK — access to 120+ pre-built capabilities as simple method calls:

await agent.sendEmail({ to: "team@company.com", subject: "Triage result", body: summary });
await agent.updateAirtableRecord({ tableId: "...", recordId: "...", fields: { status: category } });
await agent.postSlackMessage({ channel: "#support", message: `New ticket classified: ${category}` });

The plugin handles auth, rate limiting, and retries — the infrastructure layer that nobody wants to build twice. Your agent focuses on reasoning; MindStudio handles the plumbing.

For teams that don’t need custom GCP infrastructure at all, MindStudio’s visual builder lets you build and deploy AI agents without writing code. The average build takes 15 minutes to an hour, and you get access to 200+ models and 1,000+ integrations out of the box. For use cases where you need agents to automate multi-step business workflows — not just return structured output — it’s often the faster path.

You can try MindStudio free at mindstudio.ai.

---

FAQ

What is the Google Agent Development Kit (ADK)?

The Google Agent Development Kit is an open-source Python framework and CLI for building, testing, and deploying AI agents. It provides a standardized project structure, a local testing environment, a built-in evaluation system, and deployment integrations with Google Cloud Run and Vertex AI Agent Engine. It’s designed to reduce the boilerplate involved in getting an agent from prototype to production on GCP.

Do I need to use Gemini models with the ADK CLI?

No. While ADK defaults to Gemini models via Vertex AI, it supports other model backends through LiteLLM and custom model wrappers. You can configure it to use Claude models from Anthropic or OpenAI models, though you’ll need to handle API key configuration and any GCP-specific auth separately. The default Gemini integration is the most streamlined path because it uses your existing GCP credentials.

How does Claude Code help with agent development?

Claude Code is a terminal-based AI coding agent that reads and edits your local files. In the context of ADK development, it’s useful for writing the agent logic, defining tools, generating evaluation test cases, and debugging issues — all through a conversational interface rather than by writing code from scratch. Because Claude Code understands the full file context of your project, it can make changes that are consistent with your existing code structure.

What’s the difference between deploying to Cloud Run vs. Vertex AI Agent Engine?

Cloud Run is a general-purpose container runtime. It’s flexible, fast to deploy, and cost-effective for most workloads. Vertex AI Agent Engine is Google’s managed runtime specifically for AI agents — it offers tighter integration with Vertex AI’s model monitoring, evaluation pipelines, and enterprise security controls (VPC Service Controls, audit logging, IAM-based access). For most teams starting out, Cloud Run is the right choice. Vertex AI Agent Engine makes more sense when you need enterprise compliance features or deep integration with the Vertex AI ecosystem.

How do I update a deployed agent?

Modify your local code, run adk eval to confirm the changes don’t break existing test cases, then re-run the deploy command:

adk deploy cloud_run \
  --project your-project-id \
  --region us-central1 \
  --service-name my-agent

Cloud Run handles the rollout automatically and keeps the previous revision available for rollback if needed.

Can I build multi-agent systems with the ADK CLI?

Yes. ADK supports multi-agent architectures where one orchestrator agent routes tasks to specialized sub-agents. The adk create scaffolding includes a multi-agent template that sets up the basic structure. You can also connect agents built with ADK to multi-agent workflows hosted on other platforms via API calls or webhook triggers.

---

Key Takeaways

• The Google ADK CLI gives you a complete scaffold-to-deploy workflow for AI agents on GCP, with commands for creating, running, evaluating, and deploying agents.
• Pairing the ADK CLI with Claude Code cuts development time significantly — describe what you want in plain language and Claude writes the implementation directly into your project files.
• Evaluations should run before every deploy. The adk eval command makes this easy and gives you a regression baseline you can reuse.
• Cloud Run is the right default deployment target for most teams. Vertex AI Agent Engine is worth considering when you need managed infrastructure, enterprise security controls, or tight integration with other Vertex AI services.
• Once your agent is deployed, connecting it to the rest of your business stack — email, CRM, messaging, databases — is the next challenge. MindStudio’s Agent Skills Plugin and no-code builder are both worth looking at for that layer.

If you’re building agents and want to skip the infrastructure work entirely, MindStudio lets you go from idea to working agent in a fraction of the time.