Agents mit Terraform bereitstellen

Sie können Terraform verwenden, um Agent Runtime-Instanzen deklarativ bereitzustellen und zu verwalten. Wenn Sie Agents mit Terraform bereitstellen, verwalten Sie die google_vertex_ai_reasoning_engine Ressource mit dem offiziellen Google Cloud Terraform-Provider (GA-Provider oder Beta-Provider).

Die Anleitung auf dieser Seite entspricht der Beispielimplementierung eines containerisierten Agents, die im Codelab Containerisierten Agenten mit Agent Runtime bereitstellen beschrieben wird.

Vorbereitung

Bevor Sie einen Agent mit Terraform bereitstellen, müssen Sie die folgenden Schritte ausführen:

  1. Installieren Sie Terraform (Version 1.5.0 oder höher) und lesen Sie die offizielle HashiCorp Terraform Registry-Dokumentation für die Ressource google_vertex_ai_reasoning_engine (GA-Provider und Beta-Provider).
  2. Richten Sie Ihre Google Cloud Umgebung ein und aktivieren Sie die Vertex AI API (aiplatform.googleapis.com), die Artifact Registry API (artifactregistry.googleapis.com) und die Cloud Build API (cloudbuild.googleapis.com).

  3. Authentifizieren Sie Ihre lokale Umgebung mit Google Cloud Anmeldedaten:

    gcloud auth application-default login

  4. Um Ihren Anwendungscode von der Infrastrukturverwaltung zu trennen, organisieren Sie Ihren Agent-Arbeitsbereich in dedizierten Anwendungs- und Terraform-Verzeichnissen:

    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

    • Anwendungsdateien (main.py, requirements.txt, Dockerfile): enthalten Ihre Agent-Logik, Web-Framework-Wrapper (z. B. FastAPI oder ADK App), Python-Abhängigkeiten und Anweisungen zum Erstellen von Containern.

    • Terraform-Verzeichnis (terraform/): enthält alle Terraform-Konfigurationsdateien, die zum Bereitstellen von Ressourcen verwendet werden:

      • variables.tf: deklariert Eingabevariablen wie project_id, location, repository_name und image_tag.
      • main.tf: deklariert Provider-Einstellungen, lokale Variablen, IAM-Rollenbindungen und Spezifikationen für die Ressource google_vertex_ai_reasoning_engine.
      • outputs.tf: exportiert nach der Bereitstellung Attribute der bereitgestellten Ressource, z. B. die Agent Runtime-ID und den vollständigen Ressourcennamen.

  5. Weisen Sie die entsprechenden IAM-Rollen zu, je nachdem, wer die Bereitstellung ausführt:

    • Menschlicher Entwickler oder CI/CD-Dienstkonto, der terraform apply und lokale Build-Befehle ausführt.

    • Vom System verwalteter Agent Runtime-Dienst-Agent (service-<var>PROJECT_NUMBER</var>@gcp-sa-aiplatform-re.iam.gserviceaccount.com).

Bereitstellung vorbereiten

Terraform unterstützt die folgenden Bereitstellungspfade für Agent Runtime:

  • Aus einem vorkonfigurierten Container-Image bereitstellen: Erstellen Sie ein Container-Image vorab und übertragen Sie es per Push in Artifact Registry ({region}-docker.pkg.dev/...) und stellen Sie es mit container_spec bereit. Verwenden Sie diese Methode, wenn Sie die vollständige Kontrolle über den Container-Build-Prozess, benutzerdefinierte Basis-Images oder eine geringere Bereitstellungslatenz benötigen.
  • Aus Quelldateien oder Dockerfile bereitstellen: Stellen Sie Ihren Agent direkt aus lokalen Quelldateien oder einem Dockerfile bereit. Agent Runtime erstellt und stellt das Container-Image automatisch bereit, ohne dass eine manuelle Image-Verwaltung erforderlich ist.
  • Mit Python-Paketspezifikationen bereitstellen: Stellen Sie mit (package_spec) bereit, das in Cloud Storage bereitgestellt wird. Agent Runtime erstellt und stellt das Container-Image automatisch bereit, ohne dass eine manuelle Image-Verwaltung erforderlich ist.

Aus einem vorkonfigurierten Container-Image bereitstellen

Wenn Sie Container-Images vorab erstellen und per Push in Artifact Registry übertragen (z. B. um benutzerdefinierte Systembibliotheken einzufügen, die Leistung beim Kaltstart zu optimieren oder Image-Build-Steuerungen für die Organisation zu erzwingen), können Sie die Bereitstellung mit container_spec durchführen. Weitere Informationen zu den Image-Anforderungen finden Sie unter Aus Container-Image bereitstellen.

Container-Images müssen in Artifact Registry gespeichert werden ({LOCATION}-docker.pkg.dev/{PROJECT_ID}/{REPOSITORY}/{IMAGE}:{TAG}), auf Port 8080 (oder einem benutzerdefinierten Port, der in container_spec angegeben ist) ausgeführt werden und dem Laufzeitvertrag entsprechen.

  1. Erstellen Sie Ihr Container-Image lokal und übertragen Sie es per Push in Ihr Artifact Registry-Repository:

    # 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. Konfigurieren Sie Ihr vorkonfiguriertes Container-Image für die Terraform-Bereitstellung. Die folgende Konfiguration zeigt, wie Sie ein vorkonfiguriertes Container-Image bereitstellen, das in Artifact Registry gehostet wird. Dazu werden die Dateien variables.tf, main.tf und outputs.tf im Verzeichnis terraform/ erstellt:

    Eingabevariablen (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"
}

    Ressourcenspezifikationen (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]
}

    Ressourcenausgaben (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"
}

Aus Dockerfile oder Quell-Repository bereitstellen

Wenn Sie aus einem Dockerfile bereitstellen, geben Sie Ihr Quellarchiv in source_code_spec an und legen Sie einen leeren image_spec {}-Block fest, um Agent Runtime anzuweisen, das Container-Image mit Ihrem Dockerfile zu erstellen. Der aus Ihrem Dockerfile erstellte Container muss dem Laufzeit vertrag entsprechen.

Weitere Informationen zur Funktionsweise der Bereitstellung finden Sie unter Aus Dockerfile bereitstellen oder Aus Quelldateien bereitstellen.

  1. Komprimieren Sie Ihren Anwendungscode (main.py), das Python-Abhängigkeitsmanifest (requirements.txt) und die Anweisungen zum Erstellen von Containern (Dockerfile) in ein gezipptes Tar-Archiv.

  2. Führen Sie den folgenden Befehl im Stammverzeichnis Ihrer Anwendung aus. Im Beispiel wird das Stammverzeichnis weather-agent-byoc/ und das Tar-Archiv weather_agent_source.tar.gz verwendet:

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

  3. Erstellen Sie die Dateien variables.tf, main.tf und outputs.tf im Verzeichnis terraform/:

    Eingabevariablen (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"
}

    Ressourcenspezifikationen (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" }
    ])
  }
}

    Ressourcenausgaben (terraform/outputs.tf)

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

Mit Python-Paketspezifikation bereitstellen

Wenn Ihr Agent mit Python SDK-Objekten oder Pickled-Anwendungen (z. B. ADK, LangChain oder benutzerdefinierten Python-Agents) erstellt wurde, können Sie Ihren serialisierten Agent (.pkl) und die Abhängigkeitskonfiguration (requirements.txt) in einem Cloud Storage-Bucket bereitstellen und mit package_spec darauf verweisen.

Weitere Informationen zur Funktionsweise der Bereitstellung finden Sie unter Aus Python Objekt bereitstellen.

  1. Führen Sie das folgende Python-Skript aus, um Ihren Agent zu serialisieren und die Bereitstellungsartefakte in Cloud Storage bereitzustellen:

    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. Erstellen Sie die Dateien variables.tf, main.tf und outputs.tf im Verzeichnis terraform/ und verweisen Sie auf die bereitgestellten Cloud Storage-URIs:

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

Umgebungsvariablen und Secrets konfigurieren

Vor der Bereitstellung können Sie ein benutzerdefiniertes Dienstkonto der Laufzeitumgebung an Ihren Agent anhängen und Umgebungsvariablen (env) oder Secret Manager-Verweise (secret_env) übergeben.

Im folgenden Beispiel werden Umgebungsvariablen (LOCATION, MODEL, MODEL_REGION) konfiguriert und ein API-Schlüssel sicher über Secret Manager an das Dienstkonto der Laufzeitumgebung über die terraform/main.tf Datei übergeben:

# 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
  ]
}

Ausführung und Lebenszyklus

Führen Sie den Standard-Terraform-Lebenszyklus aus, um Ihre Agent-Ressourcen zu planen, bereitzustellen, aufzurufen und zu löschen.

Terraform-Konfiguration anwenden

Stellen Sie Ihren Agent bereit, indem Sie Ihre Terraform-Konfiguration anwenden:

  1. Wechseln Sie in Ihr Terraform-Verzeichnis (z. B. cd weather-agent-byoc/terraform):

    cd weather-agent-byoc/terraform

  2. Initialisieren Sie das Arbeitsverzeichnis:

    terraform init

  3. Sehen Sie sich eine Vorschau des Bereitstellungsplans an:

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

  4. Wenden Sie die Konfiguration an, um den Agent bereitzustellen:

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

Bereitgestellten KI-Agenten abfragen

Nachdem Terraform die Ressource google_vertex_ai_reasoning_engine bereitgestellt hat, senden Sie eine HTTP-POST-Anfrage an den Endpunkt :streamQuery?alt=sse, um Antwortereignisse in Echtzeit mit Server-Sent Events (SSE) zu streamen:

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"
  • OAuth-Zugriffstoken: Authorization: Bearer $(gcloud auth print-access-token) generiert ein kurzlebiges OAuth 2.0-Zugriffstoken mit Ihren lokalen Google Cloud Anmeldedaten.
  • JSON-input-Umschlag: Der Anfragetext erfordert eine JSON-Nutzlast mit einem input-Objekt. Wenn Sie explizite Klassenmethoden aufrufen (z. B. async_stream_query), fügen Sie neben "input" den Parameter "class_method" ein.
  • Antwortnutzlast: Antworten werden kontinuierlich als data: { ... } SSE-Chunks (Server-Sent Events) geliefert.

Agent-Ressourcen löschen

Wenn Sie Ressourcen bereinigen und unerwartete Abrechnungsgebühren vermeiden möchten, wechseln Sie in das Verzeichnis terraform/ (z. B. cd weather-agent-byoc/terraform) und führen Sie terraform destroy aus:

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

Nächste Schritte