Eseguire il provisioning degli agenti con Terraform

Puoi utilizzare Terraform per eseguire il provisioning e gestire le istanze di Agent Runtime in modo dichiarativo. Quando esegui il deployment degli agenti con Terraform, gestisci la risorsa google_vertex_ai_reasoning_engine utilizzando il Google Cloud provider Terraform ufficiale (provider GA o provider beta).

Le istruzioni riportate in questa pagina corrispondono all'implementazione di esempio dell'agente containerizzato descritta nel codelab Esegui il deployment di un agente containerizzato con Agent Runtime.

Prerequisiti

Prima di utilizzare Terraform per eseguire il deployment di un agente, assicurati di aver completato la seguente configurazione:

  1. Installa Terraform (versione 1.5.0 o successive) ed esamina la documentazione ufficiale del registro Terraform di HashiCorp per la risorsa google_vertex_ai_reasoning_engine (provider GA e provider beta).
  2. Configura il tuo Google Cloud ambiente e abilita l'API Vertex AI (aiplatform.googleapis.com), l'API Artifact Registry (artifactregistry.googleapis.com) e l'API Cloud Build (cloudbuild.googleapis.com).

  3. Autentica il tuo ambiente locale utilizzando le credenziali Google Cloud :

    gcloud auth application-default login

  4. Per mantenere il codice dell'applicazione separato dalla gestione dell'infrastruttura, organizza lo spazio di lavoro dell'agente in directory dedicate all'applicazione e a Terraform:

    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 dell'applicazione (main.py, requirements.txt, Dockerfile): contengono la logica dell'agente, il wrapper del framework web (come FastAPI o ADK App), le dipendenze Python e le istruzioni di compilazione del container.

    • Directory Terraform (terraform/): contiene tutti i file di configurazione Terraform utilizzati per il provisioning delle risorse:

      • variables.tf: dichiara le variabili di input come project_id, location, repository_name e image_tag.
      • main.tf: dichiara le impostazioni del provider, le variabili locali, le associazioni di ruolo IAM e le specifiche delle risorse google_vertex_ai_reasoning_engine.
      • outputs.tf: Esporta gli attributi delle risorse di cui è stato eseguito il provisioning, come l'ID runtime dell'agente e il nome completo della risorsa, dopo il deployment.

  5. Concedi i ruoli IAM appropriati a seconda di chi esegue il deployment:

    • Account di servizio di sviluppatore umano o CI/CD che esegue terraform apply e comandi di build locali.

    • Service agent di Agent Runtime gestito dal sistema (service-<var>PROJECT_NUMBER</var>@gcp-sa-aiplatform-re.iam.gserviceaccount.com).

Prepararsi al deployment

Terraform supporta i seguenti percorsi di deployment per Agent Runtime:

  • Esegui il deployment dall'immagine container predefinita: crea ed esegui il push di un'immagine container in Artifact Registry ({region}-docker.pkg.dev/...) ed esegui il deployment utilizzando container_spec. Utilizza questo metodo quando hai bisogno del controllo completo sul processo di compilazione del container, di immagini di base personalizzate o di una latenza di deployment inferiore.
  • Esegui il deployment dai file di origine o da Dockerfile: esegui il deployment dell'agente direttamente dai file di origine locali o da un Dockerfile. Agent Runtime crea e esegue il provisioning dell'immagine container automaticamente senza richiedere la gestione manuale delle immagini.
  • Esegui il deployment utilizzando le specifiche del pacchetto Python Esegui il deployment utilizzando (package_spec) sottoposto a staging in Cloud Storage. Agent Runtime crea e esegue il provisioning dell'immagine container automaticamente senza richiedere la gestione manuale delle immagini.

Esegui il deployment da un'immagine container predefinita

Se pre-crei ed esegui il push delle immagini container in Artifact Registry (ad esempio per includere librerie di sistema personalizzate, ottimizzare le prestazioni di avvio a freddo o applicare controlli di creazione delle immagini organizzative), puoi eseguire il deployment utilizzando container_spec. Per informazioni dettagliate sui requisiti delle immagini, consulta Deployment da immagine container.

