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 resmi Google Cloud (penyedia GA atau penyedia Beta).

Petunjuk di halaman ini sesuai dengan implementasi agen dalam container contoh yang dijelaskan dalam codelab Men-deploy agen dalam container 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 HashiCorp Terraform Registry resmi 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 Google Cloud kredensial:

   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 FastAPI atau Aplikasi ADK), dependensi Python, dan petunjuk build container.

   • 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 Agent Runtime dan nama resource lengkap, setelah deployment.

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

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

     Klik untuk melihat izin yang diperlukan

     • Vertex AI User (roles/aiplatform.user) atau Vertex AI Administrator (roles/aiplatform.admin): Mengotorisasi deployer untuk menjalankan operasi RPC Control Plane Agent Runtime (CreateReasoningEngine, UpdateReasoningEngine, DeleteReasoningEngine).
     • Service Account User (roles/iam.serviceAccountUser): Diberikan pada akun layanan runtime kustom (google_service_account.agent_runtime_sa) yang dilampirkan ke agen. Mengotorisasi 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 penahapan paket Python (package_spec) untuk mengupload atau membaca pickle agen serial (agent.pkl) dan manifes dependensi di Cloud Storage.
     • Artifact Registry Writer (roles/artifactregistry.writer): Diperlukan saat membangun dan mengirim 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): Memberikan izin infrastruktur platform Agent Runtime latar belakang 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 mungkin gagal dengan IMAGE_PULL_BACKOFF karena kondisi race.

Mempersiapkan deployment

Terraform mendukung jalur deployment berikut untuk Agent Runtime:

• Men-deploy dari image container bawaan: Bangun dan kirim image container ke Artifact Registry ({region}-docker.pkg.dev/...) dan 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.
• Men-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 Deploy menggunakan (package_spec) yang ditahapkan 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 membangun dan mengirim image container ke Artifact Registry (misalnya, untuk menyertakan library sistem kustom, mengoptimalkan performa cold start, atau menerapkan kontrol build image organisasi), Anda dapat men-deploy menggunakan container_spec. Untuk mengetahui detail persyaratan image, lihat Men-deploy dari Image Container.

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

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

   # 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
     location     = 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 membangun image container menggunakan Dockerfile Anda. Container yang dibangun dari Dockerfile Anda harus mematuhi runtime contract.

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 ini 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 berada di dalam direktori induk seperti weather-agent-byoc/main.py). Saat Agent Runtime menyediakan container 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
     location     = 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 dibangun menggunakan objek Python SDK atau aplikasi yang di-pickle (seperti ADK, LangChain, atau agen Python kustom), Anda dapat menahapkan agen serial (.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 membuat serial agen Anda dan menahapkan 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 yang mereferensikan URI Cloud Storage yang ditahapkan:

   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
     location     = 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 deployment, 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
  ]
}

Eksekusi dan siklus proses

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

Menerapkan konfigurasi Terraform

Deploy agen Anda dengan menerapkan konfigurasi Terraform:

1. Ubah 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 Server-Sent Events (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 lokal Anda. Google Cloud
• Amplop 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 terus-menerus sebagai bagian Server-Sent Event (SSE) data: { ... }.

Menghancurkan resource agen

Untuk membersihkan resource dan mencegah tagihan yang tidak terduga, ubah ke direktori terraform/ Anda (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

• HashiCorp Terraform Registry — google_vertex_ai_reasoning_engine (GA)
• HashiCorp Terraform Registry — google_vertex_ai_reasoning_engine (Beta)
• Google Cloud AI Generatif — Tutorial Deployment Terraform Agent Runtime (GitHub)
• Forum Developer Google — Men-deploy Agent Runtime dengan Terraform untuk Perusahaan