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 provider Terraform ufficiale ( Google Cloud 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 HashiCorp Terraform per la risorsa google_vertex_ai_reasoning_engine (provider GA e provider beta).
  2. Configura l'ambiente Google Cloud 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 l'area di lavoro dell'agente in directory dedicate per l'applicazione e 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 l'app ADK), le dipendenze Python e le istruzioni di build del container.

    • Directory Terraform (terraform/): contiene tutti i file di configurazione di Terraform utilizzati per eseguire 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 dei ruoli 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 Agent Runtime e il nome completo della risorsa, dopo il deployment.

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

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

    • Agente di servizio Agent Runtime gestito dal sistema (service-<var>PROJECT_NUMBER</var>@gcp-sa-aiplatform-re.).

Prepararsi al deployment

Terraform supporta i seguenti percorsi di deployment per Agent Runtime:

  • Esegui il deployment da un'immagine container predefinita: crea un'immagine container, eseguine il push ad Artifact Registry ({region}-docker.pkg.dev/...) ed esegui il deployment utilizzando container_spec. Utilizza questo metodo se hai bisogno di un controllo completo sul processo di compilazione dei container, su immagini di base personalizzate o su una latenza di deployment inferiore.
  • Esegui il deployment da file di origine o Dockerfile: esegui il deployment dell'agente direttamente da file di origine locali o da un Dockerfile. Agent Runtime crea ed 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) in gestione temporanea in Cloud Storage. Agent Runtime crea ed 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 dell'organizzazione), puoi eseguire il deployment utilizzando container_spec. Per informazioni dettagliate sui requisiti delle immagini, consulta Esegui il deployment da un'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."
}

# 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 repository di codice sorgente

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 maggiori dettagli sul funzionamento del deployment, consulta Esegui il deployment da Dockerfile o Esegui il deployment dai file di codice sorgente.

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

  2. Esegui questo comando dalla directory root dell'applicazione (l'esempio utilizza la directory root weather-agent-byoc/ e l'archivio di 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 SDK Python o applicazioni con pickle (come ADK, LangChain o agenti Python personalizzati), puoi eseguire lo stage dell'agente serializzato (.pkl) e della 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 cui è stato eseguito lo stage:

    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 passa una chiave API in modo sicuro da Secret Manager al 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."
}

# 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 le API o i client esterni tramite Agent Gateway, configura il blocco agent_gateway_config all'interno di deployment_spec utilizzando il provider google-beta.

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

Governance del gateway centrale multiprogetto

Nelle architetture aziendali multi-progetto, puoi gestire un progetto di governance centrale che ospita Agent Gateway, Agent Registry e Model Armor, eseguendo al contempo il deployment dei workload di runtime in cartelle di progetto separate all'interno della tua organizzazione utilizzando Terraform:

  • Agent Gateway centrale e policy di autorizzazione: esegui il provisioning di google_network_services_agent_gateway, google_network_services_authz_extension e google_network_security_authz_policy nel progetto di governance centrale. Consulta Configura Agent Gateway.
  • Accesso dell'agente di servizio tra progetti: concedi ar_agw_cross_project_sa (google_project_iam_custom_role) nel progetto gateway centrale all'agente di servizio di runtime di ogni progetto di workload utilizzando google_project_iam_member. Consulta Instrada il traffico di runtime tramite Agent Gateway.
  • Registry centrale e policy in uscita: registra agenti e strumenti tra progetti nel registry del progetto centrale utilizzando google_agent_registry_service e concedi roles/iap.egressor con risorse google_iap_agent_registry_*. Consulta Crea policy degli agenti IAM.
  • Modelli e impostazioni di base di Model Armor: applica le soglie di sicurezza alla tua organizzazione o alle tue cartelle con google_model_armor_floorsetting e google_model_armor_template. Consulta Delega l'autorizzazione a Model Armor.

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 JSON input: il corpo della richiesta richiede un payload JSON contenente un oggetto input. Quando chiami metodi di classe espliciti (come async_stream_query), includi il parametro "class_method" insieme a "input".
  • Payload della risposta: le risposte vengono inviate continuamente sotto forma di blocchi di Server-Sent Event (SSE) data: { ... }.

Elimina le risorse dell'agente

Per eseguire la pulizia delle risorse ed evitare addebiti di fatturazione 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