Easy Deployment of Vertex AI Agent Engine with vaiae

Introducing vaiae

vaiae is a tool that makes it easy to deploy and manage Google Cloud Vertex AI Agent Engine from the command line. Define your configuration in a YAML file and deploy with a single command.

Key features:

Declarative deployment with YAML configuration files
Profile management for multiple environments (dev/prod, etc.)
Interactive messaging with AI Agents
Safe validation with dry run mode
Available as both a Python library and CLI

Why I Built This

Deploying and managing Vertex AI Agent Engine traditionally involved tedious manual work. There were several challenges:

Too Much Manual Work

Need to configure AI Agents through the GCP console every time
Complex dependency and package version management
Manual configuration of environment variables and secrets

Difficult Environment Management

Tedious to separate development and production environment settings
Need to manually switch between different configurations for each environment
No way to track configuration history or version control

Team Development Challenges

Need to document and share configuration details
Configuration drift between team members
Deployment procedures become person-dependent

vaiae solves these challenges with YAML-based configuration management and a simple CLI. Since configurations are managed as code, they can be version-controlled with Git and shared with the team. The profile feature also makes managing multiple environments easy.

This article covers everything from basic usage to practical applications of vaiae.

Installation

Easy installation with pip:

pip install vaiae

Python 3.10 or higher is required.

GCP Authentication Setup

Before using vaiae, you need to configure Google Cloud authentication:

# Using Application Default Credentials
gcloud auth application-default login

# Using service account key
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

Also, make sure the Vertex AI API is enabled.

Basic Usage

Creating a Configuration File

Create .agent-engine.yml in your project root. This is the Agent Engine definition file.

default:
  # Vertex AI configuration
  vertex_ai:
    project: "my-gcp-project"
    location: "asia-northeast1"
    staging_bucket: "my-staging-bucket"

  display_name: "my-agent-engine"
  description: "Basic Agent Engine"
  gcs_dir_name: "my-agent/1.0.0"

  # AI Agent configuration
  agent_engine:
    instance_path: "my_package.agents.main_agent"

  # Environment variables
  env_vars:
    API_KEY: "your-api-key"
    SLACK_WEBHOOK_URL:
      secret: "slack-webhook-url"
      version: "latest"

  # Dependencies
  requirements:
    - "google-cloud-aiplatform[adk,agent_engines]==1.96.0"
    - "google-adk"
    - "requests"

Important points:

display_name serves as a unique identifier for the Agent Engine
Redeploying with the same display_name will update instead of creating a new one
instance_path dynamically imports an existing AI Agent instance

Deployment

Once you’ve created the configuration file, deployment is simple:

# Preview with dry run
vaiae deploy --dry-run

# Actually deploy
vaiae deploy

Using dry run lets you verify the configuration before actually deploying. This is especially important in production environments.

Checking Deployed AI Agents

You can list deployed Agent Engines:

vaiae list

Results are displayed in an easy-to-read table format:

Found 2 agent engine(s):

Display Name         Resource Name                                        Create Time                  Update Time
-------------------  ---------------------------------------------------  ---------------------------  ---------------------------
my-agent-dev         projects/.../agentEngines/123...                     2024-11-20 10:30:00          2024-11-25 14:20:00
my-agent-prod        projects/.../agentEngines/456...                     2024-11-15 09:00:00          2024-11-26 16:45:00

Sending Messages to AI Agents

You can interact with your deployed AI Agents:

# Basic message sending
vaiae send -m "Please analyze the data"

# Continue conversation with session ID
vaiae send -m "What's the next step?" -s "session-123"

# Specify user ID
vaiae send -m "Create a report" -u "user-456"

Using session IDs allows you to continue conversations while maintaining context from previous interactions.

Deleting AI Agents

You can delete Agent Engines when they’re no longer needed:

# Verify with dry run
vaiae delete --dry-run

# Actually delete
vaiae delete

# Delete by name
vaiae delete -n "my-agent-engine"

# Force delete (including child resources)
vaiae delete -n "my-agent-engine" --force

Practical Usage

Managing Multiple Environments

Using different configurations for development and production is essential in real development. vaiae accomplishes this with profile functionality.