Le immagini container devono essere archiviate in Artifact Registry ({LOCATION}-docker.pkg.dev/{PROJECT_ID}/{REPOSITORY}/{IMAGE}:{TAG}), ascoltare sulla porta 8080 (o su una porta personalizzata specificata in container_spec) e rispettare il contratto di runtime.

  1. Crea l'immagine container localmente ed eseguine il push nel repository 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. Configura l'immagine container predefinita per il deployment di Terraform. La seguente configurazione mostra il deployment di un'immagine container predefinita ospitata in Artifact Registry creando i file variables.tf, main.tf e outputs.tf nella directory terraform/:

    Variabili di 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"
}

    Specifiche delle risorse (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 delle risorse (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"
}

Esegui il deployment da Dockerfile o dal repository di origine

Quando esegui il deployment da un Dockerfile, specifica l'archivio di origine in source_code_spec e imposta un blocco image_spec {} vuoto per indicare ad Agent Runtime di creare l'immagine container utilizzando il Dockerfile. Il container creato dal Dockerfile deve rispettare il contratto di runtime.

Per ulteriori dettagli sul funzionamento del deployment, consulta Eseguire il deployment da Dockerfile o Eseguire il deployment dai file sorgente.

  1. Comprimi il codice dell'applicazione (main.py), il manifest delle dipendenze Python (requirements.txt) e le istruzioni di compilazione del container (Dockerfile) in un archivio tar compresso con gzip.

  2. Esegui questo comando dalla directory principale dell'applicazione (l'esempio utilizza la directory principale weather-agent-byoc/ e l'archivio dei file tar weather_agent_source.tar.gz):

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

  3. Crea i file variables.tf, main.tf e outputs.tf nella directory terraform/:

    Variabili di 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"
}

    Specifiche delle risorse (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 delle risorse (terraform/outputs.tf)

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

Esegui il deployment utilizzando la specifica del pacchetto Python

Se l'agente è creato utilizzando oggetti Python SDK o applicazioni serializzate (ad esempio ADK, LangChain o agenti Python personalizzati), puoi preparare l'agente serializzato (.pkl) e la configurazione delle dipendenze (requirements.txt) in un bucket Cloud Storage e farvi riferimento utilizzando package_spec.

Per maggiori dettagli su come funziona il deployment, consulta Esegui il deployment dall'oggetto Python.

  1. Esegui il seguente script Python per serializzare l'agente e preparare gli artefatti di deployment in 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. Crea i file variables.tf, main.tf e outputs.tf nella directory terraform/ facendo riferimento agli URI Cloud Storage di staging:

    Variabili di 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"
}
    Specifiche delle risorse (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 delle risorse (terraform/outputs.tf)
    output "package_agent_id" {
  value       = google_vertex_ai_reasoning_engine.package_agent.id
  description = "Resource ID of the deployed package agent"
}

Configura le variabili di ambiente e i secret

Prima del deployment, puoi collegare un account di servizio di runtime personalizzato al tuo agente e passare variabili di ambiente (env) o riferimenti a Secret Manager (secret_env).

L'esempio seguente configura le variabili di ambiente (LOCATION, MODEL, MODEL_REGION) e trasmette in modo sicuro una chiave API da Secret Manager all'account di servizio di runtime tramite il 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
  ]
}

Configura Agent Gateway

Per instradare il traffico tra Agent Runtime e API o client esterni tramite Agent Gateway, configura il blocco agent_gateway_config all'interno di deployment_spec utilizzando il provider google-beta.

Per esempi di deployment completi e dettagli sui parametri per il routing da agente a ovunque (in uscita) e da client ad agente (in entrata), consulta Instradare il traffico di runtime tramite Agent Gateway.

Esecuzione e ciclo di vita

Esegui il ciclo di vita standard di Terraform per pianificare, eseguire il deployment, richiamare ed eliminare le risorse dell'agente.

Applica la configurazione Terraform

Esegui il deployment dell'agente applicando la configurazione Terraform:

  1. Passa alla directory Terraform (ad esempio, cd weather-agent-byoc/terraform):

    cd weather-agent-byoc/terraform

  2. Inizializza la directory di lavoro:

    terraform init

  3. Visualizza l'anteprima del piano di deployment:

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

  4. Applica la configurazione per eseguire il provisioning dell'agente:

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

Esegui query sull'agente di cui è stato eseguito il deployment

Dopo che Terraform ha eseguito il provisioning della risorsa google_vertex_ai_reasoning_engine, invia una richiesta HTTP POST all'endpoint :streamQuery?alt=sse per trasmettere in streaming gli eventi di risposta in tempo reale utilizzando Server-Sent Events (SSE):

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 di accesso OAuth: Authorization: Bearer $(gcloud auth print-access-token) genera un token di accesso OAuth 2.0 di breve durata utilizzando le tue credenziali Google Cloud locali.
  • Busta input JSON: il corpo della richiesta richiede un payload JSON contenente un oggetto input. Quando chiami metodi di classe espliciti (ad esempio async_stream_query), includi il parametro "class_method" insieme a "input".
  • Payload di risposta: le risposte vengono inviate continuamente come blocchi di data: { ... } Server-Sent Event (SSE).

Elimina le risorse dell'agente

Per liberare spazio dalle risorse ed evitare addebiti imprevisti, passa alla directory terraform/ (ad esempio, cd weather-agent-byoc/terraform) ed esegui terraform destroy:

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

Passaggi successivi