Vertex AI Agent Engine Deployment

Relevant source files

• pyproject.toml
• src/google/adk/cli/adk_web_server.py
• src/google/adk/cli/cli_deploy.py
• src/google/adk/cli/cli_eval.py
• src/google/adk/cli/cli_tools_click.py
• src/google/adk/cli/fast_api.py
• src/google/adk/cli/utils/logs.py
• tests/unittests/agents/test_resumable_llm_agent.py
• tests/unittests/cli/test_cli_tools_click_option_mismatch.py
• tests/unittests/cli/test_fast_api.py
• tests/unittests/cli/utils/test_cli_deploy.py
• tests/unittests/cli/utils/test_cli_deploy_to_cloud_run.py
• tests/unittests/cli/utils/test_cli_eval.py
• tests/unittests/cli/utils/test_cli_tools_click.py

Purpose and Scope

This document describes how to deploy ADK agents to Vertex AI Agent Engine, Google Cloud's serverless managed service for hosting agents. Agent Engine deployment packages agents as Python modules with an auto-generated wrapper, enabling production deployment without managing infrastructure.

For other deployment options, see:

• Cloud Run deployment: 10.2
• GKE deployment: 10.4
• General deployment overview: 10.1

Overview

Vertex AI Agent Engine deployment differs fundamentally from container-based deployments (Cloud Run, GKE). Instead of creating Docker images, it:

1. Packages agent code as a Python module
2. Generates an adk_app.py wrapper file containing an AdkApp instance
3. Uploads the package to a staging bucket
4. Creates or updates a managed Agent Engine instance
5. Exposes the agent via Vertex AI's API endpoints

The Agent Engine service handles all runtime infrastructure, auto-scaling, and API serving.

Sources: src/google/adk/cli/cli_deploy.py635-710

Deployment Architecture

Sources: src/google/adk/cli/cli_deploy.py635-710 src/google/adk/cli/cli_tools_click.py1347-1452

CLI Command

The adk deploy agent_engine command orchestrates the deployment:

Command Options