# Default configuration (common settings)
default:
  vertex_ai:
    location: "asia-northeast1"
    staging_bucket: "common-staging-bucket"

  agent_engine:
    instance_path: "my_package.agents.main_agent"

  requirements:
    - "google-cloud-aiplatform[adk,agent_engines]==1.96.0"
    - "google-adk"

# Development environment
development:
  vertex_ai:
    project: "dev-project"
  display_name: "my-agent-dev"
  description: "Development environment AI Agent"
  env_vars:
    DEBUG_MODE: "true"
    API_ENDPOINT: "https://api-dev.example.com"

# Production environment
production:
  vertex_ai:
    project: "prod-project"
  display_name: "my-agent-prod"
  description: "Production environment AI Agent"
  env_vars:
    DEBUG_MODE: "false"
    API_ENDPOINT: "https://api.example.com"

Deploy with specific profiles:

# Deploy to development environment
vaiae --profile development deploy

# Deploy to production environment
vaiae --profile production deploy

# Delete development AI Agent
vaiae --profile development delete

Using profiles makes it easy to switch between different project IDs, display_names, and environment variables per environment. It’s efficient to write common settings in default and only override differences in each environment.

Debug Mode

When issues occur, you can check detailed logs with debug mode:

vaiae --debug deploy

Detailed logging makes it easier to identify problems.

Using Custom Configuration Files

To use a configuration file other than the default .agent-engine.yml:

vaiae --yaml-file custom-config.yml deploy

This is useful when you want different configuration files per project.

Using as a Python API

You can use vaiae not just as a CLI, but also from Python code. This is useful for integrating with CI/CD pipelines or for more complex automation.

Basic Usage

from vaiae.core import Core

# Initialize Core instance
core = Core(
    yaml_file_path=".agent-engine.yml",
    profile="default"
)

# Deploy
core.create_or_update_from_yaml(dry_run=False)

# Send message
response = core.send_message(
    message="Please run the analysis",
    user_id="user123"
)

Overriding Configuration

You can partially override YAML configuration. This is useful when you want to dynamically change settings.

from vaiae.core import Core

core = Core(yaml_file_path=".agent-engine.yml", profile="development")

# Partially override YAML configuration
core.create_or_update_from_yaml(
    dry_run=False,
    description="Dynamically generated description",
    env_vars={
        "CUSTOM_VAR": "custom_value",
        "API_ENDPOINT": "https://api.example.com"
    },
    requirements=["additional-package==1.0.0"]
)

Managing Agent Engines

from vaiae.core import Core

core = Core(yaml_file_path=".agent-engine.yml", profile="default")

# List agent engines
agent_engines = core.list_agent_engine()
for engine in agent_engines:
    print(f"Name: {engine.display_name}")
    print(f"Resource: {engine.resource_name}")

# Delete
core.delete_agent_engine_from_yaml(
    force=False,
    dry_run=False
)

Integrating with CI/CD Pipelines

Example of integrating with CI/CD pipelines like GitHub Actions or Cloud Build:

import os
from vaiae.core import Core

def deploy_agent():
    """Deploy by reading configuration from environment variables"""
    env = os.environ.get("DEPLOY_ENV", "development")

    core = Core(
        yaml_file_path=".agent-engine.yml",
        profile=env,
        debug=True
    )

    # Validate before deployment
    core.create_or_update_from_yaml(dry_run=True)

    # Actually deploy
    core.create_or_update_from_yaml(dry_run=False)
    print(f"Successfully deployed to {env} environment")

if __name__ == "__main__":
    deploy_agent()

Troubleshooting

Authentication Error

Error: Could not automatically determine credentials

This occurs when GCP authentication is not configured. Set up authentication with the following command:

gcloud auth application-default login

Or use a service account key:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json

Permission Error

Error: Permission denied

The service account or user being used needs the following permissions:

aiplatform.agentEngines.create
aiplatform.agentEngines.update
aiplatform.agentEngines.delete
aiplatform.agentEngines.list

Grant the appropriate permissions in the GCP IAM console.

YAML Configuration Error

Error: Invalid YAML configuration

Check the YAML file syntax:

Is indentation correct (consistent with 2 or 4 spaces)?
Are all required fields configured?
Are special characters escaped?

Conclusion

With vaiae, deploying and managing Vertex AI Agent Engine becomes dramatically easier. Managing configurations with YAML files and easily switching between multiple environments is a huge advantage.

Main use cases: