Menyediakan agen dengan Terraform

Anda dapat menggunakan Terraform untuk menyediakan dan mengelola instance Agent Runtime secara deklaratif. Saat men-deploy agen dengan Terraform, Anda mengelola resource google_vertex_ai_reasoning_engine menggunakan penyedia Terraform Google Cloud resmi (penyedia GA atau penyedia Beta).

Petunjuk di halaman ini sesuai dengan contoh penerapan agen dalam penampung yang dijelaskan dalam codelab Deploy agen dalam penampung dengan Agent Runtime.

Prasyarat

Sebelum menggunakan Terraform untuk men-deploy agen, pastikan Anda telah menyelesaikan penyiapan berikut:

1. Instal Terraform (versi 1.5.0 atau yang lebih baru) dan tinjau dokumentasi resmi HashiCorp Terraform Registry untuk resource google_vertex_ai_reasoning_engine (penyedia GA dan penyedia Beta).
2. Siapkan Google Cloud lingkungan Anda dan aktifkan Vertex AI API (aiplatform.googleapis.com), Artifact Registry API (artifactregistry.googleapis.com), dan Cloud Build API (cloudbuild.googleapis.com).

3. Autentikasi lingkungan lokal Anda menggunakan kredensial Google Cloud :

   gcloud auth application-default login

4. Untuk memisahkan kode aplikasi dari pengelolaan infrastruktur, atur ruang kerja agen Anda ke dalam direktori aplikasi dan Terraform khusus:

   weather-agent-byoc/
   ├── main.py                # Python ADK agent entrypoint
   ├── requirements.txt       # Python dependencies
   ├── Dockerfile             # Container build definition
   └── terraform/             # Terraform configuration directory
       ├── main.tf            # Agent Runtime resources and specifications
       ├── variables.tf       # Project, region, and container variables
       └── outputs.tf         # Resource name outputs
   

   • File aplikasi (main.py, requirements.txt, Dockerfile): Berisi logika agen, wrapper framework web (seperti Aplikasi ADK atau FastAPI), dependensi Python, dan petunjuk pembuatan penampung.

   • Direktori Terraform (terraform/): Berisi semua file konfigurasi Terraform yang digunakan untuk menyediakan resource:

     • variables.tf: Mendeklarasikan variabel input seperti project_id, location, repository_name, dan image_tag.
     • main.tf: Mendeklarasikan setelan penyedia, variabel lokal, binding peran IAM, dan spesifikasi resource google_vertex_ai_reasoning_engine.
     • outputs.tf: Mengekspor atribut resource yang disediakan, seperti ID Runtime Agen dan nama lengkap resource, setelah deployment.

5. Berikan peran IAM yang sesuai, bergantung pada siapa yang menjalankan deployment:

   • Akun layanan CI/CD atau developer manusia yang menjalankan perintah build lokal dan terraform apply.

     Klik untuk melihat izin yang diperlukan

     • Vertex AI User (roles/aiplatform.user) atau Vertex AI Administrator (roles/aiplatform.admin): Memberi otorisasi kepada deployer untuk menjalankan operasi RPC Agent Runtime Control Plane (CreateReasoningEngine, UpdateReasoningEngine, DeleteReasoningEngine).
     • Service Account User (roles/iam.serviceAccountUser): Diberikan di akun layanan runtime kustom (google_service_account.agent_runtime_sa) yang terlampir ke agen. Memberi otorisasi kepada deployer untuk melampirkan identitas akun layanan tersebut ke resource google_vertex_ai_reasoning_engine yang disediakan.
     • Storage Object Admin (roles/storage.objectAdmin) atau Storage Object Viewer (roles/storage.objectViewer): Diperlukan saat menggunakan penyiapan paket Python (package_spec) untuk mengupload atau membaca pickle agen berseri (agent.pkl) dan manifes dependensi di Cloud Storage.
     • Penulis Artifact Registry (roles/artifactregistry.writer): Diperlukan saat membangun dan mengirimkan image container kustom (docker push) ke repositori Artifact Registry.

   • Agen Layanan Agent Runtime yang dikelola sistem (service-<var>PROJECT_NUMBER</var>@gcp-sa-aiplatform-re.iam.gserviceaccount.com).

     Klik untuk melihat izin yang diperlukan

     • Artifact Registry Reader (roles/artifactregistry.reader): Memberi infrastruktur platform Agent Runtime di latar belakang izin untuk melakukan autentikasi dengan Artifact Registry dan menarik image container kustom Anda selama deployment pod dan cold start container.

     Penting: Di Terraform, Anda harus mengelola binding IAM untuk agen layanan secara eksplisit dan memastikan resource google_vertex_ai_reasoning_engine menyertakan referensi depends_on ke binding IAM. Jika tidak, penyediaan pod dapat gagal dengan IMAGE_PULL_BACKOFF karena kondisi race.

