Chapter 10
Deploy your first agent to Vertex AI Agent Engine
# Copyright 2025 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# https://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.Deploy your first agent to Vertex AI Agent Engine
Share to:
| Authors |
|---|
| Yee Sian Ng |
| Shawn Yang |
| Ivan Nardini |
Overview
This tutorial shows you how to deploy an Agent Development Kit (ADK) agent to Google Cloud's Agent Engine.
You'll deploy an AI agent with Google Search capability that can retrieve real-time information from the web.
You will start with Express Mode (Free & Easy!) using ADK CLI.
Then, you will explore the following advanced deployment methods:
- Method 1: Agent object - Deploy agents for interactive development
- Method 2: Inline Source - Deploy from source files for CI/CD pipelines
Get started with Express Mode (Start here!)
If you are a new Vertex AI user, Express Mode provides:
- Free for 90 days - No billing account needed
- Quick setup - Just sign in with your Gmail
- Simple authentication - Use an API key instead of complex service accounts
- Learn by doing - Perfect for tutorials, prototypes, and experimentation
This is the recommended starting point for all developers new to Vertex AI Agent Engine.
Get Your API Key
First, let's get you set up with Express Mode and grab your API key. This only takes a couple of minutes!
Here's what you'll do:
-
Sign up for Express Mode: Head over to console.cloud.google.com/expressmode and sign in with your plain and new Gmail account.
-
Choose your tier:
- New to Google Cloud? Select the free tier - you get 90 days of free access, no credit card needed!
- Already have a Google Cloud account? You can use your existing billing account.
-
Grab your API key:
- Navigate to APIs & Services > Credentials: console.cloud.google.com/apis/credentials
- Look for the API Keys section
- Copy your Generative Language API Key
Important: Keep your API key safe! Don't share it publicly or commit it to your GitHub repos. Think of it like a password.
Save Your API Key
Let's securely save your API key in this notebook. Run the cell below and paste your API key when prompted - don't worry, it will be hidden as you type!
Install required packages
Start with installing the required packages.
%pip install --upgrade --quiet "google-adk @ git+https://github.com/google/adk-python.git@agent-engine-express-mode"from getpass import getpass
# Enter your API key when prompted (it will be hidden)
api_key = getpass("Enter your Generative Language API Key: ")
print("✅ API key saved successfully!")
print(" You can now deploy your agent using Express Mode")Create Your First Agent
Time to create your agent! We'll use the ADK CLI to set up a new agent project. This creates a directory with all the files you need, including saving your API key so you don't have to enter it again.
Run the cell below and when prompted, choose option 1 to select the Gemini 2.5 Flash model.
# Create a new ADK agent project
!adk create my_agent --api_key={api_key}
print("\n✅ Agent project created successfully!")
print(" Agent directory: ./my_agent")Take a Look at Your Agent
Let's see what the ADK CLI created for you. This is a basic agent.
# Display the agent code
with open("my_agent/agent.py") as f:
print(f.read())Deploy your ADK Agent to the Cloud via ADK CLI
This is the exciting part! We're going to deploy your agent to Google Cloud's Agent Engine. This means your agent will be running on Google's infrastructure, ready to handle requests 24/7.
What happens during deployment:
- Your agent code gets packaged up
- It's uploaded to Agent Engine
- Google builds and deploys it on managed infrastructure
- You get back a resource name you can use to access your agent
This takes about 5-10 minutes, so grab a coffee! ☕
Watch for the ✅ success message - it will include your agent's resource name. You'll need that in the next step!
# Deploy the agent using Express Mode with API key
!adk deploy agent_engine my_agentConnect to Your Deployed Agent
Great! Your agent is now live on Agent Engine. Let's connect to it so we can start asking questions.
You need to do one thing: Copy the resource name from the deployment output above (it looks like projects/123.../locations/us-central1/reasoningEngines/456...) and paste it into the agent_resource_name variable below.
import vertexai
# Initialize client with API key (Express Mode)
client = vertexai.Client(api_key=api_key)
# TODO: Replace with your agent's resource name from deployment output
agent_resource_name = "projects/your-project-id/locations/us-central1/reasoningEngines/your-agent-engine-id"
# Get the deployed agent
express_agent = client.agent_engines.get(name=agent_resource_name)
print("✅ Agent retrieved successfully!")
print(f" Resource: {express_agent.api_resource.name}")Ask Your Agent a Question!
Now for the fun part - let's put your agent to work! We're going to ask it about recent AI announcements from Google.
Watch how the response streams in real-time. Your agent will use Google Search to find current information and then synthesize it into a helpful answer.
# Query the agent with streaming responses
print("🔍 Query: 'What are the latest AI announcements from Google in 2025?'")
print("-" * 70)
async for item in express_agent.async_stream_query(
message="What are the latest AI announcements from Google in 2025?",
user_id="demo_user_express",
):
# Print the response content
if "content" in item and item["content"] and "parts" in item["content"]:
for part in item["content"]["parts"]:
if "text" in part:
print(part["text"], end="", flush=True)
print("\n" + "-" * 70)
print("✅ Query completed successfully!")Deployment Methods in Vertex AI Agent Engine
So far, you deploy an ADK agent on Agent Engine using the CLI. The methods below are some alternatives for developers who need production-ready deployments with full Google Cloud integration.
Note: If you're just getting started, we recommend completing Method 1 (Express Mode) first before exploring these alternatives.
Method 1: Deploy from Agent Object
Use agent object deployment for interactive development in notebook environments like Colab. You create your agent in memory and deploy it directly.
This method requires:
- A Google Cloud project with billing enabled
- Vertex AI API enabled
- Appropriate IAM permissions
- A Cloud Storage bucket for staging
Install the Vertex AI SDK
For agent object deployment, we need the full Vertex AI SDK. This gives us the ability to deploy in-memory agent objects to production.
Run the cell below to install it. Colab will prompt you to restart the runtime after installation.
!pip install google-cloud-aiplatform[agent_engines] --upgrade --quietAuthenticate with Google Cloud
If you're running this in Colab, you need to authenticate so the notebook can access your Google Cloud project. Run the cell below and follow the authentication prompts.
# import sys
# if "google.colab" in sys.modules:
# from google.colab import auth
# auth.authenticate_user()
# print("✅ Authentication successful!")Configure Your Google Cloud Project
Now we need to tell the SDK which Google Cloud project to use. You'll need:
- Your Project ID (find it in the Google Cloud Console)
- A Cloud Storage bucket for staging deployment files
If you haven't set up a Google Cloud project yet, check out this guide to get started.
Replace the placeholder values below with your actual project ID and bucket name.
import os
import vertexai
# TODO: Replace with your project ID and staging bucket
PROJECT_ID = "[your-project-id]" # @param {type: "string"}
LOCATION = "us-central1" # @param {type: "string"}
STAGING_BUCKET_NAME = "[your-bucket-name]" # @param {type: "string"}
STAGING_BUCKET = f"gs://{STAGING_BUCKET_NAME}"
# Auto-detect project if running in Colab
if not PROJECT_ID or PROJECT_ID == "[your-project-id]":
PROJECT_ID = str(os.environ.get("GOOGLE_CLOUD_PROJECT"))
# Initialize the client with API key
client = vertexai.Client(project=PROJECT_ID, location=LOCATION)
print("✅ Google Cloud environment configured")
print(f" Project: {PROJECT_ID}")
print(f" Location: {LOCATION}")
print(f" Staging Bucket: {STAGING_BUCKET}")Create Your Agent in Memory
With agent object deployment, you create the agent right here in the notebook. Let's build an agent with Google Search capability, just like we did in Express Mode.
from google.adk.agents import LlmAgent
from google.adk.tools import google_search
# Create the agent in memory
local_agent = LlmAgent(
name="search_agent",
model="gemini-2.5-flash",
description="A production agent that can search the web for current information",
instruction="Use Google Search to find fresh, up-to-date information. Always cite your sources.",
tools=[google_search],
)
print("✅ Agent created in memory!")
print(f" Agent name: {local_agent.name}")Wrap Your Agent in an AdkApp
Here's the key step for ADK deployment: we need to wrap our agent in an AdkApp object. This wrapper:
- Provides the interface that Agent Engine expects
- Enables automatic session management with
VertexAiSessionService - Adds tracing capabilities for debugging
When deployed, the AdkApp automatically uses managed, persistent session state. For local testing, it uses temporary in-memory sessions.
from vertexai import agent_engines
# Wrap the agent in an AdkApp object
adk_app = agent_engines.AdkApp(
agent=local_agent,
enable_tracing=True,
)
print("✅ Agent wrapped in AdkApp!")
print(" This app is ready for deployment to Agent Engine.")Deploy the AdkApp
Now let's deploy this AdkApp to Agent Engine. The SDK will:
- Package your agent code and the AdkApp wrapper
- Upload it to your Cloud Storage staging bucket
- Build a container with the agent and ADK runtime
- Deploy it to managed infrastructure
This takes 5-10 minutes.
# Deploy the AdkApp to Agent Engine
try:
remote_app = client.agent_engines.create(
agent=adk_app,
config=dict(
display_name="Search Agent",
description="A production agent that can search the web for current information",
labels={"agent_type": "search"},
requirements=["google-cloud-aiplatform[adk,agent_engines]"],
staging_bucket=STAGING_BUCKET,
),
)
print("✅ AdkApp deployed successfully!")
print(f"\nResource name: {remote_app.api_resource.name}")
print("\nYour agent now has:")
print(" • Managed session state (VertexAiSessionService)")
print(" • Automatic scaling")
print(" • Built-in tracing")
except Exception as e:
print(f"❌ Deployment failed: {e!s}")
print("\nPlease check:")
print(" 1. Your project ID and location are correct")
print(" 2. The Vertex AI API is enabled")
print(" 3. You have necessary IAM permissions")
print(" 4. Your staging bucket exists and is accessible")
raiseTest the Deployed AdkApp
Let's query the agent using the session we just created. Notice how we pass the session_id - this enables the agent to maintain context across multiple turns.
Create a Session
Before querying the deployed agent, we need to create a session. Sessions maintain conversation history and state across multiple queries.
# Create a session for this user
remote_session = await remote_app.async_create_session(user_id="demo_user_adk")
print("✅ Session created!")
print(f" Session ID: {remote_session['id']}")
print(f" User ID: {remote_session['userId']}")
print(f" App Name: {remote_session['appName']}")Test the Deployed AdkApp
Let's query the agent using the session we just created. Notice how we pass the session_id - this enables the agent to maintain context across multiple turns.
# Query the agent with streaming responses
print("🔍 Query: 'What are the top tech trends in 2025?'")
print("=" * 70)
async for event in remote_app.async_stream_query(
user_id="demo_user_adk",
session_id=remote_session["id"],
message="What are the top tech trends in 2025?",
):
# Print the response content
if event.get("content", {}).get("parts"):
for part in event["content"]["parts"]:
if "text" in part:
print(part["text"], end="", flush=True)
print("✅ Query completed successfully!")Method 2: Inline Source Deployment
Use Inline Source deployment when you need:
- CI/CD pipelines - Automated, file-based deployments
- Version control - Deploy from local source files
- Reproducible builds - No serialization, just source code
- Infrastructure as Code - Works with Terraform and other IaC tools
This method is perfect for automated workflows and production pipelines. You deploy directly from source code files without needing to create an agent object in memory or a Cloud Storage bucket.
This method requires:
- A Google Cloud project with billing enabled
- Vertex AI API enabled
- Appropriate IAM permissions
Note: Unlike ADK App deployment, inline source does not require a Cloud Storage bucket!
Install the Vertex AI SDK
For agent object deployment, we need the full Vertex AI SDK. This gives us the ability to deploy in-memory agent objects to production.
Run the cell below to install it. Colab will prompt you to restart the runtime after installation.
%pip3 install "google-cloud-aiplatform[agent_engines] @ git+https://github.com/googleapis/python-aiplatform.git@copybara_817827304" --upgrade --quietDownload a Sample Agent
For this example, we'll download a pre-built agent from GitHub.
# Download the agent code from GitHub
!rm -rf agent_package
!git clone https://github.com/shawn-yang-google/adk-samples.git --quiet
!cp -a adk-samples/python/agents/academic-research/. ./
!rm -rf adk-samples
print("✅ Agent code downloaded successfully")
print("\nAgent package structure:")
!ls -la agent_package/Check Out the Agent Code
Let's take a quick look at the agent we just downloaded. It's structured similarly to the one we created in Method 1.
# Display the agent code
with open("academic_research/agent.py") as f:
print(f.read())Set Up the Deployment Configuration
With Inline Source deployment, we have more control over how the agent is deployed. We need to specify:
- source_packages: Which local directories contain our agent code
- entrypoint_module: The Python module with our agent (in this case,
agent_package.agent) - entrypoint_object: The name of our agent variable (can be
root_agentorAdkApp) - class_methods: Which methods should be available on the deployed agent
This might look like a lot, but it gives us flexibility for production deployments!
import vertexai
# Initialize Vertex AI client with Google Cloud project
client = vertexai.Client(
project=PROJECT_ID,
location=LOCATION,
)
# Define the async methods available on the deployed agent
class_methods = [
{
"parameters": {},
"api_mode": "async_stream",
"description": "Stream responses from the agent",
"name": "async_stream_query",
},
{
"parameters": {},
"api_mode": "async",
"description": "Create a new session",
"name": "async_create_session",
},
]
print("✅ Deployment configuration prepared")
print(f" Available methods: {[m['name'] for m in class_methods]}")Deploy Your Agent with Inline Source
Here's where it all comes together! This deployment is a bit more complex than Express Mode:
- Your code gets packaged into a tarfile (in memory)
- It's uploaded to your Cloud Storage staging bucket
- Agent Engine builds a container image with your code
- The container is deployed to managed infrastructure
This takes 5-10 minutes. The cell below includes error handling to help you troubleshoot if something goes wrong.
try:
inline_agent = client.agent_engines.create(
config={
"display_name": "Academic Research Agent",
"description": "An agent to answer questions about academic research",
"labels": {"agent_type": "academic_research"},
"source_packages": ["academic_research", "deployment", "requirements.txt"],
"entrypoint_module": "deployment.deploy",
"entrypoint_object": "adk_app",
"class_methods": class_methods,
},
)
print("\n" + "=" * 70)
print("✅ Agent deployed successfully with inline source!")
print("=" * 70)
print(f"\nResource name: {inline_agent.api_resource.name}")
print("\nYou can now query this agent using the Python SDK.")
except Exception as e:
print(f"❌ Deployment failed: {e!s}")
print("\nPlease check:")
print(" 1. Your project ID and location are correct")
print(" 2. The Vertex AI API is enabled")
print(" 3. You have necessary IAM permissions")
print(" 4. Your staging bucket exists and is accessible")
raiseTest Your Agent
Let's make sure everything works! We'll ask the agent about quantum computing - a topic that requires current information from the web.
# Query the agent with streaming responses
print("🔍 Query: 'What are the latest developments in quantum computing?'")
print("=" * 70)
async for item in inline_agent.async_stream_query(
message="What are the latest developments in quantum computing?",
user_id="demo_user_inline",
):
# Print the response content
if "content" in item and item["content"] and "parts" in item["content"]:
for part in item["content"]["parts"]:
if "text" in part:
print(part["text"], end="", flush=True)
print("\n" + "=" * 70)
print("✅ Query completed successfully!")Cleaning up
When you're done experimenting, it's a good idea to delete your deployed agents to avoid unexpected charges. This is especially important for the Inline Source deployment (Method 2), which uses billable Google Cloud resources.
For Express Mode users: Remember, you have 90 days of free usage, but it's still good practice to clean up when you're done.
Delete your Express Mode deployed agent
# # Uncomment to delete the Express Mode deployed agent
# try:
# express_agent.delete(force=True)
# print(f"✅ Agent {express_agent.api_resource.name} has been deleted.")
# except Exception as e:
# print(f"⚠️ Could not delete agent: {str(e)}")Delete Your Inline Source Agent
If you deployed an agent using Method 2, uncomment and run the cell below to delete it.
# # Uncomment to delete the Inline Source deployed agent
# try:
# inline_agent.delete(force=True)
# print(f"✅ Agent {inline_agent.api_resource.name} has been deleted.")
# except Exception as e:
# print(f"⚠️ Could not delete agent: {str(e)}")Next Steps
Congratulations! You now know how to deploy ADK agents to Agent Engine:
- Started with Express Mode - The free, easy way to deploy agents with just an API key
- Explored alternatives - Learned about Inline Source deployment
- Created an ADK agent with Google Search capability
- Deployed and tested your agent with streaming queries
- Learned how to clean up resources
As next steps, you can try to:
- Add custom tools to your agents
- Build multi-agent systems
- Create conversational workflows
- Test different prompting strategies
And when you are ready you can upgrade from Express Mode to get full Google Cloud access:
- Go to console.cloud.google.com/billing
- Click "Access all Google Cloud" to upgrade
- Transition to Inline Source deployment
- Configure IAM, monitoring, and production features
Below some resources: