Generative AI Google Brain

agents-agent-engine-tutorial-get-started-with-agent-engine-terraform-deployment

3 min read

Get started with Agent Engine Terraform Deployment

Source notebook

Repo path: agents/agent_engine/tutorial_get_started_with_agent_engine_terraform_deployment.ipynb · Open on GitHub · intermediate

Deploy Vertex AI Agent Engine agents with Terraform, cloudpickle packaging, and ADK tools.

Summary

This notebook teaches how to deploy AI agents on Vertex AI Agent Engine using Terraform infrastructure as code. It builds and packages a custom Python agent with cloudpickle, uploads artifacts to Cloud Storage through Terraform, deploys a google_vertex_ai_reasoning_engine resource, and queries it with the Vertex AI SDK. It then repeats the workflow for an ADK LlmAgent that uses a function tool to fetch exchange rates.

Key code patterns

Custom Agent Template

class SimpleAgent:
    def __init__(self, model, project, location):
        self.model_name = model
        self.project = project
        self.location = location
 
    def set_up(self):
        vertexai.init(project=self.project, location=self.location)
        self.model = GenerativeModel(self.model_name)
 
    def query(self, input: str) -> Dict:
        response = self.model.generate_content(f"Respond to: {input}")
        return {"output": response.text}

Agent Engine custom agents are Python classes with pickle-able init state, setup logic, and query operations.

Serialize Agent

agent = SimpleAgent(
    model="gemini-2.5-flash",
    project=PROJECT_ID,
    location=LOCATION,
)
agent.set_up()
with open("./agent.pkl", "wb") as f:
    cloudpickle.dump(agent, f)

Terraform deployment references a pickled agent object stored as an artifact.

Terraform Reasoning Engine

resource "google_vertex_ai_reasoning_engine" "reasoning_engine" {
  display_name = "simple_agent"
  region       = var.region
 
  spec {
    class_methods = jsonencode(local.class_methods)
    package_spec {
      pickle_object_gcs_uri = "${google_storage_bucket.bucket.url}/agent.pkl"
      python_version = "3.12"
      requirements_gcs_uri = "${google_storage_bucket.bucket.url}/requirements.txt"
    }
  }
}

The Reasoning Engine resource declares supported operations and points to Cloud Storage package artifacts.

ADK Tool Agent

def get_exchange_rate(currency_from="USD", currency_to="EUR", currency_date="latest"):
    response = requests.get(
        f"https://api.frankfurter.app/{currency_date}",
        params={"from": currency_from, "to": currency_to},
    )
    return response.json()
 
root_agent = LlmAgent(
    model="gemini-2.5-flash",
    tools=[get_exchange_rate],
)

ADK agents can be deployed with function tools and exposed through async Agent Engine operations.

Query Deployed Agent

client = vertexai.Client(project=PROJECT_ID, location=LOCATION)
agent = client.agent_engines.get(name=agent_engine_resource_name)
response = agent.query(input="What is artificial intelligence?")
 
async for event in agent.async_stream_query(
    user_id="user_123",
    message="What is the exchange rate from US dollars to SEK today?",
):
    print(event)

The deployed custom agent uses query, while the ADK agent uses async streaming query operations.

Models & APIs used

  • Models: gemini-2.5-flash
  • APIs / services: Vertex AI, Vertex AI Agent Engine, Vertex AI API, Cloud Storage
  • SDKs / libraries: google-cloud-aiplatform, vertexai, google-adk, cloudpickle

When to use this

Use this pattern when you need repeatable Terraform-based deployment of custom or ADK agents to Vertex AI Agent Engine.

Gotchas & caveats

  • Requires a Google Cloud project with billing enabled.
  • Vertex AI API must be enabled before deployment.
  • Requires sufficient IAM permissions such as Vertex AI Administrator or Editor.
  • Agent artifacts must be stored in a Cloud Storage bucket.
  • Agent objects must be pickle-able before cloudpickle serialization.
  • Terraform apply prompts for confirmation unless -auto-approve is used.
  • The notebook pins Terraform provider version 7.6.0 and installs Terraform 1.13.3 for Linux.
  • Agent Engine package spec uses python_version 3.12.
  • Deployment typically takes around 5 minutes.

Best practices

  • Use Terraform configuration files for version-controlled, repeatable Agent Engine deployments.
  • Define class_methods for the operations the deployed agent supports.
  • Package requirements.txt, agent.pkl, and dependencies.tar.gz as deployment artifacts.
  • Use set_up() for initialization logic and keep init() configuration pickle-able.
  • Use terraform output to retrieve deployed Reasoning Engine resource information.
  • Clean up deployments with terraform destroy to avoid unnecessary charges.

Graph View

Backlinks