Mempersiapkan deployment

Terraform mendukung jalur deployment berikut untuk Agent Runtime:

• Deploy dari image container bawaan: Bangun dan kirim image container ke Artifact Registry ({region}-docker.pkg.dev/...), lalu deploy menggunakan container_spec. Gunakan metode ini jika Anda memerlukan kontrol penuh atas proses build container, image dasar kustom, atau latensi deployment yang lebih rendah.
• Deploy dari file sumber atau Dockerfile: Deploy agen Anda langsung dari file sumber lokal atau Dockerfile. Agent Runtime membangun dan menyediakan image container secara otomatis tanpa memerlukan pengelolaan image manual.
• Men-deploy menggunakan spesifikasi paket Python Men-deploy menggunakan (package_spec) yang di-stage di Cloud Storage. Agent Runtime membangun dan menyediakan image container secara otomatis tanpa memerlukan pengelolaan image manual.

Men-deploy dari image container bawaan

Jika Anda membuat dan mengirim image container ke Artifact Registry sebelumnya (misalnya, untuk menyertakan library sistem kustom, mengoptimalkan performa cold start, atau menerapkan kontrol pembuatan image organisasi), Anda dapat men-deploy menggunakan container_spec. Untuk mengetahui detail persyaratan gambar, lihat Men-deploy dari Image Container.

Image container harus disimpan di Artifact Registry ({LOCATION}-docker.pkg.dev/{PROJECT_ID}/{REPOSITORY}/{IMAGE}:{TAG}), memproses di port 8080 (atau port kustom yang ditentukan dalam container_spec), dan sesuai dengan kontrak runtime.

1. Bangun image container Anda secara lokal dan kirimkan ke repositori Artifact Registry Anda:

   # 1. Authenticate Docker with your Artifact Registry region
   gcloud auth configure-docker us-central1-docker.pkg.dev
   # 2. Build the container image from your application root directory
   cd weather-agent-byoc
   docker build -t us-central1-docker.pkg.dev/PROJECT_ID/agents-repo/weather-agent-image:latest .
   # 3. Push the container image to Artifact Registry
   docker push us-central1-docker.pkg.dev/PROJECT_ID/agents-repo/weather-agent-image:latest

2. Konfigurasi image container bawaan untuk deployment Terraform. Konfigurasi berikut menunjukkan cara men-deploy image container bawaan yang dihosting di Artifact Registry dengan membuat file variables.tf, main.tf, dan outputs.tf di direktori terraform/ Anda:

   Variabel input (terraform/variables.tf)

   variable "project_id" {
     type        = string
     description = "The Google Cloud Project ID"
   }
   
   variable "project_number" {
     type        = string
     description = "The Google Cloud Project Number"
   }
   
   variable "location" {
     type        = string
     default     = "us-central1"
     description = "The region to deploy Agent Runtime"
   }
   
   variable "repository_name" {
     type        = string
     default     = "agents-repo"
     description = "The Artifact Registry repository name"
   }
   
   variable "image_tag" {
     type        = string
     default     = "latest"
     description = "The tag of the container image to deploy"
   }
   

   Spesifikasi resource (terraform/main.tf)

   terraform {
     required_providers {
       google = {
         source  = "hashicorp/google"
         version = ">= 5.28.0"
       }
     }
   }
   
   provider "google" {
     project = var.project_id
     region  = var.location
   }
   
   locals {
     class_methods = [
       { "name" = "get_session", "api_mode" = "" },
       { "name" = "list_sessions", "api_mode" = "" },
       { "name" = "create_session", "api_mode" = "" },
       { "name" = "delete_session", "api_mode" = "" },
       { "name" = "async_get_session", "api_mode" = "async" },
       { "name" = "async_list_sessions", "api_mode" = "async" },
       { "name" = "async_create_session", "api_mode" = "async" },
       { "name" = "async_delete_session", "api_mode" = "async" },
       { "name" = "async_add_session_to_memory", "api_mode" = "async" },
       { "name" = "async_search_memory", "api_mode" = "async" },
       { "name" = "stream_query", "api_mode" = "stream" },
       { "name" = "async_stream_query", "api_mode" = "async_stream" },
       { "name" = "streaming_agent_run_with_events", "api_mode" = "async_stream" }
     ]
   }
   
   # Grant Artifact Registry Reader permission to the Agent Runtime Service Agent
   resource "google_project_iam_member" "re_service_agent_ar_reader" {
     project = var.project_id
     role    = "roles/artifactregistry.reader"
     member  = "serviceAccount:service-${var.project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"
   }
   
   # Define the Agent Runtime resource with BYOC container configuration
   resource "google_vertex_ai_reasoning_engine" "byoc_weather_agent" {
     display_name = "byoc_weather_agent_tf"
     description  = "BYOC weather agent deployed using Terraform"
     project      = var.project_id
     region       = var.location
   
     spec {
       agent_framework = "google-adk"
   
       container_spec {
         image_uri = "${var.location}-docker.pkg.dev/${var.project_id}/${var.repository_name}/weather-agent-image:${var.image_tag}"
       }
   
       class_methods = jsonencode(local.class_methods)
     }
   
     # Ensure service agent permission exists before provisioning to prevent IMAGE_PULL_BACKOFF
     depends_on = [google_project_iam_member.re_service_agent_ar_reader]
   }
   

   Output resource (terraform/outputs.tf)

   output "reasoning_engine_id" {
     value       = google_vertex_ai_reasoning_engine.byoc_weather_agent.id
     description = "The ID of the deployed Agent Runtime instance"
   }
   
   output "reasoning_engine_resource_name" {
     value       = google_vertex_ai_reasoning_engine.byoc_weather_agent.name
     description = "The resource name of the deployed Agent Runtime instance"
   }
   

Men-deploy dari Dockerfile atau repositori sumber

Saat men-deploy dari Dockerfile, tentukan arsip sumber Anda di source_code_spec dan tetapkan blok image_spec {} kosong untuk menginstruksikan Agent Runtime agar membangun image container menggunakan Dockerfile Anda. Container yang dibangun dari Dockerfile Anda harus mematuhi kontrak runtime.

Untuk mengetahui detail selengkapnya tentang cara kerja deployment, lihat Men-deploy dari Dockerfile atau Men-deploy dari file sumber.

1. Kompres kode aplikasi (main.py), manifes dependensi Python (requirements.txt), dan petunjuk build container (Dockerfile) ke dalam arsip file tar yang di-gzip.

2. Jalankan perintah berikut dari direktori root aplikasi Anda (contoh menggunakan direktori root weather-agent-byoc/ dan arsip file tar weather_agent_source.tar.gz):

   cd weather-agent-byoc
   tar -czvf terraform/weather_agent_source.tar.gz main.py requirements.txt Dockerfile

   Catatan: File main.py, requirements.txt, dan Dockerfile harus berada langsung di tingkat root arsip file tar (tidak bertingkat di dalam direktori induk seperti weather-agent-byoc/main.py). Saat Agent Runtime menyediakan penampung build, Cloud Build API akan mengekstrak weather_agent_source.tar.gz langsung ke root ruang kerja build dan mengharapkan Dockerfile ada di ./Dockerfile selama kompilasi.

3. Buat file variables.tf, main.tf, dan outputs.tf di direktori terraform/ Anda:

   Variabel input (terraform/variables.tf)

   variable "project_id" {
     type        = string
     description = "The Google Cloud Project ID"
   }
   
   variable "location" {
     type        = string
     default     = "us-central1"
     description = "The region to deploy Agent Runtime"
   }
   

   Spesifikasi resource (terraform/main.tf)

   terraform {
     required_providers {
       google = {
         source  = "hashicorp/google"
         version = ">= 5.28.0"
       }
     }
   }
   
   provider "google" {
     project = var.project_id
     region  = var.location
   }
   
   resource "google_vertex_ai_reasoning_engine" "dockerfile_agent" {
     display_name = "dockerfile_weather_agent_tf"
     description  = "BYOC weather agent deployed using Dockerfile"
     project      = var.project_id
     region       = var.location
   
     spec {
       agent_framework = "google-adk"
   
       source_code_spec {
         inline_source {
           source_archive = filebase64("weather_agent_source.tar.gz")
         }
   
         # Empty image_spec instructs the runtime to build using the Dockerfile
         image_spec {}
       }
   
       class_methods = jsonencode([
         { "name" = "get_session", "api_mode" = "" },
         { "name" = "list_sessions", "api_mode" = "" },
         { "name" = "create_session", "api_mode" = "" },
         { "name" = "delete_session", "api_mode" = "" },
         { "name" = "async_get_session", "api_mode" = "async" },
         { "name" = "async_list_sessions", "api_mode" = "async" },
         { "name" = "async_create_session", "api_mode" = "async" },
         { "name" = "async_delete_session", "api_mode" = "async" },
         { "name" = "async_add_session_to_memory", "api_mode" = "async" },
         { "name" = "async_search_memory", "api_mode" = "async" },
         { "name" = "stream_query", "api_mode" = "stream" },
         { "name" = "async_stream_query", "api_mode" = "async_stream" },
         { "name" = "streaming_agent_run_with_events", "api_mode" = "async_stream" }
       ])
     }
   }
   

   Output resource (terraform/outputs.tf)

   output "dockerfile_agent_id" {
     value       = google_vertex_ai_reasoning_engine.dockerfile_agent.id
     description = "Resource ID of the deployed Dockerfile agent"
   }
   

Men-deploy menggunakan spesifikasi paket Python

Jika agen Anda dibuat menggunakan objek Python SDK atau aplikasi yang di-pickle (seperti ADK, LangChain, atau agen Python kustom), Anda dapat menyiapkan agen yang diserialisasi (.pkl) dan konfigurasi dependensi (requirements.txt) di bucket Cloud Storage dan mereferensikannya menggunakan package_spec.

Untuk mengetahui detail selengkapnya tentang cara kerja deployment, lihat Men-deploy dari objek Python.

1. Jalankan skrip Python berikut untuk melakukan serialisasi agen Anda dan menyiapkan artefak deployment di Cloud Storage:

   import cloudpickle
   from google.adk.agents import Agent
   from google.cloud import storage
   from vertexai.agent_engines import AdkApp
   PROJECT_ID = "PROJECT_ID"
   BUCKET_NAME = "BUCKET_NAME"
   GCS_DIR = "agents/weather_agent"
   
   # 1. Define agent logic
   root_agent = Agent(
       model="gemini-3.1-flash-lite",
       name="weather_agent",
       description="Agent deployed using Terraform package_spec.",
   )
   local_app = AdkApp(agent=root_agent)
   
   # 2. Upload pickle to Cloud Storage
   storage_client = storage.Client(project=PROJECT_ID)
   bucket = storage_client.bucket(BUCKET_NAME)
   
   pkl_blob = bucket.blob(f"{GCS_DIR}/agent.pkl")
   with pkl_blob.open("wb") as f:
       cloudpickle.dump(local_app, f)
   
   # 3. Upload requirements.txt
   requirements_content = """google-cloud-aiplatform[agent_engines,adk]>=1.144
   cloudpickle==3.0.0
   """
   req_blob = bucket.blob(f"{GCS_DIR}/requirements.txt")
   req_blob.upload_from_string(requirements_content)
   
   print(f"Artifacts uploaded to gs://{BUCKET_NAME}/{GCS_DIR}/")
   

2. Buat file variables.tf, main.tf, dan outputs.tf di direktori terraform/ Anda dengan mereferensikan URI Cloud Storage yang di-stage:

   Variabel input (terraform/variables.tf)

   variable "project_id" {
     type        = string
     description = "The Google Cloud Project ID"
   }
   
   variable "location" {
     type        = string
     default     = "us-central1"
     description = "The region to deploy Agent Runtime"
   }
   
   variable "bucket_name" {
     type        = string
     description = "Cloud Storage bucket name containing agent artifacts"
   }
   

   Spesifikasi resource (terraform/main.tf)

   terraform {
     required_providers {
       google = {
         source  = "hashicorp/google"
         version = ">= 5.28.0"
       }
     }
   }
   
   provider "google" {
     project = var.project_id
     region  = var.location
   }
   
   resource "google_vertex_ai_reasoning_engine" "package_agent" {
     display_name = "weather_agent_package_tf"
     description  = "Agent Runtime instance deployed using package_spec"
     project      = var.project_id
     region       = var.location
   
     spec {
       agent_framework = "google-adk"
       package_spec {
         python_version        = "3.11"
         pickle_object_gcs_uri = "gs://${var.bucket_name}/agents/weather_agent/agent.pkl"
         requirements_gcs_uri  = "gs://${var.bucket_name}/agents/weather_agent/requirements.txt"
       }
     }
   }
   

   Output resource (terraform/outputs.tf)

   output "package_agent_id" {
     value       = google_vertex_ai_reasoning_engine.package_agent.id
     description = "Resource ID of the deployed package agent"
   }
   

Mengonfigurasi variabel lingkungan dan secret

Sebelum men-deploy, Anda dapat melampirkan akun layanan runtime kustom ke agen dan meneruskan variabel lingkungan (env) atau referensi Secret Manager (secret_env).

Contoh berikut mengonfigurasi variabel lingkungan (LOCATION, MODEL, MODEL_REGION) dan meneruskan kunci API secara aman dari Secret Manager ke akun layanan runtime melalui file terraform/main.tf:

# 1. Dedicated Runtime Service Account
resource "google_service_account" "agent_runtime_sa" {
  account_id   = "agent-runtime-sa"
  display_name = "Agent Runtime Identity"
  project      = var.project_id
}

# 2. Secret Manager Secret for Agent Credentials
resource "google_secret_manager_secret" "api_key_secret" {
  secret_id = "agent-api-key"
  project   = var.project_id

  replication {
    auto {}
  }
}

resource "google_secret_manager_secret_version" "api_key_version" {
  secret      = google_secret_manager_secret.api_key_secret.id
  secret_data = var.api_key_value
}

# Grant Secret Accessor role to Runtime Service Account
resource "google_secret_manager_secret_iam_member" "secret_accessor" {
  secret_id = google_secret_manager_secret.api_key_secret.id
  role      = "roles/secretmanager.secretAccessor"
  member    = "serviceAccount:${google_service_account.agent_runtime_sa.email}"
}

# Grant Artifact Registry Reader permission to the Agent Runtime Service Agent
resource "google_project_iam_member" "re_service_agent_ar_reader" {
  project = var.project_id
  role    = "roles/artifactregistry.reader"
  member  = "serviceAccount:service-${var.project_number}@gcp-sa-aiplatform-re.iam.gserviceaccount.com"
}

# 3. Agent Runtime Resource with Environment Variables and Secret References
resource "google_vertex_ai_reasoning_engine" "advanced_weather_agent" {
  display_name = "byoc_weather_agent_advanced_tf"
  description  = "BYOC weather agent with custom service account and secrets"
  project      = var.project_id
  location     = var.location

  spec {
    agent_framework = "google-adk"
    service_account = google_service_account.agent_runtime_sa.email

    container_spec {
      image_uri = "${var.location}-docker.pkg.dev/${var.project_id}/${var.repository_name}/weather-agent-image:${var.image_tag}"
    }

    deployment_spec {
      env {
        name  = "LOCATION"
        value = var.location
      }
      env {
        name  = "MODEL"
        value = "gemini-3.1-flash-lite"
      }
      env {
        name  = "MODEL_REGION"
        value = "global"
      }

      secret_env {
        name = "API_KEY"
        secret_ref {
          secret  = google_secret_manager_secret.api_key_secret.secret_id
          version = "latest"
        }
      }
    }

    class_methods = jsonencode([
      { "name" = "get_session", "api_mode" = "" },
      { "name" = "create_session", "api_mode" = "" },
      { "name" = "stream_query", "api_mode" = "stream" },
      { "name" = "async_stream_query", "api_mode" = "async_stream" }
    ])
  }

  depends_on = [
    google_secret_manager_secret_iam_member.secret_accessor,
    google_project_iam_member.re_service_agent_ar_reader
  ]
}

