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 Google Cloud Terraform ufficiale (provider GA o provider beta).

Le istruzioni riportate in questa pagina corrispondono all'implementazione dell'agente containerizzato di esempio descritta nel codelab Eseguire 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) e consulta 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 Google Cloud le credenziali:

    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 ADK App), le dipendenze Python e le istruzioni di creazione 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 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 di 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 i comandi terraform apply e di build locale.

    • 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 da un'immagine container predefinita: pre-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, sulle 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 e esegue automaticamente il provisioning dell'immagine container senza richiedere la gestione manuale delle immagini.
  • Esegui il deployment utilizzando le specifiche del pacchetto Python utilizzando (package_spec) la gestione temporanea in Cloud Storage. Agent Runtime crea e esegue automaticamente il provisioning dell'immagine container 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 i controlli di creazione delle immagini dell'organizzazione), puoi eseguire il deployment utilizzando container_spec. Per informazioni dettagliate sui requisiti delle immagini, consulta Eseguire il deployment da un'immagine container.

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

  1. Crea l'immagine container localmente ed esegui 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
  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 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 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 maggiori dettagli su come funziona il deployment, consulta Eseguire il deployment da Dockerfile o Eseguire il deployment da file di origine.

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

  2. Esegui il comando seguente dalla directory principale dell'applicazione (l'esempio utilizza la directory principale 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
  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 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 la gestione temporanea 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 Eseguire il deployment da un oggetto Python.

  1. Esegui il seguente script Python per serializzare l'agente e gestire temporaneamente 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 temporanei:

    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
  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 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 le variabili di ambiente (env) o i 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.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
  ]
}

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 esegue 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 credenziali locali Google Cloud .
  • 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 di risposta: le risposte vengono inviate continuamente come blocchi di eventi inviati dal server (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