Option	Type	Required	Description
--project	string	No	Google Cloud project ID (default: gcloud config)
--region	string	No	Google Cloud region (default: gcloud config)
--staging_bucket	string	Yes	GCS bucket for staging artifacts (e.g., gs://bucket)
--agent_engine_id	string	No	ID of existing Agent Engine to update (creates new if omitted)
--adk_app	string	No	Name of wrapper file (default: adk_app)
--adk_app_object	string	No	Agent object name (default: root_agent)
--api_key	string	No	API key for Express Mode (uses GOOGLE_API_KEY env var if not set)
--trace_to_cloud	flag	No	Enable Cloud Trace telemetry
--display_name	string	No	Display name for Agent Engine instance
--description	string	No	Description for Agent Engine instance
--requirements_file	string	No	Path to custom requirements.txt
--env_file	string	No	Path to custom .env file
--agent_engine_config_file	string	No	Path to custom .agent_engine_config.json
--absolutize_imports	flag	No	Convert relative to absolute imports (default: True)

Sources: src/google/adk/cli/cli_tools_click.py1347-1452

Package Structure

Agent Engine expects a specific package structure. The deployment process transforms your agent folder into this structure:

<temp_folder>/
├── adk_app.py              # Generated wrapper (from _AGENT_ENGINE_APP_TEMPLATE)
├── agent.py                # Your agent code
├── __init__.py             # Your module init
├── requirements.txt        # Dependencies (if present)
├── .env                    # Environment vars (if present)
└── ... (other agent files)

File Inclusion and .ae_ignore

The .ae_ignore file (similar to .gitignore) specifies patterns of files to exclude from deployment:

# Example .ae_ignore
*.pyc
__pycache__/
.pytest_cache/
tests/
docs/

Implementation: The deployment uses shutil.copytree() with shutil.ignore_patterns() to filter files according to .ae_ignore patterns.

Sources: src/google/adk/cli/cli_deploy.py733-742

AdkApp Wrapper Generation

The deployment auto-generates an adk_app.py file that wraps your agent. This wrapper is the entry point for Agent Engine.

Generated Wrapper Template

The wrapper is generated from _AGENT_ENGINE_APP_TEMPLATE:

Template Parameters

• {is_config_agent}: Boolean - whether agent uses YAML config
• {agent_folder}: Path to agent source
• {temp_folder}: Staging directory name
• {app_name}: Agent folder name
• {adk_app_object}: Agent object name (default: root_agent)
• {express_mode}: Boolean - use API key vs project/location
• {adk_app_type}: Either agent or app
• {trace_to_cloud_option}: Boolean - enable tracing

Sources: src/google/adk/cli/cli_deploy.py69-97

Agent Engine API Methods

Agent Engine exposes a predefined set of methods through the AdkApp wrapper. These methods are registered in _AGENT_ENGINE_CLASS_METHODS:

Core Query Methods

Method	Mode	Description
stream_query	stream	Deprecated. Synchronous streaming query
async_stream_query	async_stream	Async streaming query (recommended)
streaming_agent_run_with_events	async_stream	For AgentSpace integration

Session Management Methods

Method	Mode	Description
get_session	sync	Deprecated. Get session synchronously
async_get_session	async	Get session for user/session ID
list_sessions	sync	Deprecated. List sessions synchronously
async_list_sessions	async	List all sessions for a user
create_session	sync	Deprecated. Create session synchronously
async_create_session	async	Create new session
delete_session	sync	Deprecated. Delete session synchronously
async_delete_session	async	Delete session

Memory Methods

Method	Mode	Description
async_add_session_to_memory	async	Generate memories from session
async_search_memory	async	Search memories for user

Method Schema Example:

Sources: src/google/adk/cli/cli_deploy.py99-376

Deployment Process Flow

Sources: src/google/adk/cli/cli_deploy.py710-1102

Configuration Files

.agent_engine_config.json

This file contains deployment configuration that overrides CLI options:

The config is merged with CLI options, with CLI options taking precedence.

Implementation: src/google/adk/cli/cli_deploy.py750-771

requirements.txt

Standard Python dependencies file. Agent Engine installs these packages at deployment time:

Implementation: src/google/adk/cli/cli_deploy.py773-790

.env File

Environment variables loaded into the Agent Engine runtime:

Special handling:

• GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION are overridden by CLI --project and --region if specified
• GOOGLE_API_KEY enables Express Mode if GOOGLE_GENAI_USE_VERTEXAI=1

Implementation: src/google/adk/cli/cli_deploy.py792-832

Express Mode vs Vertex AI Mode

Agent Engine supports two authentication modes:

Express Mode (API Key Based)

• When: GOOGLE_API_KEY is set in environment or via --api_key
• Requires: GOOGLE_GENAI_USE_VERTEXAI=1 environment variable
• Init: vertexai.init(api_key=os.environ.get("GOOGLE_API_KEY"))
• Use case: Simpler authentication for development/testing

Vertex AI Mode (Project/Location Based)

• When: GOOGLE_API_KEY is not set
• Requires: GOOGLE_CLOUD_PROJECT and GOOGLE_CLOUD_LOCATION
• Init: vertexai.init(project=..., location=...)
• Use case: Production deployments with full GCP integration

Determination logic:

Sources: src/google/adk/cli/cli_deploy.py834-854

Import Absolutization

By default (--absolutize_imports=True), the deployment converts relative imports to absolute imports. This prevents import resolution issues in Agent Engine's runtime environment.

Example Transformation

Before:

After:

The absolutization process:

1. Uses importlab.fs.OSFileSystem to resolve imports
2. Identifies relative imports in Python files
3. Replaces them with absolute imports using the package name
4. Updates all .py files in the staged directory

Implementation: src/google/adk/cli/cli_deploy.py856-924

Sources: src/google/adk/cli/cli_deploy.py856-924

Deployment Process Implementation

Key Functions

Core Deployment Function Signature

Location: src/google/adk/cli/cli_deploy.py635-653

Sources: src/google/adk/cli/cli_deploy.py635-1102

Create vs Update

The deployment supports both creating new Agent Engine instances and updating existing ones:

Create New Instance

When --agent_engine_id is not provided:

The SDK:

1. Packages the agent folder
2. Uploads to staging bucket
3. Creates a new Agent Engine resource
4. Returns the resource name (e.g., projects/.../locations/.../reasoningEngines/123)

Update Existing Instance

When --agent_engine_id is provided:

The SDK:

1. Retrieves the existing Agent Engine
2. Uploads new package version
3. Updates the Agent Engine configuration
4. Performs rolling update (no downtime)

Implementation: src/google/adk/cli/cli_deploy.py926-1102

Sources: src/google/adk/cli/cli_deploy.py926-1102

Integration with ADK Services

Agent Engine deployments automatically integrate with ADK's service layer:

Session Service Integration

Agent Engine provides built-in session management through the Vertex AI backend. The AdkApp wrapper exposes session methods that delegate to Vertex AI's session service:

• async_get_session() → Vertex AI Session API
• async_create_session() → Vertex AI Session API
• async_list_sessions() → Vertex AI Session API

To use custom session services in Agent Engine, agents must be configured with session service URIs in their initialization code.

Memory Service Integration

Similarly, memory operations use Agent Engine's managed memory service:

• async_add_session_to_memory() → Vertex AI RAG/Memory API
• async_search_memory() → Vertex AI RAG/Memory API

Sources: src/google/adk/cli/cli_deploy.py99-376

Deployment Validation

Pre-deployment Checks

The to_agent_engine() function validates several conditions before deploying:

1. Working Directory Check: Must be in the parent directory of the agent folder

2. ADK App Object Validation: Must be root_agent or app

3. Project Resolution: Resolves GCP project from CLI option or gcloud config

Sources: src/google/adk/cli/cli_deploy.py710-745

Cleanup and Error Handling

The deployment process uses a try...finally block to ensure temporary files are cleaned up:

This ensures the temporary staging directory is removed even if deployment fails.

Sources: src/google/adk/cli/cli_deploy.py732-1102

Example Deployment Workflow

Minimal Deployment

Full-Featured Deployment

Update Existing Agent Engine

Sources: src/google/adk/cli/cli_tools_click.py1347-1452

Limitations and Considerations

File Size Limits

Agent Engine has package size limits enforced by Vertex AI. Large agent folders should:

• Use .ae_ignore to exclude unnecessary files (tests, docs, large data files)
• Consider externalizing large assets to Cloud Storage

Import Resolution

• Python imports must be resolvable within the package
• External packages must be in requirements.txt
• Use --absolutize_imports=True to avoid relative import issues

Runtime Environment

• Agent Engine runs in a managed Python environment
• Some system-level operations may be restricted
• File I/O is limited to specific directories
• Network access follows Vertex AI's security policies

Deployment Time

• Initial deployment can take 5-15 minutes
• Updates are typically faster (2-5 minutes)
• Deployment includes package upload, environment setup, and health checks

Sources: src/google/adk/cli/cli_deploy.py635-710