DEV Community

Hiroshi Toyama
Hiroshi Toyama

Posted on • Originally published at github.com

Easy Deployment of Vertex AI Agent Engine with vaiae

#gcp #vertexai #python #devops

Introducing vaiae

https://github.com/toyama0919/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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

Important points:

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

Agent Implementation Example

Here's how to create an AI Agent using google-adk that can be referenced by instance_path:

# my_package/agents.py
from google.adk.agents import Agent

# Define tools as regular functions
def get_weather(location: str) -> str:
    """Get weather information for a location.

    Args:
        location: City name

    Returns:
        Weather information
    """
    return f"The weather in {location} is sunny, 22°C"

def calculate_sum(a: int, b: int) -> int:
    """Calculate the sum of two numbers.

    Args:
        a: First number
        b: Second number

    Returns:
        Sum of a and b
    """
    return a + b

# Create the root agent
main_agent = Agent(
    name="my_agent",
    model="gemini-2.0-flash-exp",
    description="A helpful assistant that can check weather and perform calculations.",
    instruction="""
    You are a helpful assistant with the following capabilities:
    - Check weather information using get_weather tool
    - Perform calculations using calculate_sum tool

    Always be polite and provide clear responses.
    """,
    tools=[get_weather, calculate_sum],
)
Enter fullscreen mode Exit fullscreen mode

This agent can be referenced in your .agent-engine.yml using:

agent_engine:
  instance_path: "my_package.agents.main_agent"
Enter fullscreen mode Exit fullscreen mode

The instance_path points to the main_agent variable defined in the my_package.agents module. vaiae will dynamically import this agent instance when deploying.

For more complex agent examples, refer to the Vertex AI documentation and google-adk PyPI package.

Deployment

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

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

# Actually deploy
vaiae deploy
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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"
)
Enter fullscreen mode Exit fullscreen mode

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"]
)
Enter fullscreen mode Exit fullscreen mode

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
)
Enter fullscreen mode Exit fullscreen mode

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()
Enter fullscreen mode Exit fullscreen mode

Troubleshooting

Authentication Error 

Error: Could not automatically determine credentials
Enter fullscreen mode Exit fullscreen mode

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

gcloud auth application-default login
Enter fullscreen mode Exit fullscreen mode

Or use a service account key:

export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account-key.json
Enter fullscreen mode Exit fullscreen mode

Permission Error 

Error: Permission denied
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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:

  1. Separate management of development and production environments
  2. Integration with CI/CD pipelines
  3. Sharing AI Agent configurations within teams
  4. Version control and rollback

In particular, combining the profile feature with dry run enables safe and efficient deployment.

vaiae has more features planned for the future. I recommend checking the GitHub repository for the latest information.

Reference Links

Top comments (0)