Mengonfigurasi Agent Gateway

Untuk merutekan traffic antara Agent Runtime dan API atau klien eksternal melalui Agent Gateway, konfigurasi blok agent_gateway_config di dalam deployment_spec menggunakan penyedia google-beta.

Catatan: Saat mendeklarasikan agent_gateway_config, Anda harus menetapkan identity_type = "AGENT_IDENTITY" di spec. Men-deploy agen dengan agent_gateway_config tanpa menyetel identity_type = "AGENT_IDENTITY" akan menyebabkan validasi resource gagal.

Untuk mengetahui contoh deployment lengkap dan detail parameter untuk perutean Agent-to-Anywhere (keluar) dan Client-to-Agent (masuk), lihat Merutekan traffic Runtime melalui Agent Gateway.

Eksekusi dan siklus proses

Jalankan siklus proses Terraform standar untuk merencanakan, men-deploy, memanggil, dan menghancurkan resource agen Anda.

Terapkan konfigurasi Terraform

Deploy agen Anda dengan menerapkan konfigurasi Terraform:

1. Beralihlah ke direktori Terraform Anda (misalnya, cd weather-agent-byoc/terraform):

   cd weather-agent-byoc/terraform

2. Lakukan inisialisasi direktori kerja:

   terraform init

3. Lihat pratinjau rencana deployment:

   terraform plan -var="project_id=PROJECT_ID" -var="project_number=PROJECT_NUMBER"

4. Terapkan konfigurasi untuk menyediakan agen:

   terraform apply -var="project_id=PROJECT_ID" -var="project_number=PROJECT_NUMBER"

Mengkueri agen yang di-deploy

Setelah Terraform menyediakan resource google_vertex_ai_reasoning_engine, kirim permintaan POST HTTP ke endpoint :streamQuery?alt=sse untuk melakukan streaming peristiwa respons secara real time menggunakan Peristiwa yang Dikirim Server (SSE):

Catatan: Untuk metode kueri tambahan, lihat Menggunakan agen ADK.

LOCATION="LOCATION"
PROJECT_ID="PROJECT_ID"
REASONING_ENGINE_ID="REASONING_ENGINE_ID"
curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d '{
    "class_method": "async_stream_query",
    "input": {
      "user_id": "terraform_test_user",
      "message": "What is the temperature in Seattle?"
    }
  }' \
  "https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/reasoningEngines/${REASONING_ENGINE_ID}:streamQuery?alt=sse"

• Token Akses OAuth: Authorization: Bearer $(gcloud auth print-access-token) menghasilkan token akses OAuth 2.0 berumur pendek menggunakan kredensial Google Cloud lokal Anda.
• Envelope input JSON: Isi permintaan memerlukan payload JSON yang berisi objek input. Saat memanggil metode class eksplisit (seperti async_stream_query), sertakan parameter "class_method" bersama dengan "input".
• Payload respons: Respons dikirimkan secara berkelanjutan sebagai potongan Peristiwa yang Dikirim Server (SSE) data: { ... }.

Menghancurkan resource agen

Untuk membersihkan resource dan mencegah tagihan yang tidak terduga, beralihlah ke direktori terraform/ (misalnya, cd weather-agent-byoc/terraform) dan jalankan terraform destroy:

cd weather-agent-byoc/terraform
terraform destroy -var="project_id=PROJECT_ID" -var="project_number=PROJECT_NUMBER"

Langkah berikutnya

• Merutekan traffic Runtime melalui Agent Gateway
• HashiCorp Terraform Registry — google_vertex_ai_reasoning_engine (GA)
• HashiCorp Terraform Registry — google_vertex_ai_reasoning_engine (Beta)
• Google Cloud Generative AI — Agent Runtime Terraform Deployment Tutorial (GitHub)
• Forum Developer Google — Deploy Your Agent Runtime with Terraform the Enterprise Way